使用文件狀態 Webhook API

當所汲取文件的狀態變成 available 或 failed 時，您可以使用文件狀態 Webhook 特性，將 Webhook 事件傳送至外部應用程式。 Webhook 事件可協助您對已編製索引的文件採取下一個動作，而不需要先透過 取得文件詳細資料 API取得文件狀態。

IBM Cloud Pak for DataIBM Software Hub 當您在 air-gapped 環境中執行 時，您必須透過 proxy 連線到外部應用程式。Discovery HTTP 如需詳細資訊，請參閱 在空氣封閉環境中設定 HTTP proxy。

若要使用文件狀態 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 參數會顯示所吸收文件的 ID 及其狀態。 如需相關資訊，請參閱 ping 事件的資料模型 及 document.status 事件的資料模型。

下列影像顯示 Webhook 配置流程。

顯示文件狀態 webhook 功能設定流程
文件狀態 webhook 功能設定流程

下列影像顯示文件狀態 Webhook 特性程序流程。

顯示文件狀態 Webhook 功能流程
文件狀態 Webhook 功能流程

如需查詢 API 的相關資訊，請參閱 API 參考資料中的 查詢專案 API 方法。

您也可以參閱 webhook-doc-status-sample 應用程式，以取得文件狀態 Webhook API 特性。 若要檢視範例應用程式，您必須具有探索 doc-tutorial-downloads 儲存庫的存取權。

驗證 Webhook 安全性請求

若要鑑別 Webhook 要求，請驗證隨要求一起傳送的 JSON Web 記號 (JWT)。 Webhook 微服務會自動產生 JWT，並隨每一個 Webhook 呼叫在 Authorization 標頭中傳送它。 您必須負責將程式碼新增至驗證 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 事件參數:

連線測試事件
參數 說明
event 事件名稱為 ping。
instance_id Discovery 範例 ID。
version Discovery API 版本，格式為 yyyy-mm-dd。
data

包含事件資訊的物件： url, events, 和 metadata 。

  • url : 已設定的 webhook 端點 ( URL )。

  • events ：一個事件字串值陣列。 這個陣列中的事件會被傳送到 webhook URL。

  • metadata ：包含特定於已建立 webhook 的資訊的物件。
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"
}