Skip to main content
PATCH
更新数据源

Authorizations

Authorization
string
header
required

每个请求都通过 API Key 认证:Authorization: Bearer {API_KEY}。应用接口使用应用 API Key,知识库接口使用知识库 API Key(快速开始)。

API Key 应保存在服务端,切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP 401(unauthorized)。

Path Parameters

knowledge_base_id
string<uuid>
required

知识库 ID:即知识库 API 访问 对话框中所示服务 API 端点的最后一段(…/knowledge-fs/spaces/<knowledge base ID>),也是地址栏中 /datasets/new/ 之后的那一段。

source_id
string<uuid>
required

数据源 ID,通过 获取数据源列表 获取。

Body

application/json

标记为 nullable 的可选字段,传 null 等同于省略。

规范化后的请求不得超过 262,144 个 UTF-8 字节。参见 请求大小限制。

至少提供一个非 null 的 metadata、name、providerParameters、status 或 uri。只有 expectedVersion 和 syncAfterUpdate 不构成更新。

metadata
object
required

要合并进已存储元数据的键。嵌套对象会合并,数组会整体替换。

不得包含 parameters(改用 providerParameters)或凭据。datasource、pluginId、provider、providerId 和 providerKind 不可更改。服务端会覆盖 tenantId。

expectedVersion
integer | null

数据源当前的 version,取自 获取数据源列表 或 获取数据源。值已过时则返回 409,不做任何更改。省略则以最后一次写入为准。

Required range: x >= 1
name
string | null

新的显示名称。

Required string length: 1 - 200
providerParameters
object | null

所选数据源定义的参数。此字段会整体替换已存储的 metadata.parameters 对象,因此需包含所有要保留的值。值可以是布尔值、有限数值或字符串。疑似凭据的键会被拒绝。

如果 获取数据源 未返回完整的非敏感参数,而你也不清楚该数据源的参数约定,改在 Dify 中配置数据源。

status
enum<string> | null

新状态。可设为 active 或 disabled。error 和 syncing 由同步运行设置。

disabled 会阻止新的定时同步,也会阻止本次更新启动同步,但不会取消已受理的同步。

Available options:
active,
disabled,
null
syncAfterUpdate
boolean | null

为 true 时,在写入后请求一次同步运行。响应在 sync_workflow 中返回该运行;本次调用未启动同步时,返回 sync_workflow: null。

只有本次调用更改了 uri、providerParameters 或某个 metadata 值,且数据源的 status 不是 disabled 时,才会启动同步。重新发送当前值不会启动同步。如需在不更改数据源的情况下同步,调用 同步数据源。

对于已保存页面列表的网站数据源,同步会刷新这些页面。要更改页面列表,使用 导入网站页面 或 导入所选页面。

uri
string | null

新的 URI。web 数据源的 URI 必须是 HTTP 或 HTTPS URL,且不能内嵌凭据。metadata.parameters.url 会随之更新。

Required string length: 1 - 4096

Response

更新后的数据源。

connection_id
string | null

数据源获取凭据所用的连接。将其他数据源绑定到同一连接时,将此值作为 connectionId 传入。未绑定时为 null。

created_at
string

创建时间,ISO 8601 格式。

credential_configured
boolean | null

数据源持有自己的凭据引用时为 true。未持有时为 null,例如绑定到连接的数据源。

id
string

数据源 ID。

knowledge_space_id
string

知识库的内部 ID,并非路径中的知识库 ID。

last_synced_at
string | null

最近一次已完成的同步(completed 或 zero_results)或已完成导入的完成时间。仅 获取数据源列表 设置此字段。其他操作中以及数据源从未同步时为 null。

metadata
object

提供商设置,以及由服务端管理的同步或页面选择数据。可能包含提供商标识和 parameters;由连接管理的设置不一定出现在此处。凭据类的键已移除。创建其他数据源时,不要复制整个对象。

name
string

显示名称。

permission_scope
string[]

读取此数据源所需的内容访问范围。列表为空表示在知识库内不额外限制内容,但知识库本身的授权仍然适用。

status
string

active、syncing、error 或 disabled。大多数操作返回存储的值。获取数据源列表 根据最近一次同步运行推导该值:

  • 运行为 failed 或 canceled:error
  • 运行为 completed 或 zero_results:active
  • 有进行中的运行:syncing

disabled 永远不会被覆盖。

sync_policy
object | null

数据源的定时同步设置。仅 获取数据源列表 设置此字段。其他操作中以及没有定时同步时为 null。可通过 获取同步策略 单独读取,通过 更新同步策略 修改。

sync_workflow
object | null

数据源当前进行中的同步或导入运行(crawl-import、online-document-import 或 online-drive-import),没有则为最近一次同步运行。获取数据源列表 在有运行正在进行或运行晚于数据源记录时设置此字段。更新数据源 在该调用启动了同步时设置此字段。其他情况下为 null。抓取预览以及从抓取预览发起的导入不会出现在此处。

要跟踪某次运行,用其 id 调用 获取数据源运行。

type
string

web(网站抓取)、connector(在线文档或在线云盘)、upload 或 object-storage。

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

upload 和 object-storage 数据源由 Dify 填充。

updated_at
string

最后变更时间,ISO 8601 格式。

uri
string

web 数据源为抓取的根 URL。Dify 创建的连接器数据源为 connector://<connection_id>。

version
integer

数据源版本,每次写入都会递增。调用 更新数据源 时将其作为 expectedVersion 传入,调用 删除数据源 时作为 expectedRevision 传入,调用 更新同步策略 时作为 expectedSourceVersion 传入。