Google Cloud Storage

Uma fonte do Google Cloud Storage mantém um bucket, ou prefixos dele, em um namespace. Cada arquivo é lido como um upload, e um arquivo excluído do bucket perde seus documentos.

Conceder acesso

O Conare lê buckets como uma única conta de serviço do Google, então nenhuma chave muda de mãos. Conceda a ela o papel Storage Object Viewer e crie o objeto vazio .conare/<organization id>, que mostra que o bucket é seu:

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

Visualizar o 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/"]}'

Conectá-lo

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/"]}'

A conta

GET /sources/gcs

Response

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

service_account, role: a conta e o papel a conceder a ela no seu bucket.
Uma fonte para de sincronizar quando .conare/<organization id> é removido; gcs_not_verified indica o objeto a criar.

Schema completo: A conta à qual conceder um bucket.

Visualizar um bucket

POST /sources/gcs/preview Lista o que uma fonte do bucket leria; nada é armazenado.

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
}

Opção	Tipo	O que faz
`bucket`	string, obrigatório	O nome do bucket
`prefixes`	array	Até 20 prefixos, cada um com até 1.024 caracteres; sem nenhum, lê o bucket inteiro

Campo	Significado
`objects`, `bytes`	Arquivos que uma fonte leria e seu tamanho
`types`	Arquivos por tipo; `other` para aqueles cujo tipo só os bytes revelarão
`skipped`, `unsupported`, `too_large`	Pastas e objetos vazios; arquivos que o Conare não lê; arquivos acima de 512 MiB
`sample`	Até 20 nomes de arquivo
`complete`	`false` quando o bucket tinha mais de 10.000 objetos ou levou mais de 10 segundos para ser listado

Schema completo: Visualizar um bucket.

Conectar um bucket

Envie "type": "gcs" para POST /sources; a primeira sincronização começa imediatamente, e uma chave restrita ao namespace pode conectá-lo.

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"
}

Opção	Tipo	O que faz
`type`	string, obrigatório	`gcs`
`namespace`	string, obrigatório	O namespace onde manter os arquivos
`bucket`	string, obrigatório	O nome do bucket
`prefixes`	array	Até 20 prefixos, cada um com até 1.024 caracteres
`name`	string	Um nome de exibição, até 200 caracteres; o padrão é `gs://bucket/prefix`
`sync_interval_s`	integer, padrão 3600	Segundos entre sincronizações, de 900 a 604.800 (7 dias)

Campo	Significado
`health`	`ok`; `degraded` quando a última sincronização reteve suas exclusões; `failing` quando a conta perdeu sua permissão ou as 3 últimas sincronizações falharam
`sync`	`state` (`idle`, `queued` ou `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error`
`documents`, `failures`	Documentos que ela mantém e arquivos que não conseguiu manter (abaixo)
`config`	O bucket, os prefixos, a conta e o intervalo

Sincronizar e desconectar

Ação	Rota	Resposta
Sincronizar agora	`POST /sources/:id/sync`	`202` com o `run` da sincronização, ou `409 run_active` enquanto uma estiver na fila ou em execução
Desconectar	`DELETE /sources/:id`	`202` com o `run` que exclui seus documentos; a fonte fica `deleting`, depois `deleted`

Cada sincronização lista o bucket e lê arquivos novos e alterados.
Uma sincronização que excluiria mais de 1.000 documentos e um décimo da fonte aguarda 24 horas até que uma segunda sincronização confirme.

Documentos

Cada arquivo é um documento, com o id e as localizações de um upload, além de source_url (gs://bucket/name), bucket, object e generation em seus metadados.

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

GET /sources/:id/documents lista seus arquivos.

Falhas

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
}

Opção	Tipo	O que faz
`limit`	integer, padrão 1000	Falhas por página, até 1.000
`cursor`	string	O `next_cursor` da página anterior, `null` na última página

`code`	Significado
`unsupported_file`	O Conare não lê o tipo do arquivo
`too_large`	Acima de 512 MiB
`pages_unread`	O OCR não conseguiu ler as páginas indicadas na mensagem; o restante é pesquisável
Outros	O erro da conversão, como `type_mismatch` ou `unreadable_file`

Uma falha nunca interrompe uma sincronização.
Um arquivo que falhou definitivamente só é lido de novo quando muda.
Um que falhou por um motivo passageiro é tentado novamente nas 3 sincronizações seguintes, depois diariamente.

Schema completo: Listar os objetos que uma fonte não conseguiu manter.

Erros

Erro	Quando
`422 gcs_access_denied`	A conta não consegue listar o bucket; a mensagem indica a conta e o papel
`422 gcs_not_verified`	O bucket não tem `.conare/<organization id>`; a mensagem indica o objeto
`422 gcs_bucket_not_found`	Nenhum bucket tem esse nome
`503 gcs_auth_failed`, `503 gcs_unavailable`	Não foi possível acessar o Google Cloud Storage; tente novamente após `Retry-After`

Primeiros passos

Essencial

Arquivos

Sincronização

Modelos

Ferramentas

Google Cloud Storage

A conta

Visualizar um bucket

Conectar um bucket

Sincronizar e desconectar

Documentos

Falhas

Erros

​A conta

​Visualizar um bucket

​Conectar um bucket

​Sincronizar e desconectar

​Documentos

​Falhas

​Erros

A conta

Visualizar um bucket

Conectar um bucket

Sincronizar e desconectar

Documentos

Falhas

Erros