外部エンリッチメントAPIの使用

分析 API では、外部エンリッチ機能はサポートされていません。

外部エンリッチ機能を使用すると、任意のモデルを使用して文書にアノテーションを付けることができます。 Webhook インターフェースを介して、コレクション内の文書をエンリッチするために、カスタム・モデルまたは拡張ファウンデーション・モデル、およびその他のサード・パーティー・モデルを使用できます。 文書は外部アプリケーションによってエンリッチされ、Discovery プロジェクト内のコレクションにマージされます。

IBM Cloud Pak for DataIBM Software Hub Discovery をネットワークから隔離された環境で実行する場合は、 プロキシを経由して外部アプリケーションに接続する必要があります。 HTTP 詳細については 、「 HTTP プロキシをエアギャップ環境で設定する 」を参照してください。

外部エンリッチ機能を使用する場合は、以下を実行します。

  1. Discovery から Webhook 通知を受信して文書にアノテーションを付けることができる外部アプリケーションをセットアップします。

    これを行うには、 create enrichment メソッドを使用して、外部アプリを Web フック・エンドポイントとしてプロジェクトに登録する必要があります。 詳しくは、API リファレンスの エンリッチの作成 を参照してください。

    プロジェクトの外部エンリッチメントをセットアップすると、プロジェクト内のすべてのコレクションで使用できるようになります。 外部アプリケーションは、外部エンリッチが作成されたことを通知する Webhook ping イベントも受信します。

  2. 外部エンリッチを適用するコレクションを指定します。 API を使用して、外部エンリッチをコレクションに適用できます。 詳しくは、 API を使用したエンリッチメントの管理 を参照してください。

    あるいは、ユーザー・インターフェースで 「コレクションの管理」 ページを参照し、外部エンリッチを適用するコレクションを選択することもできます。 次に、 「エンリッチメント (Enrichments)」 タブを開き、外部エンリッチメントをコレクション内のフィールドに適用します。

    文書が処理されるか、このコレクションにアップロードされると、Discovery は固有の batch_id を持つ文書のバッチを作成します。 外部アプリケーションは、バッチをプルする準備ができたことを通知する Webhook enrichment.batch.created イベントも受け取ります。 外部アプリケーションは、外部エンリッチのために Discovery からバッチをプルできます。

    外部アプリケーションがシャットダウンするか、その間に再始動する場合、「バッチのリスト (List batches)」メソッドを使用して以下を取得できます。

    • 外部エンリッチ・アプリケーションによってまだプルされていない通知済みバッチ。
    • プルされたが、外部エンリッチ・アプリケーションによってまだ Discovery にプッシュされていないバッチ。

    詳しくは、API リファレンスの バッチのリスト を参照してください。

  3. 外部アプリケーションによるエンリッチのために Discovery から文書をプルするには、 pull batches メソッドで Discovery によって提供される batch_id を指定します。 詳しくは、API リファレンスの プル・バッチ を参照してください。

    pull batches メソッドは、ディスカバリーからバイナリー添付ファイルを返します。 バイナリー添付ファイルについて詳しくは、 プル・バッチ・メソッドからのバイナリー添付ファイル を参照してください。

  4. 外部エンリッチメントがバッチ内の文書にアノテーションを付けた後に、 push batches メソッドで同じ batch_id を指定します。 詳しくは、API リファレンスの Push batches を参照してください。

    文書はバイナリー添付ファイルとして Discovery にプッシュされます。 詳しくは、 push batches メソッドでのバイナリー添付ファイル を参照してください。

  5. コレクション内の文書がマージされ、索引付けされていることを確認します。 ドキュメントには、外部アプリケーションによって適用されるアノテーションが含まれている必要があります。

ウェブフックのセキュリティのためにリクエストを認証する

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 イベント・パラメーターを示します。

ping イベント
パラメーター 説明
event イベント名は ping です。
instance_id Discovery のインスタンスID。
version Discovery API バージョン (形式は yyyy-mm-dd)。
data

イベント情報を持つオブジェクト： url 、 events 、 metadata。

  • url ：設定されたウェブフックエンドポイント（ URL ）。

  • events ：イベント文字列値の配列。 この配列のイベントはウェブフック URL に送信されます。

  • metadata ：作成されたウェブフックに固有の情報を持つオブジェクト。
created_at イベントが作成された日時。

enrichment.batch.created イベントのデータ・モデル

以下に、 enrichment.batch.created イベント・パラメーターを示します。

Enrichment.batch.created
パラメーター 説明
event イベント名は enrichment.batch.created です。
instance_id Discovery インスタンスの UUID。これはテナント ID とも呼ばれます。
version Webhook イベント・バージョンの日付 ( yyyy-mm-dd 形式)。
data

イベント固有の情報 ( project_id、 collection_id、 enrichment_id、および batch_id) を持つオブジェクト。

  • project_id: プロジェクトの Universally Unique Identifier (UUID)。

  • collection_id: コレクションの Universally Unique Identifier (UUID)。

  • enrichment_id: エンリッチメントの Universally Unique Identifier (UUID)。

  • batch_id: Universally Unique Identifier (UUID)。
