> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # 更新同步策略 > 设置数据源的定时同步，替换原有设置，并返回新设置。 保存不会启动同步。第一次定时同步在更新后满一个间隔时到期，之后每次在上一次进入队列后满一个间隔时到期。要立即同步，调用 [同步数据源](/zh/api-reference/source-syncs-and-imports/sync-source)。 每次向该数据源导入完成后，都要用数据源新的 `version` 重新保存定时同步。导入会改变 `version`，仍绑定在旧值上的定时同步会在下一次到期时自行关闭。 要暂停定时同步而不改动其设置，用 [更新数据源](/zh/api-reference/sources/update-source) 将数据源的 `status` 设为 `disabled`。暂停期间到期的同步，会在数据源恢复为 `active` 时运行。 先读取再保存的流程，详见 [同步数据源与定时同步](/zh/api-reference/guides/knowledge-base#sync-and-schedule-sources)。 ## OpenAPI ````yaml /zh/api-reference/openapi_service.json put /knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy openapi: 3.0.1 info: description: 用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。 title: Dify 服务 API version: 1.0.0 servers: - description: Dify 服务 API 的基础 URL。自部署时，替换为你的 API 基础 URL。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API 基础 URL 的主机与路径，不含 `https://` 前缀。 security: - ApiKeyAuth: [] tags: - description: 与聊天消息和交互相关的操作。 name: 对话消息 - description: 文件上传和预览操作。 name: 文件操作 - description: 终端用户信息相关操作。 name: 终端用户 - description: 用户反馈操作。 name: 消息反馈 - description: 与管理会话相关的操作。 name: 会话管理 - description: 文字转语音和语音转文字操作。 name: 语音与文字转换 - description: 获取应用设置和信息的操作。 name: 应用配置 - description: 与管理标注直接回复相关的操作。 name: 标注管理 - description: 暂停等待人工输入的工作流恢复操作。 name: 人工介入 - description: 用于执行和管理工作流的操作。 name: 工作流运行 - description: 文本生成相关操作。 name: 文本生成消息 - description: 用于管理知识库的操作，包括创建、配置和检索。 name: 知识库 - description: 用于在知识库中创建、更新和管理文档的操作。 name: 文档 - description: 用于管理分段和子分段的操作。 name: 分段 - description: 用于管理知识库元数据字段和文档元数据值的操作。 name: 元数据 - description: 用于管理知识库标签和标签绑定的操作。 name: 标签 - description: 用于获取可用模型的操作。 name: 模型 - description: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。 name: 知识流水线 - description: 向知识库提问，并流式返回回答。 name: 查询 - description: 查看一次查询检索到了什么，以及原因。 name: 查询记录 - description: 在后台运行研究问题，并获取其结果。 name: 研究任务 - description: 读取知识库中的文档及其文件、修订版本和分段，并用元数据标注文档。 name: 文档与分段 - description: 跟踪、取消或重试索引，并列出知识库的后台任务。 name: 索引任务 - description: 跟踪文档文件、一批文件或数据源的删除，直到完成。 name: 删除作业 - description: 管理为知识库提供内容的数据源，以及它们的定时同步设置和连接。 name: 数据源 - description: 立即同步数据源，导入网站页面或提供商条目，并跟踪、取消或重试运行。 name: 数据源同步与导入 - description: 读取和更改知识库的模型与检索设置，并跟踪更改触发的迁移。 name: 设置 paths: /knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}/sync-policy: put: tags: - Sources summary: 更新同步策略 description: >- 设置数据源的定时同步，替换原有设置，并返回新设置。 保存不会启动同步。第一次定时同步在更新后满一个间隔时到期，之后每次在上一次进入队列后满一个间隔时到期。要立即同步，调用 [同步数据源](/zh/api-reference/source-syncs-and-imports/sync-source)。 每次向该数据源导入完成后，都要用数据源新的 `version` 重新保存定时同步。导入会改变 `version`，仍绑定在旧值上的定时同步会在下一次到期时自行关闭。 要暂停定时同步而不改动其设置，用 [更新数据源](/zh/api-reference/sources/update-source) 将数据源的 `status` 设为 `disabled`。暂停期间到期的同步，会在数据源恢复为 `active` 时运行。 先读取再保存的流程，详见 [同步数据源与定时同步](/zh/api-reference/guides/knowledge-base#sync-and-schedule-sources)。 operationId: updateSourceSyncPolicy parameters: - description: >- 知识库 ID：即知识库 **API 访问** 对话框中所示服务 API 端点的最后一段（`…/knowledge-fs/spaces/`），也是地址栏中 `/datasets/new/` 之后的那一段。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: 数据源 ID，通过 [获取数据源列表](/zh/api-reference/sources/list-sources) 获取。 in: path name: source_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: custom: summary: 请求示例 - 自定义间隔 value: customIntervalSeconds: 21600 enabled: true expectedRevision: 5 expectedSourceVersion: 8 mode: custom interval: summary: 请求示例 - 每 24 小时 value: enabled: true expectedRevision: 0 expectedSourceVersion: 3 mode: interval manual: summary: 请求示例 - 不安排定时同步 value: enabled: false expectedRevision: 6 expectedSourceVersion: 8 mode: manual schema: additionalProperties: false properties: customIntervalSeconds: description: '两次定时同步之间的秒数，取值为 1 小时～30 天。`mode: custom` 时必填，其他模式下传入会被拒绝。' maximum: 2592000 minimum: 3600 type: integer enabled: description: '是否运行定时同步。`mode: manual` 时必须为 `false`。' type: boolean expectedRevision: description: >- 定时同步当前的 `revision`，取自 [获取同步策略](/zh/api-reference/sources/get-sync-policy)。数据源尚无定时同步时传 `0`。每次定时同步启动时该值也会递增，因此应在更新前立即读取。值已过时则返回 `409`，不做任何更改。 minimum: 0 type: integer expectedSourceVersion: description: >- 数据源当前的 `version`，取自 [获取数据源](/zh/api-reference/sources/get-source) 或 [获取数据源列表](/zh/api-reference/sources/list-sources)。每次调用 [更新数据源](/zh/api-reference/sources/update-source) 以及每次导入完成后，该值都会变化，因此应在更新前立即读取。值已过时则返回 `409`，不做任何更改。 minimum: 1 type: integer mode: description: >- `manual` 关闭定时同步，`interval` 每 24 小时同步一次，`custom` 按 `customIntervalSeconds` 的间隔同步。 enum: - manual - interval - custom type: string required: - enabled - expectedRevision - expectedSourceVersion - mode type: object required: true responses: '200': content: application/json: examples: success: summary: 响应示例 value: created_at: '2026-09-01T08:05:00Z' custom_interval_seconds: 21600 enabled: true expected_source_version: 8 id: 8e7d6c5b-4a39-4f28-9e17-0d1c2b3a4f5e knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d mode: custom next_run_at: '2026-10-21T08:30:00Z' revision: 6 source_id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90 updated_at: '2026-10-21T02:30:00Z' schema: $ref: '#/components/schemas/KnowledgeBaseSyncPolicy' description: >- 保存后的定时同步设置。`mode: manual` 或 `enabled: false` 时，`next_run_at` 为 `null`。 '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - customIntervalSeconds type: greater_than_equal knowledge_fs_invalid_request_path: summary: knowledge_fs_invalid_request (path ID) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (rejected) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`：请求未通过校验。`violations` 列出每个出错的字段。可能的原因： - 缺少某个字段或字段类型错误，或请求体含有未知键。 - `mode` 不是所列取值之一。 - `customIntervalSeconds` 超出范围、在 `mode: custom` 时缺失，或与其他模式一起传入。 - `knowledge_fs_invalid_request`：`mode: manual` 与 `enabled: true` 同时传入，或 `source_id` 不是 UUID。 - `knowledge_fs_invalid_request`：`source_id` 格式不正确。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：缺少 `Authorization` 请求头，或密钥无法识别、不是知识库 API 密钥。 - `knowledge_fs_invalid_credential`：密钥有效，但其所属工作空间中没有此 ID 的知识库，或该密钥未关联任何工作空间。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`：该密钥的访问范围限定为其他知识库、此知识库已关闭 **API 访问**，或知识库未处于活动状态。 - `forbidden`：在 Dify Cloud 上，工作空间已达到其订阅套餐的知识库请求频率限制。所有调用都计入，读取操作也不例外。 '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`：知识库中不存在此 ID 的数据源、该密钥无权读取它，或对它的删除请求已被受理。 - `not_found`：当前部署已关闭 Agent 知识库功能。 '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`：`expectedRevision` 不是定时同步当前的 `revision`，或 `expectedSourceVersion` 不是数据源当前的 `version`。响应体不会说明是哪一个，因此需用 [获取同步策略](/zh/api-reference/sources/get-sync-policy) 和 [获取数据源](/zh/api-reference/sources/get-source) 重新读取两者，再重新发送。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_transport: summary: knowledge_fs_upstream_unavailable (no response) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`：未能及时收到响应，或无法读取响应。 定时同步可能已经保存。再次发送更新前，先用 [获取同步策略](/zh/api-reference/sources/get-sync-policy) 读取。如果第一次调用已写入，用旧的 `expectedRevision` 重新发送会返回 `409`。 '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`：此工作空间尚未配置 Agent 知识库功能、当前部署不提供此操作，或在请求鉴权期间该密钥对此知识库的访问权限发生了变化。 - `knowledge_fs_operation_unavailable`：暂时无法处理该请求。按 `failure.retryPolicy` 处理。 components: schemas: KnowledgeBaseSyncPolicy: properties: created_at: description: 创建时间，ISO 8601 格式。 type: string custom_interval_seconds: description: '`mode: custom` 时的同步间隔，单位为秒。其他模式为 `null`。' nullable: true type: integer enabled: description: '是否运行定时同步。`mode: manual` 时始终为 `false`。' type: boolean expected_source_version: description: 定时同步绑定的数据源 `version`。 type: integer id: description: 同步策略 ID，更新后保持不变。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string mode: description: >- `manual`（不安排定时同步）、`interval`（每 24 小时）或 `custom`（按 `custom_interval_seconds` 的间隔）。 type: string next_run_at: description: 下次定时同步的时间，ISO 8601 格式。没有安排时为 `null`。 nullable: true type: string revision: description: >- 定时同步的修订版本。调用 [更新同步策略](/zh/api-reference/sources/update-sync-policy) 时将其作为 `expectedRevision` 传入。每次更新以及每次定时同步开始时都会递增。 type: integer source_id: description: 定时同步所属的数据源。 type: string updated_at: description: 最后变更时间，ISO 8601 格式。定时同步开始时也会更新。 type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.