Webhook による Microsoft Dataverse イベントの発行

20 分

Microsoft Dataverse から外部サービスにイベントを公開する別の方法は、Webhook を登録することです。 Webhook は、選択した Web API ベースのサービスにイベントを公開するための HTTP ベースのメカニズムです。この方法を使用すると、外部サービス上でホストされたカスタムコードをポイントツーポイント統合として作成できます。

Webhook と Azure Service Bus の比較

統合メカニズムを考慮する場合、いくつかのオプションが使用可能です。特定の方法を選択する際には、さまざまな要素を考慮することが重要です。

次のような場合は、Azure Service Bus を使用することを検討します。

高スケールの非同期処理/キューイングが必須である。
特定の Dataverse のイベントを使用するために複数のサブスクライバーが必要になる場合がある。
統合アーキテクチャを集中管理する必要がある。

次のような場合は、Webhook を使用することを検討します。

プロセスの一環として、外部システムに対する同期処理が必要である (Dataverse は Service Bus エンドポイントに対して非同期処理のみをサポートします)。
実行している外部操作がすぐに発生する必要がある。
Webhook ペイロードが外部サービスによって正常に処理されなかった場合に、トランザクション全体が失敗するようにする。
統合のために使用するサードパーティ Web API エンドポイントが既に存在する。
Shared Access Signature (SAS) 認証が優先されないか、または実現可能ではない (Webhook は認証ヘッダーとクエリ文字列パラメーターキーを介した認証をサポートします)。

Webhook 認証オプション

次の表では、指定したエンドポイントから Webhook メッセージを利用するために使用できる 3 つの認証オプションについて説明します。

種類	説明
HttpHeader	HTTP 要求のヘッダーにキー値のペアを 1 つ以上含めます。例: `Key1: Value1, Key2: Value2`
WebhookKey	コードをキーとして使用したクエリ文字列とエンドポイントで必要とされる値を含めます。 Plug-in Registration Tool を使用して Webhook を登録する場合は、値を入力するだけです。例: `?code=00000000-0000-0000-0000-000000000001`
HttpQueryString	1 つ以上のキー値のペアをクエリ文字列パラメーターとして含めます。例: `?Key1=Value1&Key2=Value2`

Webhook HTTP ヘッダー

次の表に、Webhook 呼び出しの一部としてサービスに渡される HTTP ヘッダーを示します。新しい Webhook プロセッサを作成している場合は、これらのヘッダーを処理方法の一部として使用できます。

キー	値の説明
x-request-id	要求の一意識別子
x-ms-dynamics-organization	要求を送信したテナントの名前
x-ms-dynamics-entity-name	実行コンテキストデータに渡されたエンティティの論理名
x-ms-dynamics-request-name	Webhook ステップが登録されたイベントの名前
x-ms-correlation-request-id	すべてのタイプの拡張を追跡するための一意識別子。このプロパティは、プラットフォームで無限ループ防止に使用されます。ほとんどの場合、このプロパティは無視できます。この値は、製品のテレメトリをクエリして、操作全体の間に発生した事柄を理解するために使用できるため、テクニカルサポートと連携している場合に使用できます。
x-ms-dynamics-msg-size-exceeded	HTTP ペイロードサイズが 256 KB を超えた場合にのみ送信されます

Webhook エンドポイントの登録

Webhook エンドポイントの登録は、Plug-in Registration Tool を使用することにより、サービスエンドポイントの登録と同様に実行されます。

Plug-in Registration Tool で、登録メニューオプションで新規 Webhook の登録を選択することにより、新しい Webhook を登録できます。

次の Webhook 登録ダイアログボックスが表示されます。ここで、エンドポイントの URL および認証オプションを構成できます。

HTTPHeader 認証による登録

HttpHeader 認証が選択されている場合、HTTP 要求の一部として渡されるキーと値を追加するように求めるメッセージが表示されます。通常、キーと値には、OAuth ベアラートークンまたはその他のさまざまな認証形式が含まれる場合があります。

WebhookKey 認証による登録

WebhookKey が認証方式として指定されている場合、クエリ文字列は指定されたキーとともに形式 ?code=[web hook key] で URL に渡されます。この方式は、既定でこのコードパラメーターを使用して認証を実行するため、Azure Functions を呼び出すときに便利です。

HTTPQueryString 認証による登録

Query String パラメーターは、HttpQueryString を認証オプションとして指定することによって渡すことができます。 HTTPHeader オプションと同様に、Web API に一連のキーと値のペアを渡すことができます。また、その他のパラメーターを渡すことも、この方法で Azure Functions を使用して要求される "code" パラメーターを手動で渡すこともできます。