Azure Logic Apps から呼び出しできるカスタム API の作成
適用対象: Azure Logic Apps (従量課金)
Azure Logic Apps が提供する数百個の組み込みコネクタをロジック アプリ ワークフローで利用できますが、コネクタとして利用できない API、システム、サービスを呼び出したい場合があります。 ワークフローで使用するアクションとトリガーを提供する独自の API を作成できます。 ワークフローから呼び出すことができる独自の API は、次のような理由で作成する場合もあります。
- 現行システム統合やデータ統合のワークフローを拡張する。
- 仕事または個人的な作業の管理にサービスを利用する顧客を支援する。
- サービスが届く範囲を拡大する。サービスを見つけやすくする。サービスの用途を拡大する。
基本的に、コネクタはプラグ可能インターフェイスの REST、ドキュメント用の Swagger メタデータ形式、さらにデータ交換形式として JSON を利用する Web API です。 コネクタは HTTP エンドポイント経由で通信する REST API であるため、コネクタのビルドには、.NET、Java、Python、Node.js など、任意の言語を利用できます。 Azure App Service で API をホストすることもできます。Azure App Service は、最も効果的で簡単、かつ拡張可能な方法で API ホスティングを提供する PaaS (サービスとしてのプラットフォーム) です。
カスタム API をロジック アプリ ワークフローで動作させるために、API では、ワークフローで特定のタスクを実行する "アクション" を提供できます。 API は、新しいデータまたはあるイベントが指定の条件を満たすときにワークフローの実行を開始する、"トリガー" として機能させることもできます。 このトピックでは、API のアクションやトリガーを構築するときに採用できる、動作に基づく共通パターンについて説明します。
API は Azure App Service でホストできます。Azure App Service は、高い拡張性と容易な API ホスティングを提供するサービスとしてのプラットフォーム (PaaS) です。
ヒント
API は Web アプリとしてデプロイできますが、API アプリとしてデプロイすることを検討してください。クラウドやオンプレミスで API を構築、ホスト、利用するとき、作業が簡単になります。 API のコードを変更する必要はありません。コードを API アプリにデプロイするだけです。 たとえば、次の言語で作成された API アプリをビルドする方法について確認してください。
カスタム API とカスタム コネクタの違い
カスタム API とカスタム コネクタは、プラグ可能インターフェイスの REST、ドキュメント用の Swagger メタデータ形式、さらにデータ交換形式として JSON を利用する Web API です。 また、これらの API とコネクタは HTTP エンドポイント経由で通信する REST API であるため、カスタム API とコネクタの構築には、.NET、Java、Python、Node.js など、任意の言語を利用できます。
カスタム API を使用すると、コネクタではない API を呼び出すことができ、HTTP + Swagger、Azure API Management、または App Services で呼び出せるエンドポイントを提供できます。 カスタム コネクタはカスタム API と同じように動作しますが、次の属性も備えています。
- Azure の Logic Apps コネクタ リソースとして登録されます。
- Logic Apps デザイナーで Microsoft が管理するコネクタに並んでアイコンと共に表示されます。
- ロジック アプリがデプロイされているリージョンで同じ Microsoft Entra テナントと Azure サブスクリプションを持つコネクタの作成者とロジック アプリ リソース ユーザーのみが使用できます。
また、登録されたコネクタの Microsoft 認定を申請することもできます。 このプロセスは、登録されたコネクタが一般的な使用基準を満たしていることを確認し、Power Automate および Microsoft Power Apps のユーザーがそれらのコネクタを利用できるようにします。
詳細については、次のドキュメントを確認してください。
- カスタム コネクタの概要
- Web API からのカスタム コネクタの作成
- Register custom connectors in Azure Logic Apps (Azure Logic Apps でのカスタム コネクタの登録)
便利なツール
API の操作やパラメーターを説明する Swagger ドキュメントも API に含まれるとき、カスタム API はロジック アプリと最も効果的に連動します。 Swashbuckle のようなライブラリの多くは、Swagger ファイルを自動的に生成できます。 表示名やプロパティの種類などに関して Swagger ファイルに注釈を付けるために、TRex を利用することもできます。Swagger ファイルとロジック アプリが効果的に連動します。
アクション パターン
ロジック アプリがタスクを実行するには、カスタム API でアクションを提供する必要があります。 API の各操作はアクションにマッピングされます。 基本アクションは、HTTP 要求を受け取り、HTTP 応答を返すコントローラーです。 そのため、たとえば、あるワークフローでは HTTP 要求を Web アプリまたは API アプリに送信します。 次に、ワークフローで処理できるコンテンツと共に HTTP 応答がアプリから返されます。
標準的アクションの場合、API に HTTP 要求メソッドを記述し、そのメソッドについて Swagger ファイルで説明できます。 その後、HTTP アクションまたは HTTP + Swagger アクションで API を直接呼び出すことができます。 既定では、応答は要求のタイムアウト期限内に返す必要があります。
時間のかかるタスクが API で完了するまでワークフローに待機させるには、API で、このトピックで説明する非同期ポーリング パターンまたは非同期 webhook パターンに従うことができます。 これらのパターンのさまざまな動作を視覚化する際、類推が役立ちます。ケーキ屋さんにケーキを特注する過程を想像してください。 ポーリング パターンの場合、20 分ごとにケーキ屋さんに電話し、ケーキができているか確認する動作を再現します。 webhook パターンの場合、ケーキができたときに電話できるようにケーキ屋さんがあなたの電話番号を尋ねる動作を再現します。
ポーリング アクション パターンで長時間タスクを実行する
要求のタイムアウト期限より長く実行される可能性があるタスクを API に実行させるには、非同期ポーリング パターンを利用できます。 このパターンでは、API は別個のスレッドで動作しますが、Azure Logic Apps エンジンとの有効な接続を維持します。 この方法では、API で作業が完了する前にワークフローがタイムアウトしたり、ワークフローの次の段階に進んだりすることがありません。
一般的なパターン:
- API が要求を受け取り、作業を開始したことをエンジンが認識していることを確認します。
- エンジンがその後、ジョブの状態確認を要求したら、API がタスクを完了するタイミングをエンジンに知らせます。
- ワークフローが続行できるように、関連データをエンジンに返します。
ここで、前のパン屋さんの類推をポーリング パターンに適用します。パン屋さんに電話し、特注ケーキの配送を注文するところを想像してください。 ケーキ作りの過程には時間がかかりますが、ケーキ屋さんがケーキを作っている間、あなたは電話の前で待ちたくありません。 そこでケーキ屋さんが注文を確定したら、あなたは 20 分ごとに電話をかけることにします。ケーキの状態を確認するための電話です。 20 分後、あなたはケーキ屋さんに電話しますが、ケーキはまだできておらず、さらに 20 分後に電話して欲しいと言われます。 この往復プロセスは、あなたが電話し、ケーキ屋さんがあなたにケーキができたので届けると伝えるまで続きます。
それでは、このポーリング パターンをマッピングしましょう。 ケーキ屋さんはカスタム API です。顧客であるあなたは Azure Logic Apps エンジンです。 エンジンが API を呼び出し、要求を伝えると、API は要求を確定し、エンジンがジョブの状態を確認できる時間間隔を応答として返します。 エンジンはジョブの状態確認を続け、API が応答でジョブが完了したと伝えたらデータをロジック アプリに返します。ロジック アプリはワークフローを続行します。
API が従う手順を API の観点から説明すると次のようになります。
API は HTTP 要求を受け取って作業を開始すると、この手順の後半で説明する
locationヘッダーを付けた HTTP202 ACCEPTED応答をすぐに返します。 この応答により、API で要求を受け、要求ペイロード (データ入力) を受け取り、現在処理中であることを Azure Logic Apps エンジンに認識させます。202 ACCEPTED応答には次のヘッダーを含める必要があります。"必須": Azure Logic Apps エンジンで API のジョブの状態を確認できる URL の絶対パスを指定する
locationヘッダー省略可能:待機時間を秒単位で指定する
retry-afterヘッダー。この時間が経過しないとエンジンはlocationURL にジョブの状態を確認できません。既定では、エンジンは 1 秒後に
locationURL をポーリングします。 別の時間間隔を指定するには、retry-afterヘッダーと次のポーリングまでの秒数を追加します。
指定した時間が経過したら、Azure Logic Apps エンジンでは
locationURL に問い合わせ、ジョブの状態を確認します。 API は次のような確認を実行し、次のような応答を返す必要があります。ジョブが完了したら、HTTP
200 OK応答と応答ペイロード (次の手順の入力) を返します。ジョブがまだ処理中の場合、別の HTTP
202 ACCEPTED応答を返します。ただし、ヘッダーは元の応答と同じです。
API がこのパターンに従うとき、ワークフロー定義で何もしなくてもジョブの状態確認が続行します。
エンジンでは HTTP 202 ACCEPTED 応答と有効な location ヘッダーを受け取ると、非同期パターンに従い、API によって 202 以外の応答が返されるまで location ヘッダーを確認します。
ヒント
非同期パターンの例が必要であれば、ここで GitHub の非同期コントローラー応答サンプルをご覧ください。
webhook アクション パターンで長時間タスクを実行する
代替として、長時間タスクや非同期処理に webhook パターンを使用できます。 このパターンでは、API からの "コールバック" があるまでワークフローを一時停止し、待機します。その後に処理を完了し、ワークフローを続行します。 このコールバックは、イベントの発生時にメッセージを URL に送信する HTTP POST です。
ここで、前のパン屋さんの類推を webhook パターンに適用します。パン屋さんに電話し、特注ケーキの配送を注文するところを想像してください。 ケーキ作りの過程には時間がかかりますが、ケーキ屋さんがケーキを作っている間、あなたは電話の前で待ちたくありません。 そこでケーキ屋さんがあなたの注文を確定するとき、あなたはケーキ屋さんに電話番号を伝えます。ケーキができたときに電話できるようにです。 ケーキ屋さんは注文の品ができたとあなたに伝え、品物を届けます。
この Webhook パターンを再度マップするとき、ケーキ屋さんはカスタム API です。顧客であるあなたは Azure Logic Apps エンジンです。 エンジンは API を呼び出し、要求と "コールバック" URL を与えます。 ジョブが完了すると、API は URL を利用し、エンジンにジョブ完了を通知し、ロジック アプリにデータを返します。ロジック アプリはワークフローを続行します。
このパターンでは、コントローラーに subscribe と unsubscribe という 2 つのエンドポイントを設定します。
subscribeエンドポイント: ワークフローで API のアクションまで実行が到達すると、Azure Logic Apps エンジンではsubscribeエンドポイントを呼び出します。 この手順では、API に保存されるコールバック URL をワークフローで作成し、作業の完了時に API からコールバックが届くまで待機します。 API は URL に HTTP POST でコールバックし、ロジック アプリの入力として返すコンテンツやヘッダーがあれば、それを渡します。unsubscribeエンドポイント: ワークフローの実行が取り消された場合、Azure Logic Apps エンジンではunsubscribeエンドポイントを呼び出します。 API はコールバック URL を登録解除し、プロセスがあれば必要に応じて停止できます。
現在のところ、ワークフロー デザイナーでは、Swagger で Webhook エンドポイントを検出できません。 そこでこのパターンの場合、webhook アクションを追加し、要求の URL、ヘッダー、本文を指定する必要があります。 「ワークフローのアクションとトリガー」も参照してください。 webhook パターンのサンプルについては、ここで GitHub の webhook トリガー サンプルを参照してください。
その他のヒントと注意事項のいくつかを次に示します。
コールバック URL を渡すために、必要に応じて、前のいずれかのフィールドで
@listCallbackUrl()ワークフロー機能を利用できます。ロジック アプリ リソースとサブスクライブしているサービスの両方を所有している場合、コールバック URL の呼び出し後に
unsubscribeエンドポイントを呼び出す必要はありません。 それ以外の場合、Azure Logic Apps ランタイムではunsubscribeエンドポイントを呼び出して、予定されている呼び出しがすべて終了したことを伝え、サーバー側でリソースをクリーンアップできるようにする必要があります。
トリガー パターン
カスタム API は、新しいデータまたはあるイベントが指定の条件を満たすときにワークフローの実行を開始する、"トリガー" として機能させることもできます。 このトリガーはサービス エンドポイントの新しいデータまたはイベントを定期的に確認するか、待ち受けることができます。 新しいデータ、またはあるイベントが指定の条件を満たした場合、トリガーが発動し、トリガーを待ち受けていたロジック アプリが起動します。 この方法でロジック アプリを開始するには、API でポーリング トリガー パターンまたは webhook トリガー パターンを利用します。 これらのパターンは、ポーリング アクションと webhook アクションのそれに似ています。 トリガーの使用状況測定については、こちらをご覧ください。
ポーリング トリガー パターンで新しいデータまたはイベントを定期的に確認する
ポーリング トリガーは、このトピックの前半で説明したポーリング アクションに似た動作をします。 Azure Logic Apps エンジンではトリガー エンドポイントを定期的に呼び出して、新しいデータまたはイベントがないか確認します。 指定の条件に一致する新しいデータまたはあるイベントをエンジンが見つけると、トリガーが発動します。 その後、データを入力として処理するワークフロー インスタンスがエンジンによって作成されます。
Note
ワークフロー インスタンスが作成されなくても、各ポーリング要求はアクション実行として数えられます。 同じデータが複数回処理されることを防止するには、すでに読まれ、ロジック アプリに渡されたデータをトリガーは消去する必要があります。
ポーリング トリガーの手順を API の観点から説明すると次のようになります。
| 新しいデータまたはイベントが見つかったか? | API 応答 |
|---|---|
| Found | 応答ペイロード (次の手順の入力) と共に HTTP 200 OK 状態を返します。 この応答でワークフロー インスタンスが作成され、ワークフローが開始されます。 |
| 見つかりません | location ヘッダーと retry-after ヘッダーと共に HTTP 202 ACCEPTED 状態を返します。 トリガーの場合、 location ヘッダーには triggerState クエリ パラメーターも含まれている必要があります。通常は "timestamp" です。API では、この識別子を使用して、ワークフローが最後にトリガーされた時刻を追跡できます。 |
たとえば、新しいファイルがないか、サービスに定期的に確認するには、次の動作を含むポーリング トリガーを構築できます。
要求に triggerState が含まれていますか? |
API 応答 |
|---|---|
| いいえ | HTTP 202 ACCEPTED 状態と location ヘッダーを返します。ヘッダーの triggerState を現在の時刻に設定し、retry-after 間隔を 15 秒に設定します。 |
| はい | triggerState の DateTime 後に追加されたファイルがないか、サービスに確認します。 |
| 見つかったファイルの数 | API 応答 |
|---|---|
| 1 つのファイル | HTTP 200 OK 状態とコンテンツ ペイロードを返し、返すファイルの triggerState を DateTime に更新し、retry-after 間隔を 15 秒に設定します。 |
| 複数のファイル | 一度に 1 つのファイルと HTTP 200 OK 状態を返し、triggerState を更新し、retry-after 間隔を 0 秒に設定します。 これらの手順で、さらに多くのデータが利用できること、エンジンは location ヘッダーの URL からデータをすぐに要求しなければならないことがエンジンに知らされます。 |
| ファイルなし | HTTP 202 ACCEPTED 状態を返します。triggerState は変更しません。retry-after 間隔を 15 秒に設定します。 |
ヒント
ポーリング トリガー パターンのサンプルについては、ここで GitHub のポーリング トリガー コントローラー サンプルを参照してください。
webhook トリガー パターンで新しいデータまたはイベントを待ち受ける
webhook トリガーは、サービス エンドポイントで新しいデータまたはイベントを待ち受けるプッシュ トリガーです。 新しいデータまたはあるイベントが指定の条件を満たす場合、トリガーが発動し、後からデータを入力として処理するワークフロー インスタンスが作成されます。
webhook トリガーはこのトピックの前半で説明した webhook アクションに似た動作をします。subscribe エンドポイントと unsubscribe エンドポイントで設定されます。
subscribeエンドポイント: ロジック アプリに Webhook トリガーを追加し、保存するとき、Azure Logic Apps エンジンによってsubscribeエンドポイントが呼び出されます。 この手順により、API によって保存されるコールバック URL をワークフローで作成します。 新しいデータまたはあるイベントが指定の条件を満たす場合、API は URL に HTTP POST でコールバックします。 コンテンツ ペイロードとヘッダーは入力としてロジック アプリに渡されます。unsubscribeエンドポイント: その Webhook トリガーかロジック アプリ リソース全体が削除されると、Azure Logic Apps エンジンではunsubscribeエンドポイントを呼び出します。 API はコールバック URL を登録解除し、プロセスがあれば必要に応じて停止できます。
現在のところ、ワークフロー デザイナーでは、Swagger で Webhook エンドポイントを検出できません。 そこでこのパターンの場合、webhook トリガーを追加し、要求の URL、ヘッダー、本文を指定する必要があります。 「HTTPWebhook トリガー」もご覧ください。 webhook パターンのサンプルについては、ここで GitHub の webhook トリガー コントローラー サンプルを参照してください。
その他のヒントと注意事項のいくつかを次に示します。
コールバック URL を渡すために、必要に応じて、前のいずれかのフィールドで
@listCallbackUrl()ワークフロー機能を利用できます。同じデータが複数回処理されることを防止するには、すでに読まれ、ロジック アプリに渡されたデータをトリガーは消去する必要があります。
ロジック アプリ リソースとサブスクライブしているサービスの両方を所有している場合、コールバック URL の呼び出し後に
unsubscribeエンドポイントを呼び出す必要はありません。 それ以外の場合、Logic Apps ランタイムではunsubscribeエンドポイントを呼び出して、予定されている呼び出しがすべて終了したことを伝え、サーバー側でリソースをクリーンアップできるようにする必要があります。
ロジック アプリからの API の呼び出しのセキュリティを強化する
カスタム API を作成した後、ロジック アプリから安全に呼び出すことができるように API の認証を設定します。 ロジック アプリからのカスタム API の呼び出しのセキュリティを強化する方法について説明します。
API をデプロイして呼び出す
認証を設定した後は、API のデプロイを設定します。 ロジック アプリからカスタム API をデプロイして呼び出す方法について確認してください。
カスタム API を Azure に公開する
他の Azure Logic Apps ユーザーがカスタム API を使用できるようにするには、セキュリティを追加したうえで Azure Logic Apps コネクタとして登録する必要があります。 詳細については、「Custom connectors overview (カスタム コネクタの概要)」を参照してください。
Logic Apps、Power Automate、Microsoft Power Apps のすべてのユーザーがカスタム API を使用できるようにするには、セキュリティを追加したうえで API を Azure Logic Apps コネクタとして登録し、Microsoft Azure 認定プログラムにコネクタを申請する必要があります。
サポートを受ける
カスタム API に関するサポートが必要な場合、customapishelp@microsoft.com にお問い合わせください。
ご質問がある場合は、Azure Logic Apps に関する Microsoft Q&A 質問ページを参照してください。