Google Cloud Storage

Джерело Google Cloud Storage синхронізує бакет або його префікси з одним простором імен. Кожен файл читається так само, як завантаження, а файл, видалений із бакета, втрачає свої документи.

Надайте доступ

Conare читає бакети від імені одного службового облікового запису Google, тож ключі нікому не передаються. Надайте йому роль Storage Object Viewer і створіть порожній об’єкт .conare/<organization id>, який підтверджує, що бакет ваш:

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

Перегляньте бакет

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

Підключіть його

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

Обліковий запис

GET /sources/gcs

Response

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

service_account, role: обліковий запис і роль, яку потрібно надати йому у вашому бакеті.
Джерело припиняє синхронізацію, коли .conare/<organization id> видалено; gcs_not_verified вказує, який об’єкт створити.

Повна схема: The account to grant a bucket to.

Попередній перегляд бакета

POST /sources/gcs/preview Показує, що прочитало б джерело з цього бакета; нічого не зберігається.

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
}

Параметр	Тип	Що робить
`bucket`	string, обов’язковий	Назва бакета
`prefixes`	array	До 20 префіксів, кожен до 1 024 символів; без них читається весь бакет

Поле	Значення
`objects`, `bytes`	Файли, які прочитало б джерело, і їхній розмір
`types`	Файли за типом; `other` — ті, тип яких визначать лише їхні байти
`skipped`, `unsupported`, `too_large`	Папки й порожні об’єкти; файли, які Conare не читає; файли понад 512 MiB
`sample`	До 20 назв файлів
`complete`	`false`, якщо бакет містив понад 10 000 об’єктів або їх перелік тривав понад 10 секунд

Повна схема: Preview a bucket.

Підключення бакета

Надішліть "type": "gcs" до POST /sources; перша синхронізація починається одразу, а підключити бакет може ключ з доступом до цього простору імен.

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

Параметр	Тип	Що робить
`type`	string, обов’язковий	`gcs`
`namespace`	string, обов’язковий	Простір імен для зберігання файлів
`bucket`	string, обов’язковий	Назва бакета
`prefixes`	array	До 20 префіксів, кожен до 1 024 символів
`name`	string	Відображувана назва, до 200 символів; за замовчуванням `gs://bucket/prefix`
`sync_interval_s`	integer, за замовчуванням 3600	Секунди між синхронізаціями, від 900 до 604 800 (7 днів)

Поле	Значення
`health`	`ok`; `degraded`, якщо остання синхронізація відклала видалення; `failing`, якщо обліковий запис утратив доступ або останні 3 синхронізації не вдалися
`sync`	`state` (`idle`, `queued` або `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error`
`documents`, `failures`	Документи, які воно зберігає, і файли, які не вдалося зберегти (нижче)
`config`	Бакет, префікси, обліковий запис та інтервал

Синхронізація та відключення

Дія	Маршрут	Відповідь
Синхронізувати зараз	`POST /sources/:id/sync`	`202` із `run` синхронізації або `409 run_active`, поки інша в черзі чи виконується
Відключити	`DELETE /sources/:id`	`202` із `run`, що видаляє його документи; джерело має стан `deleting`, потім `deleted`

Кожна синхронізація отримує перелік вмісту бакета й читає нові та змінені файли.
Синхронізація, яка видалила б понад 1 000 документів і десяту частину джерела, чекає 24 години, доки її не підтвердить друга синхронізація.

Документи

Кожен файл — це один документ з таким самим id і розташуваннями, як у завантаженнях, а також source_url (gs://bucket/name), bucket, object і generation у метаданих.

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

GET /sources/:id/documents показує його файли.

Збої

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
}

Параметр	Тип	Що робить
`limit`	integer, за замовчуванням 1000	Збоїв на сторінку, до 1 000
`cursor`	string	`next_cursor` попередньої сторінки, `null` на останній сторінці

`code`	Значення
`unsupported_file`	Conare не читає файли цього типу
`too_large`	Понад 512 MiB
`pages_unread`	OCR не зміг прочитати сторінки, указані в повідомленні; решта доступна для пошуку
Інші	Помилка розбору, як-от `type_mismatch` або `unreadable_file`

Збій ніколи не зупиняє синхронізацію.
Файл, що не вдався остаточно, читається знову лише після зміни.
Файл, що не вдався з тимчасової причини, повторюється під час наступних 3 синхронізацій, а потім щодня.

Повна схема: List the objects a source could not keep.

Помилки

Помилка	Коли
`422 gcs_access_denied`	Обліковий запис не може отримати перелік вмісту бакета; у повідомленні вказано обліковий запис і роль
`422 gcs_not_verified`	У бакеті немає `.conare/<organization id>`; у повідомленні вказано об’єкт
`422 gcs_bucket_not_found`	Бакета з такою назвою немає
`503 gcs_auth_failed`, `503 gcs_unavailable`	Не вдалося з’єднатися з Google Cloud Storage; повторіть після `Retry-After`

Початок роботи

Основне

Файли

Синхронізація

Моделі

Інструменти

Google Cloud Storage

Обліковий запис

Попередній перегляд бакета

Підключення бакета

Синхронізація та відключення

Документи

Збої

Помилки

​Обліковий запис

​Попередній перегляд бакета

​Підключення бакета

​Синхронізація та відключення

​Документи

​Збої

​Помилки

Обліковий запис

Попередній перегляд бакета

Підключення бакета

Синхронізація та відключення

Документи

Збої

Помилки