Google Cloud Storage

Una sorgente Google Cloud Storage mantiene un bucket, o alcuni suoi prefissi, in un namespace. Ogni file viene letto come un caricamento, e un file eliminato dal bucket perde i suoi documenti.

Concedi l'accesso

Conare legge i bucket come un unico service account Google, quindi nessuna chiave passa di mano. Concedigli Storage Object Viewer e crea l’oggetto vuoto .conare/<organization id>, che dimostra che il bucket è tuo:

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

Visualizza l'anteprima del 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/"]}'

Collegalo

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

L’account

GET /sources/gcs

Response

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

service_account, role: l’account e il ruolo da concedergli sul tuo bucket.
Una sorgente smette di sincronizzarsi quando .conare/<organization id> viene rimosso; gcs_not_verified indica l’oggetto da creare.

Schema completo: The account to grant a bucket to.

Anteprima di un bucket

POST /sources/gcs/preview Elenca ciò che una sorgente del bucket leggerebbe; non viene archiviato nulla.

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
}

Opzione	Tipo	Cosa fa
`bucket`	string, obbligatorio	Il nome del bucket
`prefixes`	array	Fino a 20 prefissi, ciascuno fino a 1.024 caratteri; senza prefissi legge l’intero bucket

Campo	Significato
`objects`, `bytes`	I file che una sorgente leggerebbe e la loro dimensione
`types`	File per tipo; `other` per quelli il cui tipo si capisce solo dai byte
`skipped`, `unsupported`, `too_large`	Cartelle e oggetti vuoti; file che Conare non legge; file oltre 512 MiB
`sample`	Fino a 20 nomi di file
`complete`	`false` quando il bucket conteneva oltre 10.000 oggetti o l’elenco ha richiesto più di 10 secondi

Schema completo: Preview a bucket.

Collegare un bucket

Invia "type": "gcs" a POST /sources; la prima sincronizzazione parte subito, e può collegarlo anche una chiave limitata al namespace.

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

Opzione	Tipo	Cosa fa
`type`	string, obbligatorio	`gcs`
`namespace`	string, obbligatorio	Il namespace in cui mantenere i file
`bucket`	string, obbligatorio	Il nome del bucket
`prefixes`	array	Fino a 20 prefissi, ciascuno fino a 1.024 caratteri
`name`	string	Un nome visualizzato, fino a 200 caratteri; predefinito `gs://bucket/prefix`
`sync_interval_s`	integer, predefinito 3600	Secondi tra le sincronizzazioni, da 900 a 604.800 (7 giorni)

Campo	Significato
`health`	`ok`; `degraded` quando l’ultima sincronizzazione ha trattenuto le eliminazioni; `failing` quando l’account ha perso l’autorizzazione o le ultime 3 sincronizzazioni sono fallite
`sync`	`state` (`idle`, `queued` o `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error`
`documents`, `failures`	I documenti che mantiene e i file che non ha potuto mantenere (sotto)
`config`	Il bucket, i prefissi, l’account e l’intervallo

Sincronizzare e scollegare

Azione	Route	Risposta
Sincronizza ora	`POST /sources/:id/sync`	`202` con il `run` della sincronizzazione, o `409 run_active` mentre una è in coda o in esecuzione
Scollega	`DELETE /sources/:id`	`202` con il `run` che elimina i suoi documenti; la sorgente è `deleting`, poi `deleted`

Ogni sincronizzazione elenca il bucket e legge i file nuovi e modificati.
Una sincronizzazione che eliminerebbe oltre 1.000 documenti e un decimo della sorgente attende 24 ore che una seconda sincronizzazione lo confermi.

Documenti

Ogni file è un documento, con l’id e le posizioni di un caricamento, più source_url (gs://bucket/name), bucket, object e generation nei suoi metadati.

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

GET /sources/:id/documents elenca i suoi file.

Errori sui file

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
}

Opzione	Tipo	Cosa fa
`limit`	integer, predefinito 1000	Errori per pagina, fino a 1.000
`cursor`	string	Il `next_cursor` della pagina precedente, `null` nell’ultima pagina

`code`	Significato
`unsupported_file`	Conare non legge il tipo del file
`too_large`	Oltre 512 MiB
`pages_unread`	L’OCR non ha potuto leggere le pagine indicate nel messaggio; il resto è ricercabile
Altri	L’errore dell’analisi, come `type_mismatch` o `unreadable_file`

Un errore non interrompe mai una sincronizzazione.
Un file fallito in modo definitivo viene riletto solo quando cambia.
Uno fallito per un motivo temporaneo viene ritentato nelle 3 sincronizzazioni successive, poi ogni giorno.

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

Errori

Errore	Quando
`422 gcs_access_denied`	L’account non può elencare il bucket; il messaggio indica l’account e il ruolo
`422 gcs_not_verified`	Il bucket non ha `.conare/<organization id>`; il messaggio indica l’oggetto
`422 gcs_bucket_not_found`	Nessun bucket ha quel nome
`503 gcs_auth_failed`, `503 gcs_unavailable`	Google Cloud Storage non era raggiungibile; riprova dopo `Retry-After`

Primi passi

Fondamenti

File

Sincronizzazione

Modelli

Strumenti

Google Cloud Storage

L’account

Anteprima di un bucket

Collegare un bucket

Sincronizzare e scollegare

Documenti

Errori sui file

Errori

​L’account

​Anteprima di un bucket

​Collegare un bucket

​Sincronizzare e scollegare

​Documenti

​Errori sui file

​Errori

L’account

Anteprima di un bucket

Collegare un bucket

Sincronizzare e scollegare

Documenti

Errori sui file

Errori