OpenAPI 拡張機能の使用

  • 4 分

このユニットでは、カスタム コネクタで Microsoft OpenAPI 拡張機能 x-ms-capabilities と x-ms-url-encoding を使用する方法を説明します。

x-ms-capabilities 拡張機能を使用すると、コネクタ レベルと操作レベルでコネクタが提供する機能を構成できます。 現在、Microsoft Power Platform カスタム コネクタは次のオプションに対して構成できます。

  • chunkTransfer - 操作レベル

  • testConnection - コネクタ レベル

chunk transfer を有効にする

メッセージを処理する際、コネクタ ランタイムは、メッセージのコンテンツを最大サイズに制限します。 この制限により、サイズの大きいメッセージを格納および処理することで生まれる間接費を削減できます。 この制限を超えるメッセージを処理するには、コネクタがサイズの大きいメッセージを小さいメッセージ チャンクに分割することができます。 こうすることにより、大規模なコンテンツを転送できます。 コネクタを介して他のサービスと通信する場合、ランタイムはサイズの大きいメッセージを消費できますが、あくまでチャンク単位です。 この条件は、コネクタがチャンク分割、そしてコネクタとこれらのサービス間の基礎 HTTP メッセージ交換もサポートしている必要があるということです。

カスタム コネクタがチャンク転送を使用するには、次のパラメーターが必要です。

  • API がチャンクをサポートしている必要があります。 詳しくは、コネクタでのチャンクされたメッセージの処理 を参照してください。

  • カスタム コネクタは、アクションに対してチャンク転送機能を有効にする必要があります。

  • コネクタ アクションを使用しているユーザーは、フロー ステップのチャンク転送を有効にする必要があります。

カスタム コネクタ定義で、チャンク転送を有効にする操作定義に次のロジックを追加します。

{chunkTransfer: true}

構成されたチャンク転送を示すスクリーンショット。

YAML エディターの代わりにダウンロードした apiDefinition.swagger.json ファイルを使用している場合、次のスクリーン ショットに示されている変更を行う必要があります。

チャンク転送が構成された状態の JSON OpenAPI 定義を示すスクリーンショット。

この変更を行うと、変更がカスタム コネクタ デザイナーに表示されなくなります。 ただし、アクションがフローで使用される場合、ステップの設定に次のチャンクの許可オプションが表示されます。

Power Automate でチャンクを有効化した状態を示すスクリーンショット

API がサポートしている場合、チャンクを有効にすると、サイズの大きいメッセージが機能するようになり、チャンクにより転送されるようになります。

テスト接続を構成する

既定では、カスタム コネクタを使用して接続を作成した場合、接続の変更が有効かどうかが検証されません。 たとえば、無効なホスト URL や無効な API キーを指定した場合、接続は作成できますが、接続を使用しているうちに障害が発生します。 testConnection OpenAPI 拡張機能を使用することにより、接続の作成中に実行されるカスタム コネクタの操作を指定し、指定されたコンフィギュレーションを検証できます。

接続テストを実装するには、HTTP 200 (成功) を返すカスタム コネクタで簡単な操作が定義されている必要があります。 こうした操作には、構成済みの既存の操作を使用することもできます。また、接続テスト専用に操作を作成してもかまいません。 特定のテスト操作を構成する場合、ユーザーが使用しないように internal とマークすることが推奨されます。 また、静的パラメーターを操作に渡すこともできます。 たとえば、アクションで返されるレコード件数を制限するために $top パラメーターを取得した場合、そのパラメーターを使用して結果を 1 件のレコードに制限できます。

次の例では、定義済みの ListInvoices 操作、および接続のテストにどのように使用されるかを示し、testConnection 拡張機能の構成を示しています。

YAML x-ms-capabilities で構成されたテスト接続を示すスクリーン ショット。

apiDefinition.swagger.json の編集は、次の画像のようになります。

JSON で構成されたテスト接続を示すスクリーン ショット。

パスのエンコードを構成する

x-ms-url-encoding拡張機能は、要求 URL パスに含まれるパラメーターに適用されます。

たとえば、次の要求で顧客を国/地域別に返すアクションを定義できます。

https://myapi.myservice.com/customers/{country}

このアクションでは、国はコネクタのユーザーが提供するパラメーターになります。 これらのパラメーターはパスの一部であるため、URL にエンコードする必要があります。 既定では、パス パラメータは URL にエンコードされた単一のパラメーターです。 ただし、一部のシナリオでは、基礎となる API では、アット記号 (@)、スラッシュ (/)、バック スラッシュ (\) などの特定の文字によってもたらされる複雑な問題を解決するために、パラメーターが二重 URL エンコードされることを期待している場合があります。

パス パラメーターで二重エンコードを設定するには、次のオプションをパラメーターに追加します。

x-ms-url-encoding: double

入力パス パラメーターを返す方法を 2 通り使用する API を検討してください。ただし、片方では次の図にあるように二重エンコードが使用されます。

二重エンコードで構成された x-ms-url-encoding を示すスクリーンショット。

入力が複雑な両方のアクションを呼び出す Microsoft Power Automate フローを実行すると、二重エンコードが同じテキスト値を API に渡します。違いは、二重にエンコードされている点のみです。

Power Automate の一重エンコードおよび二重エンコードを示すスクリーンショット。

この拡張機能を使用すると、コネクタ ユーザーがアクションを呼び出す際にパス パラメーターを制御する必要がなくなるため、API で二重 URL エンコードが必要なパラメーターの処理が簡略化されます。