立即同步知识库
立即同步知识库
可立即触发知识库中来自外部来源的知识文档的增量同步，当前仅支持 Google Drive 来源。
注意：
接口在完成校验与规划后立即返回，因此返回的是“已受理”，而非“已更新”。
频率限制：每个 Agent / Workflow 每分钟最多 1 次。
请求方式
POST
调用地址
按 API Key 所属的资源类型选择对应路径。两个接口的请求参数、响应结构、限流规则完全一致。
- Agent：
https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync
- Workflow：
https://api-${endpoint}.gptbots.ai/v1/workflow/knowledge-base/sync
下文的请求 / 响应说明对两个路径同时适用，示例以 Agent 路径书写。
调用验证
详情参见 API 概述的鉴权方式说明。
请求
请求示例
- 同步指定知识库：
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"source": "google-drive",
"knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"source": "google-drive",
"knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'
此代码块在浮窗中显示
- 同步该 Agent 下全部知识库：
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"source": "google-drive"
}'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
"source": "google-drive"
}'
此代码块在浮窗中显示
请求头
| 字段 | 类型 | 描述 |
|---|---|---|
| Authorization | Bearer ${API Key} | 使用 Authorization: Bearer ${API Key}进行调用验证，请在 API 密钥页面获取密钥作为 API Key。 |
| Content-Type | application/json | 数据类型，取值为 application/json 。 |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| source | String | 是 | 来源类型。当前仅支持 google-drive，传其它值返回参数错误。 |
| knowledge_base_ids | Array<String> | 否 | 目标知识库 ID 列表，最多 200 个，超出返回参数错误。不传、传 null 或传空数组表示该 Agent / Workflow 名下全部知识库。列表中不存在或不属于当前 Agent / Workflow 的 ID 不会导致整个请求失败，会出现在 skipped 中。 |
响应
响应示例
{
"code": 0,
"message": "OK",
"data": {
"accepted": true,
"source": "google-drive",
"matched_knowledge_base_count": 2,
"matched_doc_count": 37,
"matched_folder_count": 3,
"matched_restore_count": 1,
"skipped": [
{
"reason": "DRIVE_NOT_AUTHORIZED",
"message": "The document owner has not authorized Google Drive, or the authorization has expired.",
"knowledge_base_id": "6a44c3512ceb43775567391e",
"doc_count": 8
},
{
"reason": "KNOWLEDGE_BASE_NOT_FOUND",
"message": "Knowledge base does not exist or does not belong to this agent.",
"knowledge_base_id": "deadbeefdeadbeefdeadbeef"
}
],
"scheduled_round_running": false
}
}
{
"code": 0,
"message": "OK",
"data": {
"accepted": true,
"source": "google-drive",
"matched_knowledge_base_count": 2,
"matched_doc_count": 37,
"matched_folder_count": 3,
"matched_restore_count": 1,
"skipped": [
{
"reason": "DRIVE_NOT_AUTHORIZED",
"message": "The document owner has not authorized Google Drive, or the authorization has expired.",
"knowledge_base_id": "6a44c3512ceb43775567391e",
"doc_count": 8
},
{
"reason": "KNOWLEDGE_BASE_NOT_FOUND",
"message": "Knowledge base does not exist or does not belong to this agent.",
"knowledge_base_id": "deadbeefdeadbeefdeadbeef"
}
],
"scheduled_round_running": false
}
}
此代码块在浮窗中显示
成功响应
| 字段 | 类型 | 说明 |
|---|---|---|
| code | Integer | 返回码，0 表示成功。 |
| message | String | 返回信息。 |
| data | Object | 受理结果。 |
| accepted | Boolean | 是否已受理。false 表示本次什么都没启动，原因见 skipped。 |
| source | String | 本次同步的来源类型。 |
| matched_knowledge_base_count | Integer | 本次命中的知识库数量。 |
| matched_doc_count | Integer | 本次将检查的知识文档数量。注意是“将检查”，而非“已更新”。 |
| matched_folder_count | Integer | 本次将检查新增文件的文件夹来源数量。 |
| matched_restore_count | Integer | 本次将检查能否重新导入的已删除单文件数量：源文件进回收站、过了观察窗被系统删除的文档，若已在 Google Drive 上还原，本次会重新导入（见下文“从回收站还原后”）。仍在回收站、读不到的跳过。 |
| skipped | Array<Object> | 被跳过的明细，按“知识库 + 原因”聚合，不逐文档展开。 |
| reason | String | 跳过原因，取值见下表。 |
| message | String | 原因说明。 |
| knowledge_base_id | String | 受影响的知识库 ID。整体性原因（如余额不足）时不返回该字段。 |
| doc_count | Integer | 受影响的文档数。按知识库整体跳过时不返回该字段。 |
| scheduled_round_running | Boolean | 系统定时同步轮次当前是否正在执行。仅作告知，不影响本次受理；某个知识库是否因定时同步正在处理而被跳过，以 skipped 为准。accepted 为 false 时本次未做该判定，返回 null。 |
skipped[].reason 取值
| 取值 | 含义 | 处理建议 |
|---|---|---|
| KNOWLEDGE_BASE_NOT_FOUND | 知识库不存在，或不属于当前 API Key 绑定的 Agent / Workflow。 | 检查 knowledge_base_ids，可先调用获取知识库列表确认。 |
| NO_GOOGLE_DRIVE_SOURCE | 知识库存在，但其中没有任何来自 Google Drive 的文档，也没有待重新导入的已删除文件。 | 正常情况，说明该知识库无需同步。 |
| DRIVE_NOT_AUTHORIZED | 文档所属成员没有可用的 Google Drive 授权（从未授权，或授权已失效）。 | 让该成员重新授权 Google Drive。 |
| DOC_IN_PROGRESS | 文档正在处理中。多为定时轮次或上一次同步尚未完成。 | 稍后重试，或等待处理完成。 |
| DOC_NO_OWNER | 文档缺少所属成员信息，无法确定使用谁的 Google Drive 授权。 | 需联系支持人员排查该文档。 |
| INSUFFICIENT_BALANCE | 组织余额不足。此时 accepted 为 false，不启动任何同步。 |
充值后重试。 |
| SYNC_IN_PROGRESS | 正在同步，本次跳过。不带 knowledge_base_id：该 Agent / Workflow 上一次立即同步仍在执行，此时 accepted 为 false，本次不启动任何同步。带 knowledge_base_id：该知识库此刻正被系统定时同步处理，本次只跳过这一个知识库，其余知识库照常受理；命中的知识库全部如此时 accepted 为 false。 |
稍后重试。定时同步对该知识库做的事与本接口相同，等它完成即可。 |
失败响应
| 字段 | 类型 | 描述 |
|---|---|---|
| code | Integer | 错误码。 |
| message | String | 错误详情。 |
常见错误码：
| HTTP | code | 场景 |
|---|---|---|
| 400 | 40000 | source 缺失或不支持；knowledge_base_ids 超过 200 个；单次命中文档数超过 5000（需用 knowledge_base_ids 缩小范围）。 |
| 400 | 40001 | 触发过于频繁，超出接口限流。 |
| 401 | 40101 | 缺少 Authorization 请求头。 |
| 401 | 40127 | API Key 无效。 |
| 200 | 20055 | 该 Agent / Workflow 尚未发布版本，或 API 开关未开启。未发布时 API 开关无法打开：需先发布，再到「开发空间 → 集成 → API」打开。注意 HTTP 状态码为 200，请以 code 判断。 |
source 非法时的响应示例：
{
"code": 40000,
"message": "Unsupported source: sharepoint. Supported: google-drive"
}
{
"code": 40000,
"message": "Unsupported source: sharepoint. Supported: google-drive"
}
此代码块在浮窗中显示