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)。

Headers

Idempotency-Key
string
required

用同一个 API 密钥对同一个数据源重复发送相同的键,会返回原运行及其当前状态,不会启动新的运行。每打算启动一次预览,都使用新的键。使用可打印 ASCII 字符,首尾不得有空白。

Required string length: 8 - 255

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,通过 获取数据源列表 获取。

Response

运行,其中 kind: crawl-preview、state: queued。

canceled_at
string | null

取消运行的时间。仅当 state 为 canceled 时有值,否则为 null。

checkpoint
string

运行已到达的最后一步:queued、provider-read、preview-staged、selection-frozen、materialized、cleanup-staging 或 source-committed。无论运行停在哪个检查点,重试数据源运行 都会从头开始运行。

completed_at
string | null

运行结束(completed、zero_results、failed 或 canceled)的时间,ISO 8601 格式。运行期间为 null。

created_at
string

创建时间,ISO 8601 格式。

cursor
string | null

运行恢复时所用的提供商游标。运行尚未翻页时为 null。

execution_attempts
integer

工作进程领取该运行的次数,包括 重试数据源运行 之后的领取,重试不会重置该值。

failure
object | null

state 为 failed 时的错误详情。其中 stage 为失败时运行的 checkpoint,traceId 为运行 ID。其他情况下为 null。

kind
string

运行的类型:

在 Dify 中添加或编辑数据源时,Dify 也会发起预览和导入。

knowledge_space_id
string

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

last_error_code
string | null

state 为 failed 时为 failure.code 的值,否则为 null。

max_execution_attempts
integer

execution_attempts 的上限。达到上限后,重试数据源运行 返回 409。

progress_completed
integer

已处理完的项数,包括同步时检查过但未变化的项。

progress_failed
integer

数据源运行始终为 0:任一项失败都会导致整个运行失败。

progress_skipped
integer

数据源运行始终为 0。

progress_total
integer | null

运行预计处理的项数:导入请求的页面或条目数、抓取预览目前已暂存的页面数,或同步列出数据源条目后的条目数。确定之前为 null。

导入网站页面 的运行抓取 URL 期间,progress_completed 和 progress_total 都统计目前已抓取的页面数。所有 URL 抓取完成后,进度从 0 重新开始计,总数变为 URL 的数量。

source_id
string | null

运行所属的数据源。

state
string

运行的进度。

进行中的状态:

  • queued:等待工作进程处理
  • crawling:抓取预览正在获取页面
  • preview_ready:抓取预览正在等待 导入所选页面 或 取消数据源运行
  • importing:正在导入并索引条目
  • syncing:正在刷新数据源的文档

终态:

  • completed:所有条目均已导入或刷新、完成索引并生效
  • zero_results:抓取预览未找到任何页面
  • failed:详见 failure
  • canceled

failed 或 canceled 之后,重试数据源运行 会再次执行该运行,同步数据源 则会发起新的同步。

updated_at
string

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