Google Cloud Storage

Una fuente de Google Cloud Storage mantiene un bucket, o prefijos de él, en un namespace. Cada archivo se lee igual que una subida, y un archivo eliminado del bucket pierde sus documentos.

Concede acceso

Conare lee los buckets como una única cuenta de servicio de Google, así que no se intercambia ninguna clave. Concédele Storage Object Viewer y crea el objeto vacío .conare/<organization id>, que demuestra que el bucket es tuyo:

gcloud

gcloud storage buckets add-iam-policy-binding gs://acme-reports \
  --member=serviceAccount:conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com \
  --role=roles/storage.objectViewer
gcloud storage cp /dev/null gs://acme-reports/.conare/ORG_ID

Previsualiza el bucket

curl

curl https://api.conare.ai/sources/gcs/preview \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bucket": "acme-reports", "prefixes": ["2024/"]}'

Conéctalo

curl

curl https://api.conare.ai/sources \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "gcs", "namespace": "reports", "bucket": "acme-reports", "prefixes": ["2024/"]}'

La cuenta

GET /sources/gcs

Response

{
  "configured": true,
  "role": "roles/storage.objectViewer",
  "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com"
}

service_account, role: la cuenta y el rol que debes concederle en tu bucket.
Una fuente deja de sincronizarse cuando se elimina .conare/<organization id>; gcs_not_verified indica el objeto que hay que crear.

Esquema completo: The account to grant a bucket to.

Previsualizar un bucket

POST /sources/gcs/preview Lista lo que leería una fuente del bucket; no se almacena nada.

Response

{
  "bucket": "acme-reports",
  "bytes": 74,
  "complete": true,
  "objects": 2,
  "prefixes": ["2024/"],
  "sample": ["2024/prices.csv", "2024/site-7.txt"],
  "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com",
  "skipped": 0,
  "too_large": 0,
  "types": { "csv": 1, "txt": 1 },
  "unsupported": 0
}

Opción	Tipo	Qué hace
`bucket`	string, obligatorio	El nombre del bucket
`prefixes`	array	Hasta 20 prefijos, cada uno de hasta 1.024 caracteres; sin ninguno se lee todo el bucket

Campo	Significado
`objects`, `bytes`	Archivos que leería una fuente, y su tamaño
`types`	Archivos por tipo; `other` para aquellos cuyo tipo solo revelarán sus bytes
`skipped`, `unsupported`, `too_large`	Carpetas y objetos vacíos; archivos que Conare no lee; archivos de más de 512 MiB
`sample`	Hasta 20 nombres de archivo
`complete`	`false` cuando el bucket tenía más de 10.000 objetos o tardó más de 10 segundos en listarse

Esquema completo: Preview a bucket.

Conectar un bucket

Envía "type": "gcs" a POST /sources; la primera sincronización empieza de inmediato, y una clave limitada al namespace puede conectarlo.

Response

{
  "id": "src_4e4abfd7ac248dce3668ef76",
  "kind": "gcs",
  "type": "gcs",
  "namespace": "reports",
  "user": null,
  "name": "gs://acme-reports/2024/",
  "status": "active",
  "health": "ok",
  "display": { "state": "ok" },
  "sync": {
    "state": "queued",
    "run_id": null,
    "phase": null,
    "last_success_at": null,
    "last_failure_at": null,
    "next_run_at": "2026-10-21T22:41:44.768045Z",
    "last_error": null
  },
  "documents": 0,
  "documents_verified_at": null,
  "config": {
    "bucket": "acme-reports",
    "prefixes": ["2024/"],
    "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com",
    "sync_interval_s": 3600
  },
  "failures": 0,
  "created_at": "2026-10-21T21:41:44.768045Z",
  "updated_at": "2026-10-21T21:41:44.768045Z"
}

Opción	Tipo	Qué hace
`type`	string, obligatorio	`gcs`
`namespace`	string, obligatorio	El namespace en el que guardar los archivos
`bucket`	string, obligatorio	El nombre del bucket
`prefixes`	array	Hasta 20 prefijos, cada uno de hasta 1.024 caracteres
`name`	string	Un nombre visible, de hasta 200 caracteres; por defecto `gs://bucket/prefix`
`sync_interval_s`	integer, predeterminado 3600	Segundos entre sincronizaciones, de 900 a 604.800 (7 días)