created_at イベントが作成された日時。

外部エンリッチの制限

外部エンリッチメントの制限
プラン コレクションごとの Webhook エンリッチの最大量 テナントごとの Webhook エンリッチの最大量
エンタープライズ 1 100
プラス 1 10
プレミアム 1 100

Pull Batches メソッドからのバイナリー添付ファイル

pull batches メソッドは、ディスカバリーからバイナリー添付ファイルを返します。

返されるファイルは、圧縮された改行区切り JSON (NDJSON) ファイルです。 このファイルには、文書プロパティーを表す構造化データが含まれています。 例えば、以下は NDJSON ファイルに含まれている JSON 値です。

{
    "document_id": "3bafc09abfaacd90d66f57181b50d041",
    "location_encoding": "utf-16",
    "language": "en",
    "artifact": "{\"text_positions\":[0,21],\"space_above\":93.07864284515381,\"space_below\":32.53530788421631,\"is_start_of_block\":true,\"image_id\":-1}{\"text_positions\":[22,63],\"space_above\":32.53530788421631,\"space_below\":13.935576438903809,\"is_start_of_block\":true,\"image_id\":-1}{\"parent_document_id\":\"3bafc09abfaacd90d66f57181b50d041\",\"source\":{\"ListId\":\"f0ac1d32-b9e5-41af-b9da-e1e37e965d99\",\"UniqueId\":\"357d7a48-4460-442c-be56-d8bdd40a8c36\",\"ServerRelativeUrl\":\"/Lists/list1/Attachments/1/addattachments.csv\",\"FileNameAsPath\":{\"DecodedUrl\":\"addattachments.csv\"},\"ListItemId\":\"284dcb51-8021-56d0-9213-7f4eb134e083\",\"FileName\":\"addattachments.csv\",\"ServerRelativePath\":{\"DecodedUrl\":\"/Lists/list1/Attachments/1/addattachments.csv\"},\"WebId\":\"ad5bf592-3b4e-4dd1-bd3e-abc0ef179b03\"},\"ingest_datetime\":\"2023-06-26T09:24:02.573Z\",\"application_id\":\"sharepoint\",\"application_sub_type\":\"ListItemAttachmentCollection\"}0.51vanilla ice creamcontamination_tamperingotherchange_of_propertiesI love the ads for the new milk chocolate. Could you tell me the name of the actor in the commercial?{\"metadata\":{\"numPages\":\"54\",\"title\":\"\",\"publicationdate\":\"2010-06-03\"},\"info\":{\"histogram\":{\"mean-char-height\":{},\"mean-char-width\":{},\"number-of-chars\":{}},\"styles\":[]}}1451692800000",
    "features": [
        {
            "type": "field",
            "location": {
                "begin": 0,
                "end": 128
            },
            "properties": {
                "field_name": "multi_nested",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 128,
                "end": 258
            },
            "properties": {
                "field_name": "multi_nested",
                "field_index": 1,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 258,
                "end": 889
            },
            "properties": {
                "field_name": "metadata",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 889,
                "end": 892
            },
            "properties": {
                "field_name": "claim_score",
                "field_index": 0,
                "field_type": "double"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 892,
                "end": 893
            },
            "properties": {
                "field_name": "claim_id",
                "field_index": 0,
                "field_type": "long"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 893,
                "end": 910
            },
            "properties": {
                "field_name": "claim_product",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 910,
                "end": 933
            },
            "properties": {
                "field_name": "label",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 933,
                "end": 938
            },
            "properties": {
                "field_name": "label",
                "field_index": 1,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 938,
                "end": 958
            },
            "properties": {
                "field_name": "label",
                "field_index": 2,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 958,
                "end": 1059
            },
            "properties": {
                "field_name": "body",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 1059,
                "end": 1230
            },
            "properties": {
                "field_name": "nested",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 1230,
                "end": 1243
            },
            "properties": {
                "field_name": "claim_date",
                "field_index": 0,
                "field_type": "date"
            }
        }
    ]
}

バイナリー・ファイルのプロパティーは以下のとおりです。

Pull メソッドのバイナリー・ファイル・プロパティー
プロパティー タイプ 説明
document_id string 文書の識別子。
location_encoding string 各フィーチャーのロケーションを計算するために使用されるエンコード・タイプ。 サポートされるタイプは、 utf-8、 utf-16、および utf-32 です。 外部エンリッチ・アプリケーションは、Discovery からの対応する文書の location_encoding に基づいて、各フィーチャーの場所を計算する必要があります。 データのストリング表現でのフィーチャーの場所は、外部エンリッチの実装に使用されるプログラミング言語のエンコード・タイプによって異なります。 例えば、C++ と Go は UTF-8を使用し、 Java と JavaScript は UTF-16を使用し、 Python は UTF-32を使用します。
language string 文書の内容の言語。
artifact string すべてのテキスト値のパッケージ。
features array 文書内の機能のリスト。 詳細は、 機能の種類 を参照してください。

バッチ・プッシュ・メソッドでのバイナリー添付ファイル

