IBM Cloud Docs
使用文件状态网络钩子 API

使用文件状态网络钩子 API

当摄入文档的状态变为 available 或 failed 时，可以使用文档状态 Webhook 功能将 Webhook 事件发送到外部应用程序。 Webhook 事件可帮助您对已建立索引的文档执行下一个操作，而不必首先通过 获取文档详细信息 API来获取文档状态。

IBM Cloud Pak for Data 当您在隔离的环境中运行xml-ph-0000@deepl.internal时，必须通过xml-ph-0001@deepl.internal代理连接到外部应用程序。IBM Software Hub 当您在隔离的环境中运行 时，必须通过 代理连接到外部应用程序。Discovery HTTP 更多信息，请参阅 在隔离环境中设置 HTTP 代理。

要使用文档状态 Webhook 功能，请执行以下操作:

  1. 设置可从 Discovery接收 Webhook 通知的外部应用程序。

    要执行此操作，必须使用 create collection 或 update collection API 方法将外部应用程序注册为集合上的 Webhook 端点。 有关更多信息，请参阅 API 参考中的 创建集合 或 更新集合。

    外部应用程序接收 Webhook ping 事件，这将通知您已成功创建 Webhook。 必须可从 IBM Cloud访问外部应用程序。

  2. 将文档采集到集合中。 当摄入文档的状态变为 available 或 failed 时，外部应用程序将接收 document.status Webhook 事件。

    您可以验证 document.status Webhook 事件的 data 对象中摄入文档的状态。 document_ids 和 status 参数显示摄入文档的标识及其状态。 有关更多信息，请参阅 ping 事件的数据模型 和 document.status 事件的数据模型。

下图显示了网络挂钩配置流程。

显示文件状态网络钩子功能配置流程
文件状态网络钩子功能配置

下图显示了文档状态 Webhook 功能部件过程流。

显示文档状态网络钩子功能流程
文档状态网络钩子功能
*

有关查询 API 的更多信息，请参阅 API 参考中的 查询项目 API 方法。

您还可以参考 webhook-doc-status-sample 应用程序以获取文档状态 Webhook API 功能。 要查看样本应用程序，您必须有权访问 Discovery doc-tutorial-download 存储库。

为网络钩子安全自动识别请求

要认证 Webhook 请求，请验证随请求一起发送的 JSON Web 令牌 (JWT)。 Webhook 微服务会自动生成 JWT，并通过每个 Webhook 调用在 Authorization 头中发送该 JWT。 您负责向用于验证 JWT 的外部服务添加代码。

系统可以根据您指定的 sample secret 生成 JWT，并且在 Authorization 头中，可以将此系统生成的 JWT 传递到外部应用程序。 如果在 header 中指定值，那么 Webhook 微服务会将该值发送到外部应用程序，而不是 JWT。

例如，如果在 创建集合 或 更新集合 API 的 Webhook 对象的 Secret 字段中指定 sample secret，那么可以在 Node.js: 中添加如下所示的样本代码:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'sample secret');
} catch(err) {
  // error thrown if token is invalid
}

ping 事件的数据模型

以下是 ping 事件参数:

Ping 事件
参数 描述
event 事件名称为 ping。
instance_id Discovery 实例ID。
version Discovery API 版本，格式为 yyyy-mm-dd。
data

一个包含事件信息的对象： url 、 events 和 metadata 。

  • url ：配置的webhook端点（ URL ）。

  • events ：事件字符串值的数组。 此数组中的事件被发送到网络钩子 URL。

  • metadata ：一个包含特定于创建的网络钩子的信息的对象。
created_at 创建活动的日期和时间。

例如，以下是发送到 Webhook 的 ping 事件:

POST https://example.com/webhook

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
  "event": "ping",
  "version": "2023-03-31",
  "instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
  "data": {
    "url": "https://example.com/webhook",
    "events": [
      "document.status"
    ],
    "metadata": {
      "project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
      "collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b"
    }
  },
  "created_at": "2023-08-16T08:34:46.000Z"
}

document.status 事件的数据模型

以下是 document.status 事件参数:

Document.status 事件
参数 描述
event 事件名称为 document.status。
instance_id Discovery 实例ID。
version Discovery API 版本，格式为 yyyy-mm-dd。
data 具有特定于事件的信息的对象: project_id，collection_id 和 document_ids。
status 文件状态。
created_at 创建活动的日期和时间。

例如，以下是发送到 Webhook 的 document.status 事件:

POST https://example.com/webhook

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
  "event": "document.status",
  "version": "2023-03-31",
  "instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
  "data": {
    "project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
    "collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b",
    "document_ids": [
      "1a5d4916-6097-4150-977a-ca897226565b",
      "2a5d4916-6097-4150-977a-ca897226565b"
    ],
    "status": "available"
  },
  "created_at": "2023-08-16T08:34:46.000Z"
}