Webhook トリガー

5 分

Webhook は、より一般的な公開元 - サブスクライバー通知パターンを HTTP ベースで行う、よく使われる実装です。特定のイベントがシステム (公開元) で発生するたびに、通知を外部サービス (サブスクライバー) に配信することができます。

Power Automateと Azure Logic Apps を使用することで、作成者は Webhook をトリガーとして使用できます。このシナリオでは、トリガーがサブスクライバーの役割を果たし、作成者に代わり Webhook を登録および登録解除します。登録は、クラウドフローまたは Logic Apps ワークフロー内の手順が作成または更新された場合に行われます。手順が削除されると、プラットフォームは Webhook を登録解除します。

Copilot がコネクタの設定に役立つように、Copilot はここでも役立ちます。単純なプロンプトから始めて、学習が進むにつれて実装が向上します。

"カスタムコネクタ用の HTTP トリガーを定義する方法は?"
"カスタムコネクタトリガーに含めるべきパラメーターは何ですか?"
"潜在的な改善のためにトリガーのロジックを確認できますか?"

Copilot は、API とフローの要件に基づいてトリガーを定義する最適な方法を提案できます。

次のスクリーンショットは、サブスクライバーと発行元の間のやりとりの例を示しています。

当事者の責任は次の表で説明されています。

公開元 (カスタムコネクタ OpenAPI)	サブスクライバー (Power Automate/Logic Apps)
サブスクリプション登録エンドポイントを提供します。	フロー内でトリガーが作成または更新されると、サブスクリプション登録エンドポイントを呼び出します。
通知契約、つまり、各通知で渡されるオブジェクトはどれかを指定します。 Webhook の作成時に、201 応答に場所 HTTP ヘッダーを含める必要があります。	通知メッセージを受け入れる、自動的に生成されたエンドポイントの URL を指定します。
サブスクライバーの登録とその通知エンドポイントを管理します。	Webhook の登録解除に使用する場所情報を受信して格納します。
登録されている各エンドポイントに POST 要求を発行し、メッセージの本文で関連データを渡します。	通知を受信し、カスタムコネクタによって定義されたスキーマに対して通知を検証を行ったら、自動化をトリガーします。
DELETE メッセージに応じて、エンドポイントの登録解除/削除を行います。	トリガーステップが削除されると、DELETE メッセージを発行して Webhook を登録解除します。

Webhook は通知メカニズムのみを提供し、データの操作はサポートしていません。多くの場合、Webhook の実装には、データまたはオブジェクトの取得と操作をサポートするように設計された 1 つ以上のアクションによって補完されています。

API の要件

カスタムコネクタに必要な Webhook サポートを提供するには、API の実装で次のパラメーターを指定する必要があります。

登録メッセージを受け入れて場所情報を返すエンドポイント
通知メッセージと共に送信されるメッセージの本文の定義
DELETE メッセージを受け入れて Webhook 登録を削除するエンドポイント

通常、API の実装では有効なサブスクライバーの内部リストが保持され、各サブスクライバーは固有の URL で識別されます。この URL をサブスクライバーに返すには、HTTP 201 の応答を返し、場所 HTTP ヘッダーを含める必要があります。この場所の値は、後でサブスクライバーが Webhook 登録を削除するために使用します。

Webhook トリガーの作成

カスタムコネクタは、OpenAPI を使用して、Webhook の必要に応じて、公開元 API の実装を記述します。カスタムコネクタで Webhook トリガーを定義するには、OpenAPI 定義に不可欠な次の 3 つの要素を含める必要があります。

Webhook 登録を説明する POST メッセージ
Webhook 応答のコンテンツ定義
Webhook の変更後の変更プロセスを説明する DELETE メッセージ

登録メッセージ

トリガー定義には、Webhook の登録に使用する POST メソッドを含める必要があります。トリガー定義は、アクションと同様に定義されます。

Microsoft Power Platform によって使用される OpenAPI 仕様のバージョンでは、アクションとトリガーは区別されません。カスタムコネクタ定義では x-ms-trigger カスタム拡張機能を使用してトリガーを宣言します。

paths:
  /webhooks:
    post:
      operationId: OrderCreated
      x-ms-trigger: single

x-ms-trigger 拡張機能の存在が、メソッドがアクションではなくトリガーであることを示します。ウィザードを使用してトリガーを作成すると、この拡張機能が自動的に追加されます。ただし、外部 OpenAPI 定義からカスタムコネクタを作成すると、常にインポートプロセスによってアクションが作成されます。このシナリオでは、ウィザードを使用してトリガーを再作成し、対応するアクション定義を削除する必要があります。

x-ms-trigger 拡張機能の使用可能な値は、オブジェクトと配列の応答を区別するために単一またはバッチです。変更ごとに Webhook で通知が発生すると、1 つのオブジェクトが含まれます。このアプローチは、Webhook で最も一般的です。複数の変更を 1 つの通知に結合すると、オブジェクトの配列が送信されます。通常、このアプローチはポーリングトリガーで使用されます。これについてはモジュールの後半で説明します。

Webhook の応答

カスタムコネクタ定義は、イベントが発生した場合にサービスから受信する Webhook 応答の内容を説明します。この定義は必須ではありませんが、動的コンテンツ一覧で作成者がデザイン時に使用できる動的な値を識別します。

注

この応答は、Webhook を作成および登録する要求の応答ではありません。このデータは、イベントが発生した場合にサービスによって送信されます。

カスタム x-ms-notification-content プロパティは、Webhook 応答スキーマを定義するために OpenAPI で使用される、もう 1 つの拡張機能です。

paths:
  /webhooks:
    x-ms-notification-content:
      description: Order
      schema:
        type: object
        properties:
          id: {type: integer, format: int32, description: id}
          order_key: {type: string, description: order_key}
          status: {type: string, description: status}
          currency: {type: string, description: currency}
          date_created: {type: string, description: date_created}
          total: {type: number, description: total, format: decimal}

ヒント

Webhook 応答の定義では、応答のコンテンツ全体が含まれる必要はありません。動的コンテンツ一覧でデザイン時にフローの作成者に対して公開する部分のみです。

Webhook 応答で送信されるデータには、基になるオブジェクトからユーザーが必要とするすべてのプロパティを含む必要はなく、必ずしも必要ではありません。このような状況では、情報取得用のカスタムコネクタに、その他のアクションを作成します。たとえば、ある Web ストアは新しい注文の識別子を「新しい注文が作成された場合」のみ送信するとします。次に、カスタムコネクタが、注文の識別子を受け入れて注文に関する詳細情報を返す、「注文の詳細を取得」などのアクションを定義します。

逆も同じです。 Webhook 応答は、通常の状況においては必須ではない、または必要とされない過剰な情報を提供する場合があります。 Power Automate または Logic Apps の作成者用インターフェースで表示したデータのみを説明する必要があります。作成者が通知で送信されるより多くのデータにアクセスする必要がある場合、受信メッセージからこれらのプロパティを直接抽出するために JSON 機能を使用できます。

メッセージを削除する

Power Automate または Logic Apps で Webhook を削除するには、Webhook が作成されたときの応答の場所 HTTP ヘッダーを API に含める必要があります。

重要

内部アクションとして Webhook 削除要求のパスを定義する必要があります。このアクションにより、場所ヘッダーで指定された URL に DELETE 要求が送信されます。

このアクションが定義されていない場合、または API に場所ヘッダーが含まれていない場合、Webhook は作成されますが、削除されず、ランタイムに API 実装で問題を発生させる可能性があります。