OpenAPI 拡張機能の使用
このユニットでは、カスタム コネクタで 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 ファイルを使用している場合、次のスクリーン ショットに示されている変更を行う必要があります。
この変更を行うと、変更がカスタム コネクタ デザイナーに表示されなくなります。 ただし、アクションがフローで使用される場合、ステップの設定に次のチャンクの許可オプションが表示されます。
API がサポートしている場合、チャンクを有効にすると、サイズの大きいメッセージが機能するようになり、チャンクにより転送されるようになります。
テスト接続を構成する
既定では、カスタム コネクタを使用して接続を作成した場合、接続の変更が有効かどうかが検証されません。 たとえば、無効なホスト URL や無効な API キーを指定した場合、接続は作成できますが、接続を使用しているうちに障害が発生します。 testConnection OpenAPI 拡張機能を使用することにより、接続の作成中に実行されるカスタム コネクタの操作を指定し、指定されたコンフィギュレーションを検証できます。
接続テストを実装するには、HTTP 200 (成功) を返すカスタム コネクタで簡単な操作が定義されている必要があります。 こうした操作には、構成済みの既存の操作を使用することもできます。また、接続テスト専用に操作を作成してもかまいません。 特定のテスト操作を構成する場合、ユーザーが使用しないように internal とマークすることが推奨されます。 また、静的パラメーターを操作に渡すこともできます。 たとえば、アクションで返されるレコード件数を制限するために $top パラメーターを取得した場合、そのパラメーターを使用して結果を 1 件のレコードに制限できます。
次の例では、定義済みの ListInvoices 操作、および接続のテストにどのように使用されるかを示し、testConnection 拡張機能の構成を示しています。
apiDefinition.swagger.json の編集は、次の画像のようになります。
パスのエンコードを構成する
x-ms-url-encoding拡張機能は、要求 URL パスに含まれるパラメーターに適用されます。
たとえば、次の要求で顧客を国/地域別に返すアクションを定義できます。
https://myapi.myservice.com/customers/{country}
このアクションでは、国はコネクタのユーザーが提供するパラメーターになります。 これらのパラメーターはパスの一部であるため、URL にエンコードする必要があります。 既定では、パス パラメータは URL にエンコードされた単一のパラメーターです。 ただし、一部のシナリオでは、基礎となる API では、アット記号 (@)、スラッシュ (/)、バック スラッシュ (\) などの特定の文字によってもたらされる複雑な問題を解決するために、パラメーターが二重 URL エンコードされることを期待している場合があります。
パス パラメーターで二重エンコードを設定するには、次のオプションをパラメーターに追加します。
x-ms-url-encoding: double
入力パス パラメーターを返す方法を 2 通り使用する API を検討してください。ただし、片方では次の図にあるように二重エンコードが使用されます。
入力が複雑な両方のアクションを呼び出す Microsoft Power Automate フローを実行すると、二重エンコードが同じテキスト値を API に渡します。違いは、二重にエンコードされている点のみです。
この拡張機能を使用すると、コネクタ ユーザーがアクションを呼び出す際にパス パラメーターを制御する必要がなくなるため、API で二重 URL エンコードが必要なパラメーターの処理が簡略化されます。