Campo	Significado
`health`	`ok`; `degraded` cuando la última sincronización retuvo sus eliminaciones; `failing` cuando la cuenta perdió su permiso o fallaron las 3 últimas sincronizaciones
`sync`	`state` (`idle`, `queued` o `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error`
`documents`, `failures`	Documentos que mantiene, y archivos que no pudo mantener (más abajo)
`config`	El bucket, los prefijos, la cuenta y el intervalo

Sincronizar y desconectar

Acción	Ruta	Respuesta
Sincronizar ahora	`POST /sources/:id/sync`	`202` con el `run` de la sincronización, o `409 run_active` mientras haya una en cola o en curso
Desconectar	`DELETE /sources/:id`	`202` con el `run` que elimina sus documentos; la fuente pasa a `deleting` y luego a `deleted`

Cada sincronización lista el bucket y lee los archivos nuevos y modificados.
Una sincronización que eliminaría más de 1.000 documentos y una décima parte de la fuente espera 24 horas a que una segunda sincronización lo confirme.

Documentos

Cada archivo es un documento, con el id y las ubicaciones de una subida, además de source_url (gs://bucket/name), bucket, object y generation en sus metadatos.

{ "source_url": "gs://acme-reports/2024/prices.csv" }

GET /sources/:id/documents lista sus archivos.

Fallos

GET /sources/:id/failures

curl

curl https://api.conare.ai/sources/src_b805954930e968fe8d4a89f6/failures \
  -H "Authorization: Bearer $CONARE_API_KEY"

Response

{
  "data": [
    {
      "external_id": "gs://acme-reports/2024/minutes.pdf",
      "key": "minutes.pdf-69578779b32368c6",
      "version": "md5:0HKRGpcwGcvjCA5k1+5AFA==;type=pdf",
      "code": "type_mismatch",
      "message": "type_mismatch: the file is not the type declared: declared pdf, but the bytes are text",
      "run_id": "run_1a20d9cdd1b2092406b048ae",
      "attempts": 1,
      "failed_at": "2026-10-21T21:55:33.56975Z"
    }
  ],
  "next_cursor": null
}

Opción	Tipo	Qué hace
`limit`	integer, predeterminado 1000	Fallos por página, hasta 1.000
`cursor`	string	El `next_cursor` de la página anterior, `null` en la última página

`code`	Significado
`unsupported_file`	Conare no lee el tipo del archivo
`too_large`	Más de 512 MiB
`pages_unread`	El OCR no pudo leer las páginas que indica el mensaje; el resto se puede buscar
Otros	El error del análisis, como `type_mismatch` o `unreadable_file`

Un fallo nunca detiene una sincronización.
Un archivo que falló de forma definitiva solo se vuelve a leer cuando cambia.
Uno que falló por un motivo pasajero se reintenta en las 3 sincronizaciones siguientes, y después a diario.

Esquema completo: List the objects a source could not keep.

Errores

Error	Cuándo
`422 gcs_access_denied`	La cuenta no puede listar el bucket; el mensaje indica la cuenta y el rol
`422 gcs_not_verified`	El bucket no tiene `.conare/<organization id>`; el mensaje indica el objeto
`422 gcs_bucket_not_found`	No existe ningún bucket con ese nombre
`503 gcs_auth_failed`, `503 gcs_unavailable`	No se pudo contactar con Google Cloud Storage; reinténtalo después de `Retry-After`

Primeros pasos

Esenciales

Archivos

Sincronización

Modelos

Herramientas

Google Cloud Storage

La cuenta

Previsualizar un bucket

Conectar un bucket

Sincronizar y desconectar

Documentos

Fallos

Errores

​La cuenta

​Previsualizar un bucket

​Conectar un bucket

​Sincronizar y desconectar

​Documentos

​Fallos

​Errores

La cuenta

Previsualizar un bucket

Conectar un bucket

Sincronizar y desconectar

Documentos

Fallos

Errores