> ## 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.

# 更新数据源

> 更新数据源的名称、状态、URI、元数据或提供商参数；配置有变化时，可同时启动一次同步。

至少传入 `name`、`status`、`uri`、`metadata`、`providerParameters` 中的一项。只传 `expectedVersion` 和 `syncAfterUpdate` 的请求会被拒绝。

如何启动和跟踪同步，详见 [同步数据源与定时同步](/zh/api-reference/guides/knowledge-base#sync-and-schedule-sources)。



## OpenAPI

````yaml /zh/api-reference/openapi_service.json patch /knowledge-fs/spaces/{knowledge_base_id}/sources/{source_id}
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}:
    patch:
      tags:
        - Sources
      summary: 更新数据源
      description: >-
        更新数据源的名称、状态、URI、元数据或提供商参数；配置有变化时，可同时启动一次同步。


        至少传入 `name`、`status`、`uri`、`metadata`、`providerParameters` 中的一项。只传
        `expectedVersion` 和 `syncAfterUpdate` 的请求会被拒绝。


        如何启动和跟踪同步，详见
        [同步数据源与定时同步](/zh/api-reference/guides/knowledge-base#sync-and-schedule-sources)。
      operationId: updateSource
      parameters:
        - description: >-
            知识库 ID：即知识库 **API 访问** 对话框中所示服务 API
            端点的最后一段（`…/knowledge-fs/spaces/<knowledge base ID>`），也是地址栏中
            `/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:
              reconfigure:
                summary: 请求示例
                value:
                  expectedVersion: 7
                  name: Docs site (v2)
                  status: active
                  syncAfterUpdate: true
                  uri: https://docs.example.com/v2
            schema:
              additionalProperties: false
              anyOf:
                - properties:
                    metadata:
                      nullable: false
                      type: object
                  required:
                    - metadata
                  title: 更新元数据
                - properties:
                    name:
                      nullable: false
                      type: string
                  required:
                    - name
                  title: 重命名数据源
                - properties:
                    providerParameters:
                      nullable: false
                      type: object
                  required:
                    - providerParameters
                  title: 更新提供商参数
                - properties:
                    status:
                      nullable: false
                      type: string
                  required:
                    - status
                  title: 更改状态
                - properties:
                    uri:
                      nullable: false
                      type: string
                  required:
                    - uri
                  title: 更改数据源 URL
              description: >-
                至少提供一个非 null 的 `metadata`、`name`、`providerParameters`、`status` 或
                `uri`。只有 `expectedVersion` 和 `syncAfterUpdate` 不构成更新。
              properties:
                expectedVersion:
                  description: >-
                    数据源当前的 `version`，取自
                    [获取数据源列表](/zh/api-reference/sources/list-sources) 或
                    [获取数据源](/zh/api-reference/sources/get-source)。值已过时则返回
                    `409`，不做任何更改。省略则以最后一次写入为准。
                  minimum: 1
                  nullable: true
                  type: integer
                metadata:
                  description: >-
                    要合并进已存储元数据的键。嵌套对象会合并，数组会整体替换。


                    不得包含 `parameters`（改用
                    `providerParameters`）或凭据。`datasource`、`pluginId`、`provider`、`providerId`
                    和 `providerKind` 不可更改。服务端会覆盖 `tenantId`。
                  nullable: true
                  type: object
                name:
                  description: 新的显示名称。
                  maxLength: 200
                  minLength: 1
                  nullable: true
                  type: string
                providerParameters:
                  description: >-
                    所选数据源定义的参数。此字段会整体替换已存储的 `metadata.parameters`
                    对象，因此需包含所有要保留的值。值可以是布尔值、有限数值或字符串。疑似凭据的键会被拒绝。


                    如果 [获取数据源](/zh/api-reference/sources/get-source)
                    未返回完整的非敏感参数，而你也不清楚该数据源的参数约定，改在 Dify 中配置数据源。
                  maxProperties: 50
                  nullable: true
                  type: object
                status:
                  description: |-
                    新状态。可设为 `active` 或 `disabled`。`error` 和 `syncing` 由同步运行设置。

                    `disabled` 会阻止新的定时同步，也会阻止本次更新启动同步，但不会取消已受理的同步。
                  enum:
                    - active
                    - disabled
                    - null
                  nullable: true
                  type: string
                syncAfterUpdate:
                  description: >-
                    为 `true` 时，在写入后请求一次同步运行。响应在 `sync_workflow`
                    中返回该运行；本次调用未启动同步时，返回 `sync_workflow: null`。


                    只有本次调用更改了 `uri`、`providerParameters` 或某个 `metadata` 值，且数据源的
                    `status` 不是 `disabled`
                    时，才会启动同步。重新发送当前值不会启动同步。如需在不更改数据源的情况下同步，调用
                    [同步数据源](/zh/api-reference/source-syncs-and-imports/sync-source)。


                    对于已保存页面列表的网站数据源，同步会刷新这些页面。要更改页面列表，使用
                    [导入网站页面](/zh/api-reference/source-syncs-and-imports/import-website-pages)
                    或
                    [导入所选页面](/zh/api-reference/source-syncs-and-imports/import-selected-pages)。
                  nullable: true
                  type: boolean
                uri:
                  description: >-
                    新的 URI。`web` 数据源的 URI 必须是 HTTP 或 HTTPS
                    URL，且不能内嵌凭据。`metadata.parameters.url` 会随之更新。
                  maxLength: 4096
                  minLength: 1
                  nullable: true
                  type: string
              type: object
        description: >-
          标记为 nullable 的可选字段，传 `null` 等同于省略。


          规范化后的请求不得超过 262,144 个 UTF-8 字节。参见
          [请求大小限制](/zh/api-reference/guides/knowledge-base#request-size-limits)。
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                success:
                  summary: 响应示例
                  value:
                    connection_id: c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f
                    created_at: '2026-09-01T08:00:00Z'
                    credential_configured: null
                    id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90
                    knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d
                    last_synced_at: null
                    metadata:
                      client_request_id: source-20260907-0001
                      parameters:
                        url: https://docs.example.com/v2
                      providerKind: website
                      tenantId: 2f1e0d9c-8b7a-4695-8473-2a1b0c9d8e7f
                    name: Docs site (v2)
                    permission_scope: []
                    status: active
                    sync_policy: null
                    sync_workflow:
                      canceled_at: null
                      checkpoint: queued
                      completed_at: null
                      created_at: '2026-09-06T02:00:00Z'
                      cursor: null
                      execution_attempts: 0
                      failure: null
                      id: d4c3b2a1-6f5e-4d7c-8b9a-0f1e2d3c4b5a
                      kind: sync
                      knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d
                      last_error_code: null
                      max_execution_attempts: 5
                      progress_completed: 0
                      progress_failed: 0
                      progress_skipped: 0
                      progress_total: null
                      source_id: 6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90
                      state: queued
                      updated_at: '2026-09-06T02:00:00Z'
                    type: web
                    updated_at: '2026-09-06T02:00:00Z'
                    uri: https://docs.example.com/v2
                    version: 8
              schema:
                $ref: '#/components/schemas/KnowledgeBaseSource'
          description: 更新后的数据源。
        '400':
          content:
            application/json:
              examples:
                knowledge_fs_invalid_request:
                  summary: knowledge_fs_invalid_request (validation)
                  value:
                    code: knowledge_fs_invalid_request
                    message: Agent Knowledge Base request is invalid.
                    status: 400
                    violations:
                      - field:
                          - name
                        type: string_too_long
                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
                  value:
                    code: knowledge_fs_invalid_request
                    failure:
                      category: validation
                      code: KNOWLEDGE_FS_INVALID_REQUEST
                      message: The Agent Knowledge Base request is invalid.
                      retryPolicy: never
                    message: The Agent Knowledge Base request is invalid.
                    status: 400
          description: >-
            - `knowledge_fs_invalid_request`：请求未通过校验。`violations`
            列出每个出错的字段。可能的原因：
              - 未传入任何可更新的字段。
              - `metadata` 含有 `parameters` 或 `syncPolicy`。
              - `providerParameters` 的键超过 50 个，或某个键的长度不在 1～255 个字符之间。
              - 某个值超出限制。
              - 请求体含有未知键。
            - `knowledge_fs_invalid_request`：更改被拒绝。可能的原因：
              - `metadata` 含有 `credentials` 对象，或 `providerParameters` 含有疑似凭据的键。
              - `metadata` 更改了 `datasource`、`pluginId`、`provider`、`providerId` 或 `providerKind`。
              - `web` 数据源的 `uri` 不是 HTTP 或 HTTPS URL，或内嵌了凭据。
            - `knowledge_fs_invalid_request`：`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:
                  summary: knowledge_fs_access_denied (key scope)
                  value:
                    code: knowledge_fs_access_denied
                    message: Agent Knowledge Base operation is not allowed.
                    status: 403
                knowledge_fs_access_denied_upstream:
                  summary: knowledge_fs_access_denied
                  value:
                    code: knowledge_fs_access_denied
                    failure:
                      action: contact_admin
                      category: authorization
                      code: KNOWLEDGE_FS_ACCESS_DENIED
                      message: >-
                        You do not have permission to perform this Agent
                        Knowledge Base operation.
                      retryPolicy: never
                    message: >-
                      You do not have permission to perform this Agent Knowledge
                      Base operation.
                    status: 403
          description: >-
            - `knowledge_fs_access_denied`：该密钥的访问范围限定为其他知识库、此知识库已关闭 **API
            访问**，或知识库未处于活动状态。

            - `knowledge_fs_access_denied`：该密钥无权访问此知识库的内容。

            - `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
                    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 的数据源、其
            `permission_scope` 不在该密钥的授权范围内，或对它的删除请求已被受理。

            - `not_found`：当前部署已关闭 Agent 知识库功能。
        '409':
          content:
            application/json:
              examples:
                knowledge_fs_conflict:
                  summary: knowledge_fs_conflict (stale version)
                  value:
                    code: knowledge_fs_conflict
                    failure:
                      action: retry
                      category: conflict
                      code: SOURCE_VERSION_CONFLICT
                      message: >-
                        The Agent Knowledge Base operation conflicts with the
                        current resource state.
                      retryPolicy: manual
                      traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b
                    message: >-
                      The Agent Knowledge Base operation conflicts with the
                      current resource state.
                    status: 409
          description: >-
            - `knowledge_fs_conflict`：`expectedVersion` 与当前的 `version`
            不一致。`failure.code` 为 `SOURCE_VERSION_CONFLICT`。重新读取数据源后重试。

            - `knowledge_fs_conflict`：`providerParameters` 会替换含有凭据的已存储参数。

            - `knowledge_fs_conflict`：知识库或此数据源正在删除中。

            - `knowledge_fs_conflict`：本次更新请求了同步，但启动同步时与数据源当前的运行冲突。


            如果已存储的参数含有凭据，此 API 无法替换它们。要进行其他受支持的更改，省略 `providerParameters` 即可。
        '413':
          content:
            application/json:
              examples:
                knowledge_fs_request_too_large:
                  summary: knowledge_fs_request_too_large (request budget)
                  value:
                    code: knowledge_fs_request_too_large
                    message: Agent Knowledge Base request is too large.
                    status: 413
          description: >-
            - `knowledge_fs_request_too_large`：Dify 补上默认值后，请求超过 262,144 个 UTF-8
            字节。参见
            [请求大小限制](/zh/api-reference/guides/knowledge-base#request-size-limits)。
        '502':
          content:
            application/json:
              examples:
                knowledge_fs_upstream_unavailable:
                  summary: knowledge_fs_upstream_unavailable
                  value:
                    code: knowledge_fs_upstream_unavailable
                    message: Agent Knowledge Base is unavailable.
                    status: 502
          description: >-
            - `knowledge_fs_upstream_unavailable`：未能及时收到响应，或无法读取响应。


            更新可能已经生效。用 [获取数据源](/zh/api-reference/sources/get-source)
            读取数据源，将当前值与预期的更改进行比对。


            如果发送了 `syncAfterUpdate: true`，用
            [获取数据源运行列表](/zh/api-reference/source-syncs-and-imports/list-source-runs)
            按 `sourceId` 筛选，查找该运行。


            不要为了确认同步是否已启动而修改 `expectedVersion` 后重新提交。
        '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` 处理。

            - `knowledge_fs_operation_unavailable`：本次更新请求了同步，但同步工作流或策略服务不可用。
components:
  schemas:
    KnowledgeBaseSource:
      properties:
        connection_id:
          description: 数据源获取凭据所用的连接。将其他数据源绑定到同一连接时，将此值作为 `connectionId` 传入。未绑定时为 `null`。
          nullable: true
          type: string
        created_at:
          description: 创建时间，ISO 8601 格式。
          type: string
        credential_configured:
          description: 数据源持有自己的凭据引用时为 `true`。未持有时为 `null`，例如绑定到连接的数据源。
          nullable: true
          type: boolean
        id:
          description: 数据源 ID。
          type: string
        knowledge_space_id:
          description: 知识库的内部 ID，并非路径中的知识库 ID。
          type: string
        last_synced_at:
          description: >-
            最近一次已完成的同步（`completed` 或 `zero_results`）或已完成导入的完成时间。仅
            [获取数据源列表](/zh/api-reference/sources/list-sources)
            设置此字段。其他操作中以及数据源从未同步时为 `null`。
          nullable: true
          type: string
        metadata:
          description: >-
            提供商设置，以及由服务端管理的同步或页面选择数据。可能包含提供商标识和
            `parameters`；由连接管理的设置不一定出现在此处。凭据类的键已移除。创建其他数据源时，不要复制整个对象。
          type: object
        name:
          description: 显示名称。
          type: string
        permission_scope:
          description: 读取此数据源所需的内容访问范围。列表为空表示在知识库内不额外限制内容，但知识库本身的授权仍然适用。
          items:
            type: string
          type: array
        status:
          description: >-
            `active`、`syncing`、`error` 或
            `disabled`。大多数操作返回存储的值。[获取数据源列表](/zh/api-reference/sources/list-sources)
            根据最近一次同步运行推导该值：


            - 运行为 `failed` 或 `canceled`：`error`

            - 运行为 `completed` 或 `zero_results`：`active`

            - 有进行中的运行：`syncing`


            `disabled` 永远不会被覆盖。
          type: string
        sync_policy:
          allOf:
            - $ref: '#/components/schemas/KnowledgeBaseSyncPolicy'
          description: >-
            数据源的定时同步设置。仅 [获取数据源列表](/zh/api-reference/sources/list-sources)
            设置此字段。其他操作中以及没有定时同步时为 `null`。可通过
            [获取同步策略](/zh/api-reference/sources/get-sync-policy) 单独读取，通过
            [更新同步策略](/zh/api-reference/sources/update-sync-policy) 修改。
          nullable: true
        sync_workflow:
          allOf:
            - $ref: '#/components/schemas/KnowledgeBaseSourceRun'
          description: >-
            数据源当前进行中的同步或导入运行（`crawl-import`、`online-document-import` 或
            `online-drive-import`），没有则为最近一次同步运行。[获取数据源列表](/zh/api-reference/sources/list-sources)
            在有运行正在进行或运行晚于数据源记录时设置此字段。[更新数据源](/zh/api-reference/sources/update-source)
            在该调用启动了同步时设置此字段。其他情况下为 `null`。抓取预览以及从抓取预览发起的导入不会出现在此处。


            要跟踪某次运行，用其 `id` 调用
            [获取数据源运行](/zh/api-reference/source-syncs-and-imports/get-source-run)。
          nullable: true
        type:
          description: >-
            `web`（网站抓取）、`connector`（在线文档或在线云盘）、`upload` 或 `object-storage`。


            `connector` 数据源的 `metadata.providerKind` 为 `online-document` 或
            `online-drive`，`web` 数据源则为 `website`。


            `upload` 和 `object-storage` 数据源由 Dify 填充。
          type: string
        updated_at:
          description: 最后变更时间，ISO 8601 格式。
          type: string
        uri:
          description: '`web` 数据源为抓取的根 URL。Dify 创建的连接器数据源为 `connector://<connection_id>`。'
          type: string
        version:
          description: >-
            数据源版本，每次写入都会递增。调用 [更新数据源](/zh/api-reference/sources/update-source)
            时将其作为 `expectedVersion` 传入，调用
            [删除数据源](/zh/api-reference/sources/delete-source) 时作为
            `expectedRevision` 传入，调用
            [更新同步策略](/zh/api-reference/sources/update-sync-policy) 时作为
            `expectedSourceVersion` 传入。
          type: integer
      type: object
    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
    KnowledgeBaseSourceRun:
      properties:
        canceled_at:
          description: 取消运行的时间。仅当 `state` 为 `canceled` 时有值，否则为 `null`。
          nullable: true
          type: string
        checkpoint:
          description: >-
            运行已到达的最后一步：`queued`、`provider-read`、`preview-staged`、`selection-frozen`、`materialized`、`cleanup-staging`
            或
            `source-committed`。无论运行停在哪个检查点，[重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run)
            都会从头开始运行。
          type: string
        completed_at:
          description: >-
            运行结束（`completed`、`zero_results`、`failed` 或 `canceled`）的时间，ISO 8601
            格式。运行期间为 `null`。
          nullable: true
          type: string
        created_at:
          description: 创建时间，ISO 8601 格式。
          type: string
        cursor:
          description: 运行恢复时所用的提供商游标。运行尚未翻页时为 `null`。
          nullable: true
          type: string
        execution_attempts:
          description: >-
            工作进程领取该运行的次数，包括
            [重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run)
            之后的领取，重试不会重置该值。
          type: integer
        failure:
          allOf:
            - $ref: '#/components/schemas/KnowledgeBaseErrorDetails'
          description: >-
            `state` 为 `failed` 时的错误详情。其中 `stage` 为失败时运行的 `checkpoint`，`traceId`
            为运行 ID。其他情况下为 `null`。
          nullable: true
        id:
          description: >-
            运行 ID，可传给
            [获取数据源运行](/zh/api-reference/source-syncs-and-imports/get-source-run)、[取消数据源运行](/zh/api-reference/source-syncs-and-imports/cancel-source-run)
            或
            [重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run)。
          type: string
        kind:
          description: >-
            运行的类型：


            - `sync`：由
            [同步数据源](/zh/api-reference/source-syncs-and-imports/sync-source)、[更新数据源](/zh/api-reference/sources/update-source)、定时同步或
            Dify 发起。

            - `crawl-preview`：由
            [预览网站抓取](/zh/api-reference/source-syncs-and-imports/preview-website-crawl)
            发起。[导入所选页面](/zh/api-reference/source-syncs-and-imports/import-selected-pages)
            从该预览导入时，类型保持不变。

            - `crawl-import`：由
            [导入网站页面](/zh/api-reference/source-syncs-and-imports/import-website-pages)
            发起。

            - `online-document-import`、`online-drive-import`：由
            [导入数据源条目](/zh/api-reference/source-syncs-and-imports/import-source-items)
            发起。


            在 Dify 中添加或编辑数据源时，Dify 也会发起预览和导入。
          type: string
        knowledge_space_id:
          description: 知识库的内部 ID，并非路径中的知识库 ID。
          type: string
        last_error_code:
          description: '`state` 为 `failed` 时为 `failure.code` 的值，否则为 `null`。'
          nullable: true
          type: string
        max_execution_attempts:
          description: >-
            `execution_attempts`
            的上限。达到上限后，[重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run)
            返回 `409`。
          type: integer
        progress_completed:
          description: 已处理完的项数，包括同步时检查过但未变化的项。
          type: integer
        progress_failed:
          description: 数据源运行始终为 `0`：任一项失败都会导致整个运行失败。
          type: integer
        progress_skipped:
          description: 数据源运行始终为 `0`。
          type: integer
        progress_total:
          description: >-
            运行预计处理的项数：导入请求的页面或条目数、抓取预览目前已暂存的页面数，或同步列出数据源条目后的条目数。确定之前为 `null`。


            [导入网站页面](/zh/api-reference/source-syncs-and-imports/import-website-pages)
            的运行抓取 URL 期间，`progress_completed` 和 `progress_total` 都统计目前已抓取的页面数。所有
            URL 抓取完成后，进度从 `0` 重新开始计，总数变为 URL 的数量。
          nullable: true
          type: integer
        source_id:
          description: 运行所属的数据源。
          nullable: true
          type: string
        state:
          description: >-
            运行的进度。


            进行中的状态：


            - `queued`：等待工作进程处理

            - `crawling`：抓取预览正在获取页面

            - `preview_ready`：抓取预览正在等待
            [导入所选页面](/zh/api-reference/source-syncs-and-imports/import-selected-pages)
            或
            [取消数据源运行](/zh/api-reference/source-syncs-and-imports/cancel-source-run)

            - `importing`：正在导入并索引条目

            - `syncing`：正在刷新数据源的文档


            终态：


            - `completed`：所有条目均已导入或刷新、完成索引并生效

            - `zero_results`：抓取预览未找到任何页面

            - `failed`：详见 `failure`

            - `canceled`


            `failed` 或 `canceled`
            之后，[重试数据源运行](/zh/api-reference/source-syncs-and-imports/retry-source-run)
            会再次执行该运行，[同步数据源](/zh/api-reference/source-syncs-and-imports/sync-source)
            则会发起新的同步。
          type: string
        updated_at:
          description: 最后变更时间，ISO 8601 格式。
          type: string
      type: object
    KnowledgeBaseErrorDetails:
      properties:
        action:
          description: >-
            建议的下一步操作（如有）：`configure_model`、`configure_parser`、`configure_source`、`contact_admin`、`reupload`
            或 `retry`。不适用时为 `null`。HTTP 错误响应体中不包含此字段。
          nullable: true
          type: string
        category:
          description: >-
            失败类别：`authorization`、`canceled`、`configuration`、`conflict`、`dependency`、`internal`、`not_found`、`rate_limit`、`timeout`
            或 `validation`。
          type: string
        code:
          description: >-
            稳定的错误码，采用大写蛇形命名，例如 `KNOWLEDGE_FS_CONFLICT` 或
            `SOURCE_CREDENTIAL_TEST_FAILED`。
          type: string
        message:
          description: 错误码或失败类别对应的公开消息。不会暴露提供商的错误详情。
          type: string
        parameters:
          additionalProperties: true
          description: >-
            描述失败细节的值，最多 8 个，键取自
            `attempt`、`currentRowVersion`、`documentCount`、`expectedRowVersion`、`fileSizeBytes`、`limit`、`maxFileSizeBytes`、`maxItems`、`modelType`、`providerKind`、`retryAfterSeconds`
            和 `status`。没有时为 `null`。HTTP 错误响应体中不包含此字段。
          nullable: true
          type: object
        retryPolicy:
          description: >-
            重试是否有用：`automatic`（服务会自动重试）、`manual`（需自行重试）、`after_configuration`（先在
            Dify 中修正知识库配置）或 `never`（需修改请求）。
          type: string
        stage:
          description: >-
            失败所在的阶段，例如 `query_generation` 或 `credential-test`。不适用时为 `null`。HTTP
            错误响应体中不包含此字段。
          nullable: true
          type: string
        traceId:
          description: 联系管理员时需提供的参考编号。在包含失败详情的成功响应中可能为 `null`，在 HTTP 错误响应体中可能不出现。
          nullable: true
          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.