> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Google Cloud Storage

> 让 Google Cloud Storage 存储桶中的文件在命名空间中保持可搜索。

Google Cloud Storage 数据源将一个存储桶或其中的若干前缀同步到一个命名空间。每个文件按[上传](https://docs.conare.ai/zh/files.md)的方式读取，从存储桶中删除的文件会失去其文档。

**1. 授予访问权限**

Conare 以一个 Google 服务账号读取存储桶，因此无需交换任何密钥。为其授予 Storage Object Viewer 角色，并创建空对象 `.conare/<organization id>`，以证明该存储桶归您所有：

```bash gcloud theme={null}
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
```

**2. 预览存储桶**

```bash curl theme={null}
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/"]}'
```

**3. 连接存储桶**

```bash curl theme={null}
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`

```json Response theme={null}
{
  "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：[要授予存储桶访问权限的账号](https://docs.conare.ai/zh/api-reference/sources/get-the-bucket-service-account.md)。

## 预览存储桶

`POST /sources/gcs/preview`

列出该存储桶的数据源将读取的内容；不存储任何内容。

```json Response theme={null}
{
  "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：[预览存储桶](https://docs.conare.ai/zh/api-reference/sources/preview-a-bucket.md)。

## 连接存储桶

向 [`POST /sources`](https://docs.conare.ai/zh/sources#连接数据源) 发送 `"type": "gcs"`；首次同步会立即开始，限定于该命名空间的密钥即可连接。

```json Response theme={null}
{
  "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 小时，由第二次同步确认。

## 文档

每个文件是一个文档，具有与[上传](https://docs.conare.ai/zh/files.md#存储的文档)相同的 id 和位置，元数据中还包含 `source_url`（`gs://bucket/name`）、`bucket`、`object` 和 `generation`。

```json theme={null}
{ "source_url": "gs://acme-reports/2024/prices.csv" }
```

`GET /sources/:id/documents` 列出其文件。

## 失败项

`GET /sources/:id/failures`

```bash curl theme={null}
curl https://api.conare.ai/sources/src_b805954930e968fe8d4a89f6/failures \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

```json Response theme={null}
{
  "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：[列出数据源无法保留的对象](https://docs.conare.ai/zh/api-reference/sources/list-a-sources-failures.md)。

## 错误

| 错误 | 场景 |
| - | - |
| `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` 之后重试 |


## Related topics

- [Get the bucket service account](https://docs.conare.ai/zh/api-reference/sources/get-the-bucket-service-account.md)
- [Preview a bucket](https://docs.conare.ai/zh/api-reference/sources/preview-a-bucket.md)
- [List a source's failures](https://docs.conare.ai/zh/api-reference/sources/list-a-sources-failures.md)
- [Sync a source now](https://docs.conare.ai/zh/api-reference/sources/sync-a-source-now.md)
- [数据源](https://docs.conare.ai/zh/sources.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.