データ変換にポリシーを使用する
ポリシー テンプレートは、データを 1 つの構造から別の構造に変換するために使用できます。 通常、このプロセスは、データをアクションに提供したり、アクション結果からの応答データを処理したりするためにカスタム コネクタを使用するユーザーのタスクを簡素化するために行われます。 たとえば、API がレコードへのアクセス権を持つユーザーのコンマ区切りのリストを提供するとします。 そのリストを配列に変換することで、アプリやフローでリストが使いやすくなります。 現在、次のポリシー テンプレートでは、データ構造の変換がサポートされています。
配列をオブジェクトに変換する
オブジェクトを配列に変換する
区切られた文字列をオブジェクトの配列に変換する
各ポリシーは、1 つ以上のアクションの要求 (入力データ) または応答 (出力データ) に対して実行できます。 要求に対してポリシーを実行すると、作成者が提供したデータを成形して、API の表示方法を決めることができます。 たとえば、Microsoft Planner Connector では、そのタスクの詳細を更新するアクションでオブジェクトの配列を使用します。 このアクションにより、ユーザーは外部参照リンクの配列を提供してから、タスクに関連付けることができます。 作成者がそれらを配列と指定できるようになると、新しい項目を追加するを選択することで複数のリンクを追加できる使いやすいインターフェイスでユーザーに表示されます。
アクション ステップでピーク機能を使用すると、データの構造を確認でき、コネクタのポリシー テンプレートによって行われた変換がない場合、API に表示されます。
この操作用の Microsoft Planner API ドキュメント を探す場合、次の例のような構造のデータが必要なことに注目します。
フロー アクションによって提供された情報を API によって予期される動作に変換するために、コネクタは複数のポリシー テンプレートに構成してデータを変換します。 ポリシー テンプレートは次のように使用されます。
プロパティを設定する - previewPriority フィールドを "!" に設定します
プロパティを設定する - @odata.type 式を設定します
配列をオブジェクトに変換 - 配列を成形してプロパティとしてタイプとエイリアスを含めます
配列をオブジェクトに変換ポリシーは次の例に似ています。
応答で実行されるポリシー テンプレートにより、API からの出力を整形できます。 たとえば、その請求の取得アクションからの Contoso 請求の応答には、請求書オブジェクトの一部として、セミコロンで区切られたタグの一覧が含まれます。 API から返されるデータは、次のスクリーンショットに似ています。
複数の値を含む文字列は、アプリケーションおよびフローでは配列よりも操作が難しくなります。 使い勝手を改善するには、応答に区切られた文字列を変換するポリシー テンプレートを使用します。 次の例は、構成するポリシー テンプレートを示しています。
このアクションを実行すると、次の画像のように、応答にタグリストという名前の新しい配列が追加されます。
使用するポリシー テンプレートのいくつかの例を説明したので、重要なコンフィギュレーションの詳細をいくつか確認します。 ポリシーの実行対象パラメーターは、ポリシーが要求または応答に適用されるかどうかを決定します。 両方が必要な場合は、2 つのポリシー テンプレートを構成する必要があります。
各変換ポリシー テンプレートには、ターゲット オブジェクトまたはコレクション パラメーターがあります。 この係数を使用すると、ポリシー ロジックで変換するデータを取得する開始点が得られます。 最も一般的な開始点は、要求または応答の本文をポイントする@body() 式を使用しています。 次の例では、@body() 式はオブジェクトであり、tags という名前のプロパティを用意しています。
代わりに、応答が、それぞれが tags プロパティを持つ請求書オブジェクトの配列である請求書という名前のプロパティのあるオブジェクトである場合、構成は次の画像に似たものになります。
ポリシーを構成する場合は、これらの構成に一致する要求/応答データを含むアクションにのみ適用してください。 たとえば、単一の請求書オブジェクトを返す請求書の取得アクションは、請求書オブジェクトの配列を返す請求書一覧よりもさまざまなポリシー テンプレートを必要とします。 すべてのアクションが有効になっている既存のコネクタにポリシー テンプレートを追加する場合は、すべてのアクションとトリガーをテストして、それらが新しいポリシーで機能することを確認します。
応答ポリシー テンプレートを構成した後、アクション応答でサンプル データを再評価します。 この手順は必須のため、アプリとフローは変換済みのデータを表示できます。
ポリシー テンプレートの構成でエラーが発生した場合、通常は、500 の HTTP ステータスとしてテスターで表示されるか、処理に失敗します。 ポリシーを無効にはできませんが、操作の一覧からアクションを削除することでポリシーが問題を引き起こしている場合にテストを分離できます。 次の画像は、選択された 2 つの操作のみを示しています。
ポリシーの変換テンプレートは、基になる API への/からのデータ変換への構成に重点を置いたアプローチを提供します。 それらは、コネクタ アクションを使いやすくするために使用できます。