ドキュメントステータスWebhook APIの使用
ドキュメント状況 Webhook 機能を使用して、取り込まれたドキュメントの状況が available または failed になったときに、Web フック・イベントを外部アプリケーションに送信できます。 Webhook イベントは、索引付けされた文書に対して次のアクションを実行するのに役立ちます。最初に 文書詳細の取得 APIを使用して文書状況を取得する必要はありません。
IBM Cloud Pak for DataIBM Software Hub Discovery をネットワークから隔離された環境で実行する場合は、 プロキシを経由して外部アプリケーションに接続する必要があります。 HTTP 詳細については 、「 HTTP プロキシをネットワークから隔離された環境で設定する 」を参照してください。
ドキュメント状況 Webhook 機能を使用するには、以下を実行します。
-
Discoveryから Webhook 通知を受信できる外部アプリケーションをセットアップします。
これを行うには、
create collectionまたはupdate collectionAPI メソッドを使用して、外部アプリケーションをコレクション上の Webhook エンドポイントとして登録する必要があります。 詳しくは、API リファレンスの コレクションの作成 または コレクションの更新 を参照してください。外部アプリケーションは、Webhook が正常に作成されたことを通知する Webhook
pingイベントを受け取ります。 外部アプリケーションは、 IBM Cloudからアクセス可能でなければなりません。 -
文書をコレクションに取り込みます。 取り込まれた文書の状況が
availableまたはfailedになると、外部アプリケーションはdocument.statusWebhook イベントを受け取ります。document.statusWeb フック・イベントのdataオブジェクトで、取り込まれたドキュメントの状況を確認できます。document_idsパラメーターとstatusパラメーターは、取り込まれた文書の ID とその状況を示します。 詳しくは、pingイベントのデータ・モデル およびdocument.statusイベントのデータ・モデル を参照してください。
次の図は、ウェブフックの設定の流れを示しています。
以下のイメージは、ドキュメント状況 Webhook フィーチャーのプロセス・フローを示しています。
照会 API について詳しくは、API リファレンスの Query a project API method を参照してください。
文書状況 Webhook API 機能については、webhook-doc-status-sample アプリケーションを参照することもできます。 サンプル・アプリケーションを表示するには、Discovery doc-tutorial-downloads リポジトリーにアクセスできる必要があります。
ウェブフックのセキュリティのためにリクエストを認証する
Webhook 要求を認証するには、要求とともに送信される JSON Web トークン (JWT) を確認します。 Webhook マイクロサービスは、自動的に JWT を生成し、各 Webhook 呼び出しとともに Authorization ヘッダーで送信します。 JWT を検証する外部サービスにコードを追加するのはユーザーの責任です。
システムは、指定された sample secret に基づいて JWT を生成でき、 Authorization ヘッダーで、このシステム生成 JWT を外部アプリケーションに渡すことができます。 header で値を指定すると、Web フック・マイクロサービスはその値を JWT ではなく外部アプリケーションに送信します。
例えば、 コレクションの作成 API または コレクションの更新 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 |
イベント情報を持つオブジェクト：
|
created_at |
イベントが作成された日時。 |
例えば、Web フックに送信される 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 イベント・パラメーターを示します。
| パラメーター | 説明 |
|---|---|
event |
イベント名は document.status です。 |
instance_id |
Discovery のインスタンスID。 |
version |
Discovery API バージョン (形式は yyyy-mm-dd)。 |
data |
イベント固有の情報 ( project_id、 collection_id、および document_ids) を持つオブジェクト。 |
status |
書類のステータス。 |
created_at |
イベントが作成された日時。 |
例えば、Web フックに送信される 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"
}