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 会指明需要创建的对象。

完整 schema：要授予存储桶访问权限的账号。

预览存储桶

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`	存储桶对象超过 10,000 个或列举耗时超过 10 秒时为 `false`

完整 schema：预览存储桶。

连接存储桶

向 POST /sources 发送 "type": "gcs"；首次同步会立即开始，限定于该命名空间的密钥即可连接。

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`；账号失去授权或最近 3 次同步失败时为 `failing`
`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 次同步中重试，之后每天重试。

完整 schema：列出数据源无法保留的对象。

错误

错误	场景
`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

服务账号

预览存储桶

连接存储桶

同步与断开连接

文档

失败项

错误

​服务账号

​预览存储桶

​连接存储桶

​同步与断开连接

​文档

​失败项

​错误

服务账号

预览存储桶

连接存储桶

同步与断开连接

文档

失败项

错误