WebHook の登録

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

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

WebHook の登録時に、3 つの情報アイテムを提供する必要があります。

Item	Description
件名	WebHook を示す一意の名前。
エンドポイント URL	実行コンテキスト情報のポスト先となる URL。
認証	3 つの認証オプションのうちの 1 つ。 どの認証タイプでも、要求が正当であることを識別するキーを提供する必要があります。

登録された WebHooks は、HTTP の場合はポート 80、HTTPS の場合はポート 443 のみをサポートします。

認証オプション

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

タイプ	Description
HttpHeader	http 要求のヘッダーに 1 つ以上のキー値ペアが含まれます。 例: Key1: Value1 Key2: Value2
WebhookKey	code をキーとして使用してするクエリ文字列、およびエンドポイントに必要な値が含まれています。 プラグイン登録ツールを使用して WebHook を登録するときは、値のみを入力します。 例: ?code=00000000-0000-0000-0000-000000000001
HttpQueryString	クエリ文字列パラメーターとして 1 つ以上のキー値ペアが含まれます。 例: ?Key1=Value1&Key2=Value2

注意

WebhookKey オプションは、認証クエリ文字列に code というキー名が想定されるため、Azure Functionsで使用すると便利です。

構成されたエンドポイントへの要求は、要求で渡された認証オプションが一致しない場合は失敗します。 このエンドポイントはこれに対して責任があります。

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 と FetchExpression の使用

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

WebHook のステップの登録

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

プラグインのようにメッセージを指定し、適切な場合はテーブルのメッセージを指定します。 また、WebHook を実行するイベント パイプラインの場所、実行モード、操作が成功した場合に AsyncOperation を削除するかどうかを指定します。

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

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

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

非同期モード

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

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

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

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

ヒント

特定のステップの sdkmessageprocessingstepid を取得するには、以下のWebHook に登録されたステップをクエリするを参照してください。

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 と FetchExpression の使用

同期モード

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

注意

同期モードは、WebHook によってトリガーされる操作をすぐに実行することが重要である場合、または WebHook のペイロードをサービスが受け取らないとトランザクション全体が失敗するようにする場合に使用します。 簡単な WebHook ステップの登録では、失敗を管理するための限定的なオプションが提供されていますが、詳細な制御が必要な場合はプラグインとワークフロー活動を使用して Webhooks を呼び出すこともできます。 詳細: プラグインまたはワークフロー活動から WebHook を呼び出す。

WebHook に登録されたステップをクエリする

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

WebHook の serviceendpointid を知っている場合に特定の WebHook に登録されているステップをクエリできます。 登録されている WebHook の ID を取得するクエリについては、WebHook 登録のクエリ を参照してください。

Web API:

この Web API クエリを使用でき、<id> は WebHook の ServiceEndpointId です。

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 を使用してサーバー イベント用に外部ハンドラーを作成する

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。