外部エンリッチの後、文書を push batches メソッドのバイナリー添付ファイルとして Discovery にプッシュできます。

このファイルは、文書プロパティーを表す構造化データを含む圧縮 NDJSON ファイルでなければなりません。 例えば、次のような NDJSON ファイルがあるとします。

{
  "document_id": "3bafc09abfaacd90d66f57181b50d041",
  "features": [
    {
      "type": "annotation",
      "location": {
        "begin": 958,
        "end": 1000
      },
      "properties": {
        "type": "element_classes",
        "class_name": "expression",
        "confidence": 0.7905777096748352
      }
    },
    {
      "type": "annotation",
      "location": {
        "begin": 1001,
        "end": 1059
      },
      "properties": {
        "type": "element_classes",
        "class_name": "question",
        "confidence": 0.9507029056549072
      }
    },
    {
      "type": "annotation",
      "location": {
        "begin": 1035,
        "end": 1040
      },
      "properties": {
        "type": "entities",
        "entity_type": "JobTitle",
        "entity_text": "actor",
        "confidence": 0.70953685
      }
    },
    {
      "type": "annotation",
      "properties": {
        "type": "document_classes",
        "class_name": "amount.shortage",
        "confidence": 0.43297016620635986
      }
    },
    {
      "type": "notice",
      "properties": {
        "description": "something wrong happened",
      }
    },
    {
      "type": "notice",
      "properties": {
        "description": "something wrong happened again",
        "created": 1689076276402,
      }
    }
  ]
}

バイナリー・ファイルのプロパティーは以下のとおりです。

プッシュ方式のバイナリー・ファイル・プロパティー
プロパティー タイプ 説明
document_id string 文書の識別子。
features array 文書内の機能のリスト。 詳細は、 機能の種類 を参照してください。

フィーチャー・タイプ

フィーチャー type は、バイナリー・ファイル内で以下のいずれかにすることができます。

フィーチャー・タイプ
機能 タイプ 説明
field string 文書の特定のフィールド値を表します。
annotation string 文書を強化できる特定のアノテーションを表します。
notice string 文書エンリッチ中に外部アプリケーションで発生する可能性があるエラーを表します。 notice の情報は、ディスカバリー UI でメッセージを生成するために使用されます。

バイナリー・ファイル内の他のプロパティーは以下のとおりです。

バイナリー・ファイル内のその他のプロパティー
機能 タイプ 説明
location object begin および end の値を使用して artifact からテキスト値を取得するためのロケーション情報。 begin 値は、成果物内の開始ロケーションを表すストリング値です。 end 値は、成果物内の排他的な終了位置を表すストリング値です。 フィーチャーが文書レベルの情報を表す場合、このプロパティーはヌルです。 例えば、 type=annotation および properties.type=document_classes の場合です。
properties object 文書内の機能のプロパティです。 サポートされるプロパティは、機能の type によって異なります。 詳しくは、 フィールド・タイプ・プロパティー、 アノテーション・タイプ・プロパティー、および 通知タイプ・プロパティー を参照してください。

フィールド・タイプ・プロパティー

field タイプの場合、以下のプロパティーは、Discovery によって元のファイルから変換された文書の特定のフィールドを表します。

フィールド・タイプ・プロパティー
プロパティー タイプ 説明
field_name string フィールドの名前。
field_index int フィールド値のインデックスです。 この値は、単一値フィールドの場合は 0 ですが、フィールドが複数値 (値の配列など) の場合は > 0 にすることができます。
field_type string (列挙型: long、 double、 date、 json) 機能のデータタイプ。 この値は、プログラミング言語でフィーチャーのテキスト表現を解析する方法を決定します。

アノテーション・タイプ・プロパティー

annotation タイプの場合、以下のプロパティーは、文書をエンリッチできるアノテーションを表します。

Annotation タイプのプロパティー
プロパティー タイプ 説明
type string (列挙型: entities、 element_classes、 document_classes) フィーチャーが表すエンリッチ・アノテーションのタイプ。 entities は、エンリッチ・フィールドのエンティティーにマージされます。 element_classes は、拡張フィールドのエレメント・クラスにマージされます。  document_classes は、文書レベル・エンリッチ・フィールドのクラスにマージされます。
confidence double 外部モデルによるオプションの信頼性スコア。 これは 0 から 1 の間にあり、デフォルトでは 0 です。
entity_type string 外部モデルによってモノに割り当てられるエンティティーのタイプ。 entities タイプの場合は必須です。
entity_text string 外部アプリケーションが抽出するエンティティーの代表的なテキスト。 entities タイプの場合は必須です。
class_name string 外部アプリケーションによってモノに割り当てられるクラスの名前。 element_classes および document_classes タイプの場合は必須です。

通知タイプのプロパティー

notice タイプの場合、以下のプロパティーは、文書のエンリッチ中に外部アプリケーションで発生したエラーおよび例外を表します。

通知タイプのプロパティー
プロパティー タイプ 説明
description string 外部エンリッチ中に発生したエラーを説明するメッセージ。
created long 外部エンリッチ中にエラーが発生した UNIX エポック時間 (ミリ秒)。