動的スキーマを使用する
カスタム コネクタのアクションを構成するとき、パラメーターも構成できます。 これらのパラメーターは、OpenAPI 定義またはサンプル要求をインポートすることで構成します。 使用するアプローチに関係なく、パラメーターの一覧は固定です。 そのアクションを使用すると、コネクタによって定義されたパラメーターの静的な一覧が作成者に表示されます。 リスト パラメーターは固定であり、変化しないので、多くの場合はこのアプローチが適しています。 場合によっては、入力に対して表示されるパラメーターが変化することがあります。
最も一般的なユース ケースは次のとおりです。
パラメーターの一覧は、カテゴリや請求書のタイプなど、タイプに応じて変化します。
レコードの状態により、変更できるパラメーターが決まることがあります。 たとえば、出荷注文に使用できるパラメーターは、非出荷注文とは異なる場合があります。
パラメーター一覧は、セキュリティ上の理由で縮小されることがあります。
共通のアクションの実装は、いくつかのデータ型にまたがります。 たとえば、API には、取引先企業、取引先担当者、注文、または請求書に適用される作成アクションが実装されることがあります。 入力パラメーターは、作成者が選択したオブジェクト タイプによって定義されます。
カスタム コネクタは、動的スキーマ OpenAPI 拡張機能を構成できるようにすることで、これらのシナリオをサポートします。 動的スキーマ OpenAPI 拡張機能が構成されている場合、カスタム コネクタ ランタイムは操作を呼び出し、特定のアクションに対して表示する必要があるパラメーターを定義するスキーマを取得します。 スキーマ データには、パラメーターの表示名や説明などの他のオプションを含めることができます。
Contoso Invoicing API の例では、OpenAPI 定義がインポートされた後、Power Automate フローで使用されたときのアクションは次の図のようになっていました。
上の図は、発注請求書ではなく発注以外の請求書の追加に関連するパラメーターを示しています。 さらに、請求書作成で有効ではない請求書フィールドもあります。 たとえば、createDate は、API によって設定されるフィールドであり、ユーザー入力の一部とはなりません。 請求書のタイプ ID の動的値と他のパラメーターの動的スキーマを実装すると、アクションは次の図のようになります。
作成者が請求書タイプを発注から発注以外に変更したので、発注書パラメーターは必要に応じて非表示または表示になります。
カスタム コネクタ ランタイムは、動的スキーマの構成に使用できる 2 つの拡張機能をサポートします。 どちらも同じ目的を果たしますが、x-ms-dynamic-schema 拡張機能はバージョン 1 で、x-ms-dynamic-properties はバージョン 2 です。 アクションを使用して古いフローをサポートする必要がある場合、両方のバージョンをカスタム コネクタで構成できます。 新しいフローのみをサポートする場合、x-ms-dynamic-properties 拡張機能のみ構成できます。
API のサポート
動的スキーマを構成するには、基盤となる API が、スキーマを返す操作を定義することでサポートを提供する必要があります。 API にまだ適切なアクションが存在しておらず、API を変更したり変更を要求したりできない場合、動的スキーマを実装できない場合があります。
スキーマを返す操作は、カスタム コネクタ ランタイムから渡される 1 つ以上のパラメーターを受け取ります。 これらのパラメーターは、定数の場合もあれば、アクション カードで収集される他のデータを表す場合もあります。 このデータは、スキーマの一部として返されるパラメーターの一覧をフィルター処理するために API が使用できます。 前の例では、請求書のタイプは動的スキーマを取得する操作にパラメーターとして渡されます。
JSON スキーマに使用される操作からの応答は、有効な SQL スキーマである必要があります。 次の例は、Contoso API GetInvoiceSchema によって返される API を示しています。
コンテンツに関する次の重要な点に注意してください。
型の指定は必須であり、パラメーターのデータ型を識別するために使用されます。
概要と説明は、作成者がパラメーターを識別できるように、Power Automate デザイナーで使用されます。
x-ms-visibility 拡張機能プロパティは、このパラメーターを常に表示する必要がある場所を指定したり (値 "important")、フロー カードで詳細リンクを選択するなど、作成者に表示するためにユーザー アクションが必要かどうかを指定したり (値 "advanced") するために用意されています。 この情報は動的に取得されるため、利用可能なコンテキスト情報によって異なる場合があります。
必須の配列に、必須のパラメーターの一覧が示されます。
動的スキーマ拡張機能の構成
x-ms-dynamic-schema または x-ms-dynamic-properties 拡張機能を構成するには、カスタム コネクタの OpenAPI 定義を直接編集する必要があります。 現在のところ、これらの値を編集するためのカスタム コネクタ デザイナーのサポートはありません。
次の図は、API によって提供された OpenAPI 定義がインポートされた後、AddInvoice パラメーター構成がどのようになったかを示しています。
上の例では、AddInvoice が CreateInvoiceRequest オブジェクトを入力として使用しています。 プロパティは、参照先の #/definitions/Invoice によって定義されており、これはすべての請求書プロパティの共有定義になっています。
動的スキーマ拡張機能への呼び出しを実装するには、プロパティを構成済みの拡張機能と置き換えることができます。
プロパティのハード コーディングされた一覧を使用する代わりに、GetInvoiceSchema 操作を呼び出して typeId パラメーターに基づく一覧が取得されます。
カスタム コネクタに動的スキーマを実装することにより、アクションに使用する必要があるパラメーターを作成者に対して明確にできます。