Skip to main content
POST
创建数据源

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/ 之后的那一段。

Body

application/json

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

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

name
string
required

显示名称。

Required string length: 1 - 200
type
enum<string>
required

网站抓取传 web,在线文档或在线云盘提供商传 connector(并设置 metadata.providerKind)。upload 和 object-storage 用于由 Dify 填充内容的数据源。

Available options:
connector,
object-storage,
upload,
web
uri
string
required

web 数据源填抓取的根 URL。connector 数据源填 connector://<connectionId>,与 Dify 写入的格式一致。

Required string length: 1 - 4096
connectionId
string<uuid> | null

为数据源提供读取凭据的连接。必须属于此知识库,且处于 active 状态。取自 获取数据源连接列表 返回的 id。

metadata
object

提供商设置,以及你自己的非敏感元数据。添加唯一的 client_request_id,可在创建响应丢失时识别出此数据源。该值会随数据源一起返回,但 API 不校验其唯一性,也不会对请求去重。

将 providerKind 设为连接的 configuration.providerKind,并选择与之匹配的数据源 type。来自连接的设置可能不会出现在数据源响应中。

如果基于现有数据源的响应构造 metadata,需去掉以 __knowledgeFs 开头的字段、credentials 以及 parameters 对象。credentialId 若存在,指向 Dify 保存的凭据。

permissionScope
string[]

留空或省略。仅接受空列表。

status
enum<string> | null
default:active

disabled 会暂停定时同步。

Available options:
active,
disabled,
null

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 传入。