Google Cloud Storage

Une source Google Cloud Storage synchronise un bucket, ou certains de ses préfixes, dans un namespace. Chaque fichier est lu comme lors d’un import, et un fichier supprimé du bucket perd ses documents.

Accorder l'accès

Conare lit les buckets via un unique compte de service Google, donc aucune clé n’est échangée. Accordez-lui le rôle Storage Object Viewer et créez l’objet vide .conare/<organization id>, qui prouve que le bucket vous appartient :

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

Prévisualiser le 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/"]}'

Le connecter

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

Le compte

GET /sources/gcs

Response

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

service_account, role : le compte, et le rôle à lui accorder sur votre bucket.
Une source cesse de se synchroniser lorsque .conare/<organization id> est supprimé ; gcs_not_verified indique l’objet à créer.

Schéma complet : The account to grant a bucket to.

Prévisualiser un bucket

POST /sources/gcs/preview Liste ce qu’une source de ce bucket lirait ; rien n’est stocké.

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
}

Option	Type	Ce qu’elle fait
`bucket`	chaîne, requis	Le nom du bucket
`prefixes`	tableau	Jusqu’à 20 préfixes, chacun jusqu’à 1 024 caractères ; sans préfixe, tout le bucket est lu

Champ	Signification
`objects`, `bytes`	Fichiers qu’une source lirait, et leur taille
`types`	Fichiers par type ; `other` pour ceux dont seuls les octets révéleront le type
`skipped`, `unsupported`, `too_large`	Dossiers et objets vides ; fichiers que Conare ne lit pas ; fichiers de plus de 512 Mio
`sample`	Jusqu’à 20 noms de fichiers
`complete`	`false` lorsque le bucket contenait plus de 10 000 objets ou que son listage a pris plus de 10 secondes

Schéma complet : Preview a bucket.

Connecter un bucket

Envoyez "type": "gcs" à POST /sources ; la première synchronisation démarre immédiatement, et une clé limitée au namespace peut le connecter.

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

Option	Type	Ce qu’elle fait
`type`	chaîne, requis	`gcs`
`namespace`	chaîne, requis	Le namespace où conserver les fichiers
`bucket`	chaîne, requis	Le nom du bucket
`prefixes`	tableau	Jusqu’à 20 préfixes, chacun jusqu’à 1 024 caractères
`name`	chaîne	Un nom d’affichage, jusqu’à 200 caractères ; par défaut `gs://bucket/prefix`
`sync_interval_s`	entier, 3600 par défaut	Secondes entre deux synchronisations, de 900 à 604 800 (7 jours)

Champ	Signification
`health`	`ok` ; `degraded` lorsque la dernière synchronisation a retenu ses suppressions ; `failing` lorsque le compte a perdu son autorisation ou que les 3 dernières synchronisations ont échoué
`sync`	`state` (`idle`, `queued` ou `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error`
`documents`, `failures`	Documents conservés, et fichiers qui n’ont pas pu l’être (ci-dessous)
`config`	Le bucket, les préfixes, le compte et l’intervalle

Synchroniser et déconnecter

Action	Route	Réponse
Synchroniser maintenant	`POST /sources/:id/sync`	`202` avec le `run` de la synchronisation, ou `409 run_active` tant qu’une synchronisation est en file ou en cours
Déconnecter	`DELETE /sources/:id`	`202` avec le `run` qui supprime ses documents ; la source passe à `deleting`, puis `deleted`

Chaque synchronisation liste le bucket et lit les fichiers nouveaux et modifiés.
Une synchronisation qui supprimerait plus de 1 000 documents et un dixième de la source attend 24 heures qu’une seconde synchronisation la confirme.

Documents

Chaque fichier est un document, avec l’id et les emplacements d’un import, plus source_url (gs://bucket/name), bucket, object et generation dans ses métadonnées.

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

GET /sources/:id/documents liste ses fichiers.

Échecs

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
}

Option	Type	Ce qu’elle fait
`limit`	entier, 1000 par défaut	Échecs par page, jusqu’à 1 000
`cursor`	chaîne	Le `next_cursor` de la page précédente, `null` sur la dernière page

`code`	Signification
`unsupported_file`	Conare ne lit pas ce type de fichier
`too_large`	Plus de 512 Mio
`pages_unread`	L’OCR n’a pas pu lire les pages indiquées dans le message ; le reste est consultable
Autres	L’erreur de conversion, comme `type_mismatch` ou `unreadable_file`

Un échec n’arrête jamais une synchronisation.
Un fichier en échec définitif n’est relu que s’il change.
Un fichier en échec pour une raison passagère est retenté lors des 3 synchronisations suivantes, puis chaque jour.

Schéma complet : List the objects a source could not keep.

Erreurs

Erreur	Quand
`422 gcs_access_denied`	Le compte ne peut pas lister le bucket ; le message indique le compte et le rôle
`422 gcs_not_verified`	Le bucket n’a pas de `.conare/<organization id>` ; le message indique l’objet
`422 gcs_bucket_not_found`	Aucun bucket ne porte ce nom
`503 gcs_auth_failed`, `503 gcs_unavailable`	Google Cloud Storage est injoignable ; réessayez après `Retry-After`

Premiers pas

Essentiel

Fichiers

Synchronisation

Modèles

Outils

Google Cloud Storage

Le compte

Prévisualiser un bucket

Connecter un bucket

Synchroniser et déconnecter

Documents

Échecs

Erreurs

​Le compte

​Prévisualiser un bucket

​Connecter un bucket

​Synchroniser et déconnecter

​Documents

​Échecs

​Erreurs

Le compte

Prévisualiser un bucket

Connecter un bucket

Synchroniser et déconnecter

Documents

Échecs

Erreurs