値の動的なリストの拡張機能の使用
カスタム コネクタのアクションのパラメーターを構成する場合、パラメーター値を入力する既定のメーカー エクスペリエンスは単純なテキスト ボックスです。 請求書のタイプ ID という名前の請求書の追加アクションに対するパラメーターがある場合、メーカー エクスペリエンスは次の図のようになります。
メーカーは、請求書のタイプ ID フィールドの正しい値を把握しておく必要があります。この例では、次の値です。
| 値 | ラベル |
|---|---|
| 1 | 発注書 |
| 2 | 非発注書 |
請求書のタイプが発注書であることを示す場合は、メーカーが 1 と入力する必要があります。 これをより簡単な OpenAPI 定義にするには、列挙型のキーワードをサポートする必要があります。 メーカーが選択できる値のリストを使用して、列挙型を定義できます。
カスタム コネクタ デザイナーを使用して列挙型を構成するには、パラメーター構成を編集します。 構成では、ドロップダウン タイプ領域で静的を選択すると、値のコンマ区切りのリストを指定できます。 次のスクリーンショットは、請求書のタイプ ID 構成を示しています。
次の図に示すように、Swagger エディターを使用して列挙型を追加することもできます。
さらに、Power Automate のメーカー エクスペリエンスを見ると、次の図のようになります。
エクスペリエンスが向上する一方、メーカーが 1 または 2 の値の意味を把握しておく必要があります。 パラメーターの説明にこれらの値の意味を記述しておくと、メーカーのプロセスを簡略化するのに役立ちます。 期日のパラメーターがあり、理解しやすく使いやすい 30、60、90 の列挙型を使用する場合など、自己記述型のデータには列挙型を使用するのが最適です。 列挙型の使用に関する他の制限は、API が新しい許容値を追加する場合、カスタム コネクタの列挙型定義を編集してコネクタの更新バージョンを公開する必要があることです。 このエクスペリエンスをさらに向上させるために、Microsoft では OpenAPI 拡張機能 x-ms-dynamic-values を追加しました。
動的な値の構成
パラメーターの x-ms-dynamic-values 拡張機能を構成して、基になる API から値のリストを取得できます。
このアプローチの利点は次のとおりです。
値に加えて、ユーザーに表示されるラベルを構成できます。
返される値は、常に API からの正しい値を表します。
API では、ユーザーごとまたは接続ごとに、セキュリティやその他のニーズに基づいて値のリストをトリミングできます。
他のパラメーター値を API に渡して、返されたリストのフィルター処理を実行できます。
あるフィールドの出力を別の API 呼び出しの入力パラメーターとして使用し、国/地域や州のリストなどの依存オプションを作成できます。
使用している API は、有効な値の配列と、必要に応じてその説明を返す操作を提供する必要があります。 請求書のタイプ ID の前の例をサポートするために、API は次のデータを返す ListInvoiceTypes 操作を提供しました。
請求書のタイプ ID パラメーターのカスタム コネクタ デザイナーでは、動的を選択し、操作 ID、値と値の表示名のプロパティを指定すると、x-ms-dynamic-values 拡張機能を構成できます。 次のスクリーンショットは、請求書のタイプ ID の構成を示しています。
Swagger エディターを使用して x-ms-dynamic-values 拡張機能を構成することもできます。
拡張機能でパラメーターを設定する場合は、Swagger エディターを使用するか、JSON ファイルをダウンロードして編集する必要があります。
これで拡張機能が構成されたので、メーカーはアクションを使用する際によりユーザー フレンドリーなエクスペリエンスを得られます。
x-ms-dynamic-values 拡張機能に加えて、Microsoft は x-ms-dynamic-list と呼ばれる新しい拡張機能も実装しました。 概念的には、どちらも、アクションのパラメーターをユーザーが選択できるドロップダウン リストにするという同じ目的を達成します。 x-ms-dynamic-values 拡張機能をバージョン 1、x-ms-dynamic-list 拡張機能をバージョン 2 と考えます。 古い既存のフローをサポートしている場合は、両方を定義に実装することをお勧めします。 新しく作成したフローのみをサポートしている場合は、x-ms-dynamic-list のみを使用します。 x-ms-dynamic-list 拡張機能を使用すると、アクション パラメーターのスキーマが向上し、いくつかのあいまいな参照を解決できるようにします。 たとえば、要求本文の一部としてパス パラメーター ID とパラメーター ID が要求に含まれている場合、x-ms-dynamic-list 仕様では 2 つのパラメーターを区別できます。一方、x-ms-dynamic-values では、この API をサポートできません。
カスタム コネクタ デザイナーでは x-ms-dynamic-values のみを構成するため、x-ms-dynamic-list 拡張機能を構成するには、OpenAPI 定義を直接変更する必要があります。 次の図は、x-ms-dynamic-list の構成も追加された x-ms-dynamic-values の構成を示しています。
カスタム コネクタのパラメーターに動的な値を構成すると、カスタム コネクタをメーカーにとってより使いやすくすることができます。