Google Cloud Storage

Eine Google Cloud Storage-Quelle hält einen Bucket oder Präfixe davon in einem Namespace. Jede Datei wird wie ein Upload gelesen, und eine aus dem Bucket gelöschte Datei verliert ihre Dokumente.

Zugriff gewähren

Conare liest Buckets als ein einziges Google-Dienstkonto, sodass kein Schlüssel weitergegeben wird. Erteilen Sie ihm Storage Object Viewer und erstellen Sie das leere Objekt .conare/<organization id>, das zeigt, dass der Bucket Ihnen gehört:

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

Bucket-Vorschau anzeigen

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

Verbinden

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

Das Konto

GET /sources/gcs

Response

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

service_account, role: das Konto und die Rolle, die Sie ihm für Ihren Bucket erteilen.
Eine Quelle hört auf zu synchronisieren, wenn .conare/<organization id> entfernt wird; gcs_not_verified nennt das zu erstellende Objekt.

Vollständiges Schema: Das Konto, dem ein Bucket freigegeben wird.

Vorschau eines Buckets

POST /sources/gcs/preview Listet auf, was eine Quelle des Buckets lesen würde; nichts wird gespeichert.

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	Typ	Funktion
`bucket`	string, erforderlich	Der Name des Buckets
`prefixes`	array	Bis zu 20 Präfixe, jeweils bis zu 1.024 Zeichen; ohne Präfix wird der ganze Bucket gelesen

Feld	Bedeutung
`objects`, `bytes`	Dateien, die eine Quelle lesen würde, und ihre Größe
`types`	Dateien nach Typ; `other` für jene, deren Typ erst die Bytes verraten
`skipped`, `unsupported`, `too_large`	Ordner und leere Objekte; Dateien, die Conare nicht liest; Dateien über 512 MiB
`sample`	Bis zu 20 Dateinamen
`complete`	`false`, wenn der Bucket über 10.000 Objekte enthielt oder das Auflisten über 10 Sekunden dauerte

Vollständiges Schema: Vorschau eines Buckets.

Einen Bucket verbinden

Senden Sie "type": "gcs" an POST /sources; die erste Synchronisierung startet sofort, und ein auf den Namespace beschränkter Schlüssel kann ihn verbinden.

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	Typ	Funktion
`type`	string, erforderlich	`gcs`
`namespace`	string, erforderlich	Der Namespace, in dem die Dateien gehalten werden
`bucket`	string, erforderlich	Der Name des Buckets
`prefixes`	array	Bis zu 20 Präfixe, jeweils bis zu 1.024 Zeichen
`name`	string	Ein Anzeigename, bis zu 200 Zeichen; standardmäßig `gs://bucket/prefix`
`sync_interval_s`	integer, Standard 3600	Sekunden zwischen Synchronisierungen, 900 bis 604.800 (7 Tage)

Feld	Bedeutung
`health`	`ok`; `degraded`, wenn die letzte Synchronisierung ihre Löschungen zurückgehalten hat; `failing`, wenn das Konto seine Berechtigung verloren hat oder die letzten 3 Synchronisierungen fehlgeschlagen sind
`sync`	`state` (`idle`, `queued` oder `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error`
`documents`, `failures`	Dokumente, die sie hält, und Dateien, die sie nicht halten konnte (unten)
`config`	Bucket, Präfixe, Konto und Intervall

Synchronisieren und trennen

Aktion	Route	Antwort
Jetzt synchronisieren	`POST /sources/:id/sync`	`202` mit dem `run` der Synchronisierung, oder `409 run_active`, solange eine in der Warteschlange ist oder läuft
Trennen	`DELETE /sources/:id`	`202` mit dem `run`, der ihre Dokumente löscht; die Quelle ist `deleting`, dann `deleted`

Jede Synchronisierung listet den Bucket auf und liest neue und geänderte Dateien.
Eine Synchronisierung, die über 1.000 Dokumente und ein Zehntel der Quelle löschen würde, wartet 24 Stunden auf eine zweite Synchronisierung, die das bestätigt.

Dokumente

Jede Datei ist ein Dokument, mit der ID und den Positionen eines Uploads, dazu source_url (gs://bucket/name), bucket, object und generation in seinen Metadaten.

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

GET /sources/:id/documents listet ihre Dateien auf.

Fehlschläge

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	Typ	Funktion
`limit`	integer, Standard 1000	Fehlschläge pro Seite, bis zu 1.000
`cursor`	string	Der `next_cursor` der vorherigen Seite, `null` auf der letzten Seite

`code`	Bedeutung
`unsupported_file`	Conare liest den Typ der Datei nicht
`too_large`	Über 512 MiB
`pages_unread`	OCR konnte die in der Meldung genannten Seiten nicht lesen; der Rest ist durchsuchbar
Andere	Der Fehler beim Parsen, etwa `type_mismatch` oder `unreadable_file`

Ein Fehlschlag stoppt nie eine Synchronisierung.
Eine endgültig fehlgeschlagene Datei wird erst wieder gelesen, wenn sie sich ändert.
Eine aus vorübergehendem Grund fehlgeschlagene Datei wird bei den nächsten 3 Synchronisierungen erneut versucht, danach täglich.

Vollständiges Schema: Die Objekte auflisten, die eine Quelle nicht halten konnte.

Fehler

Fehler	Wann
`422 gcs_access_denied`	Das Konto kann den Bucket nicht auflisten; die Meldung nennt Konto und Rolle
`422 gcs_not_verified`	Der Bucket hat kein `.conare/<organization id>`; die Meldung nennt das Objekt
`422 gcs_bucket_not_found`	Kein Bucket hat diesen Namen
`503 gcs_auth_failed`, `503 gcs_unavailable`	Google Cloud Storage war nicht erreichbar; versuchen Sie es nach `Retry-After` erneut

Erste Schritte

Grundlagen

Dateien

Synchronisierung

Modelle

Tools

Google Cloud Storage

Das Konto

Vorschau eines Buckets

Einen Bucket verbinden

Synchronisieren und trennen

Dokumente

Fehlschläge

Fehler

​Das Konto

​Vorschau eines Buckets

​Einen Bucket verbinden

​Synchronisieren und trennen

​Dokumente

​Fehlschläge

​Fehler

Das Konto

Vorschau eines Buckets

Einen Bucket verbinden

Synchronisieren und trennen

Dokumente

Fehlschläge

Fehler