Webhook を登録する

プラグイン登録ツールを使用して Webhook を登録します。 プラグイン登録ツールを取得するには、Dataverse 開発ツールを参照してください。

プラグイン登録ツールには、WebHook の登録 オプションを選びます。

Webhook を登録するときは、次の 3 つの情報項目を指定する必要があります。

登録済み Webhook では、HTTP の場合はポート 80、HTTPS の場合はポート 443 のみがサポートされます。

認証オプション

正しい WebHook 登録認証オプションと使用する値は、エンドポイントで想定される内容によって異なります。 エンドポイントの所有者が何を使用するか伝える必要があります。 Microsoft Dataverse で Webhooks を使用するには、エンドポイントは以下の認証オプションのいずれかを使用する必要があります。

構成されたエンドポイントへの要求は、要求で渡された認証オプションが一致しない場合に失敗する必要があります。 エンドポイントはこの条件を担当します。

WebHook 登録のクエリ

WebHook 登録は ServiceEndpoint テーブル に格納され、契約 値は 8 です。

ServiceEndpoint テーブルをクエリすることで登録された Webhooks の詳細を参照できます。

Web API:

GET [organization URI]/api/data/v9.0/serviceendpoints?$filter=contract eq 8&$select= serviceendpointid,name,authtype,url

詳細: Web API を使用するクエリ データ

FetchXml:

<fetch>
  <entity name="serviceendpoint" >
    <attribute name="serviceendpointid" />
    <attribute name="name" />
    <attribute name="authtype" />
    <attribute name="url" />
    <filter>
      <condition attribute="contract" operator="eq" value="8" />
    </filter>
  </entity>
</fetch> 

詳細については、FetchXML でデータを取得するを参照してください

設定された認証の値の詳細は AuthValue プロパティにあり、取得できません。

WebHook のステップを登録

WebHook のステップの登録は、プラグインの手順の登録に似ています。 主な相違点は、構成情報を指定できないことです。

プラグインと同様に、メッセージと、必要に応じてテーブルに関する情報を指定します。 また、WebHook を実行するイベント パイプラインの場所、実行モード、操作が成功した場合に AsyncOperation を削除するかどうかを指定します。

ステップ名 と 説明 の情報は、選択したオプションに基づいて自動挿入されますが、それらは変更可能です。 それらをサポートするメッセージのフィルタ属性を設定しない場合、パフォーマンスのベスト プラクティスとして設定するよう求められます。

実行モードと WebHook 登録のデバッグ

WebHook の登録の選択は、不具合が生じた場合のデバッグのエクスペリエンスを左右します。

非同期モード

非同期実行モードを使用すると、システムは、操作の成功または失敗をキャプチャするシステム ジョブ (非同期操作) を作成します。 成功した場合にシステム ジョブを削除するよう選択すると、データベースのスペースを保存できます。

システム は、システム ジョブで発生したエラーを記録します。 Web アプリケーションで 、設定>System>System ジョブ に移動して、任意の Webhook の状態を確認できます。 状態の理由 の値は 失敗 です。 ジョブが失敗した理由の説明を表示するには、失敗したシステム ジョブを開きます。

特定のステップで失敗した非同期ジョブをクエリする

特定のステップの sdkmessageprocessingstepid を知っている場合、任意のエラーの AsynchronousOperations テーブル をクエリできます。 OwningExtensionId 値を使用して、特定の登録されたステップに結果をフィルターできます。 次の例は <stepid> をステップの sdkmessageprocessingstepid として使用します。

Web API:

GET [organization URI]/api/data/v9.0/asyncoperations?$orderby=completedon desc&$filter=statuscode eq 31 and _owningextensionid_value eq @stepid&$select=name,friendlymessage,errorcode,message,completedon?@stepid=<stepid>

詳細: Web API を使用するクエリ データ

FetchXML:

<fetch>
  <entity name="asyncoperation" >
    <attribute name="name" />
        <attribute name="friendlymessage" />
    <attribute name="errorcode" />
    <attribute name="message" />
    <attribute name="completedon" />     
    <filter>
      <condition attribute="owningextensionid" operator="eq" value="<stepid>" />
    </filter>
    <order attribute="completedon" descending="true" />
  </entity>
</fetch>

詳細については、FetchXML でデータを取得するを参照してください

同期モード

同期実行モードを選択すると、失敗はエンドポイントを使用できませんエラー ダイアログによってアプリケーションのユーザーに報告され、webhook のサービス エンドポイントが正しく構成されていないか、利用できないことが通知されます。 ダイアログでは、エラーの詳細を取得するためにログ ファイルをダウンロードすることができます。

Webhook に登録されているクエリ ステップ

登録された Webhook のデータは 、SdkMessageProcessingStep テーブルにあります。

webhook の serviceendpointid がわかっている場合は、特定の Webhook に登録されている手順に対してクエリを実行できます。 登録済みの Webhook の ID を取得するためのクエリについては、Webhook 登録のクエリを参照してください。

Web API:

<id>が webhook の ServiceEndpointId である場合は、次の Web API クエリを使用します。

GET [organization URI]/api/data/v9.0/serviceendpoints(@id)/serviceendpoint_sdkmessageprocessingstep?$select=sdkmessageprocessingstepid,name,description,asyncautodelete,filteringattributes,mode,stage?@id=<id>

登録された手順の詳細については、次の Web API クエリを使用します。ここで、<stepid>はステップの SdkMessageProcessingStepId です。

GET [organization URI]/api/data/v9.0/sdkmessageprocessingsteps(@id)?$select=name,description,filteringattributes,asyncautodelete,mode,stage&$expand=plugintypeid($select=friendlyname),eventhandler_serviceendpoint($select=name),sdkmessagefilterid($select=primaryobjecttypecode),sdkmessageid($select=name)?@id=<stepid>

FetchXML:

この FetchXML を使用して、1 つのクエリで同じ情報を取得します。 <serviceendpointid> は webhook の ID です。

<fetch>
  <entity name="sdkmessageprocessingstep" >
    <attribute name="name" />
    <attribute name="filteringattributes" />
    <attribute name="stage" />
    <attribute name="asyncautodeletename" />
    <attribute name="description" />
    <attribute name="mode" />
    <link-entity name="serviceendpoint" from="serviceendpointid" to="eventhandler" link-type="inner" alias="endpnt" >
      <attribute name="name" />
      <filter>
        <condition attribute="serviceendpointid" operator="eq" value="<serviceendpointid>" />
      </filter>
    </link-entity>
    <link-entity name="sdkmessagefilter" from="sdkmessagefilterid" to="sdkmessagefilterid" link-type="inner" alias="fltr" >
      <attribute name="primaryobjecttypecode" />
    </link-entity>
    <link-entity name="sdkmessage" from="sdkmessageid" to="sdkmessageid" link-type="inner" alias="msg" >
      <attribute name="name" />
    </link-entity>
  </entity>
</fetch>

次の手順

要求ログ サイトでの Webhook 登録のテスト
Webhooks を使用してサーバー イベント用に外部ハンドラーを作成する