導入
Microsoft Power Platform カスタム コネクタは、認証、アクション、トリガー、およびそのパラメーターを記述するために OpenAPI (Swagger とも呼ばれます) 定義を使用します。 OpenAPI 仕様を使用すると、特定のシナリオを処理するコア定義を拡張する拡張機能を定義できます。 Microsoft では、OpenAPI 定義に対していくつかの拡張機能を定義し、カスタム コネクタによりサポートされる特定の機能を構成できるようにしています。
OpenAPI 定義で x-ms-<name> を検索することで、各拡張子を識別できます。 x-ms-summary 拡張機能を使用して定義に値を格納するアクションのパラメーターに集計を入力するときなど、デザイナーを使用してカスタム コネクタを構成するときに、これらの定義の一部を既に使用したことがあるかと思います。 複数の拡張機能を直接編集するには、デザイナーの Swagger エディターを使用するか、コネクタの定義をエクスポートした後、編集およびインポートし直す必要があります。 カスタム コネクタによりサポートされている拡張機能の完全な一覧 をご覧ください。
このモジュールでは、次の拡張機能とその使用方法について説明します。
x-ms-capabilities - コネクタと操作レベルの定義で使用され、提供される機能を指定します。
x-ms-encoding - パス パラメーターのエンコードを指定します。
x-ms-dynamic-values および x-ms-dynamic-list - ユーザーが操作の入力パラメーターを選択するためのオプションの一覧を生成します。
x-ms-dynamic-schema - API の操作から取得されたスキーマの結果に基づいてパラメーターと応答を動的にできます。
これらの拡張機能を構成する主なユース ケースとして、コネクタを使いやすくできます。 たとえば、動的な値がない場合、作成者は、型パラメーターや検索パラメーターのわかりにくい内部スキーマ値または文字列を把握しておく必要があります。 動的な値を構成することで、わかりやすいドロップダウン リストを生成して、作成者がそこから選択できようになります。
一部の拡張機能には API によるサポートも必要な点に留意してください。 たとえば、動的スキーマでは、スキーマを取得する操作をサポートするために API が必要です。 API を制御できない場合、それらの種類の拡張機能を構成できない可能性があります。
拡張機能の構成
デザイナーを使用して定義を操作するように構成されている OpenAPI 拡張機能もありますが、このモジュールで説明する拡張機能はそうではありません。 これらの拡張機能を構成するには、次のいずれかのアプローチを使用する必要があります。
OpenAPI のインポート - OpenAPI ファイルをインポートするときに、Microsoft OpenAPI 拡張機能を含めることができます。
Microsoft Power Platform コネクタ CLI - コマンドライン ツール paconn を使用すると、API 定義ファイルをダウンロードし、お気に入りの JSON エディターを使用して編集できます。 編集が終了したら、paconn を使用して、修正した定義を環境にアップロードし直すことができます。 このアプローチは、たとえば接続パラメーター用の API プロパティ ファイルに対してその他の変更を行う必要がある場合に最適です。
Microsoft Power Platform CLI - コマンドライン ツールを使用することで、ソリューションを利用するカスタム コネクタ用の API 定義ファイルをダウンロードしたり、お気に入りの JSON エディターを使用して編集したりすることができます。 編集が終了したら、CLI を使用して、修正した定義をソリューションにアップロードし直すことができます。 このアプローチは、接続パラメーター用の API プロパティ ファイルに対してその他の変更を行う必要があり、カスタム コネクタがソリューションに含まれる場合に最適です。
組み込み Swagger エディター - カスタム コネクタ デザイナーには OpenAPI エディターが組み込まれており、これを使用することで OpenAPI 拡張機能を最も迅速に追加することができます。
Swagger エディターの使用
カスタム デザイナーの任意のステップから Swagger エディター トグル スイッチをオンにすることで 、Swagger エディターを表示できます。
エディターを使用しているとき、YAML Ain't Markup Language (YAML) の OpenAPI 定義が左側に表示され、検証メッセージ (ある場合) と操作リストが右側に表示されます。
YAML について簡単に説明すると、人間に優しいデータ シリアル化標準であり、YAML コンテンツの変更と保存を簡単に行い、コネクタ ランタイムに使用させることができます。
ほとんどの変更には、良いスタート地点となる例が用意されています。 YAML での変更については、Microsoft Power Platform コネクタ GitHub リポジトリ にある他のコネクタで探してみることをお勧めします。 たとえば、x-ms-capability 拡張機能を実装する場合、リポジトリを検索し、他のコネクタでどのように構成されているかを確認してください。
エディターを使用する場合は、的を絞った小規模な変更を加えることをお勧めします。 エディターでは、入力と同時に構文がチェックされ、誤りがある場合はその場所がリアルタイムで表示されます。
Swagger エディターで YAML を使用するためのヒントを次に示します。
インデントが重要 - インデントは YAML 仕様の一部であるため、構成の詳細を指定するためにインデントをどのように使用するかに注意してください。
左および右中かっこ {} - 左中かっこ { を使用する場合は、右中かっこ } も使用する必要があります。
左および右角かっこ [] - 左角かっこを使用する場合は、右角かっこも使用する必要があります。
検索するには Ctrl + F キー - このキーボード ショートカットを使用すると、YAML 内で検索できます。
元に戻すには Ctrl + Z キー - 誤りに気付いた場合、Ctrl + Z キーボード ショートカットを使用すると、直前の変更を元に戻せます。
このモジュールの残りの部分では、いくつかの Microsoft OpenAPI 拡張機能を使用してカスタム コネクタを使いやすくする方法について説明します。