式を使用したランタイム値へのアクセス

5 分

式を使用すると、ポリシーテンプレートパラメーターはランタイムデータから値を取得できます。関数は、要求のヘッダー、クエリ、本文からのランタイムデータおよび API からの応答にアクセスし、それらを変換します。また、式を使用してコネクタの接続プロパティからデータにアクセスするのも一般的です。たとえば、@connectionParameters('HostUrl') は接続プロパティ HostUrl 用に構成された値を取得します。これによって作成者は、テスト対実稼働環境の API シナリオと同様に、接続の一部としてサービス URL を変更できます。このユニットでは、ポリシーテンプレートで使用するいくつかの一般的な式について確認します。

式の基本

式はランタイムに評価されます。式は、1 つ以上の関数、演算子、または明示的な値のシーケンスです。パラメーターで式を定義する場合、式の前にアット記号 (@) を付けます。文字列の入力が想定される式で数値が算出された場合、かっこ ({}) の表記を使用すると、数値が文字列に自動的に変換されます。

次の例は、両方の表記方法の使用方法を示しています。

@{connectionParameters('HostPortNumber')}

null 値プロパティが原因で式が失敗しないためには、パスに null 値がないことを確認します。次の例は、概要が null 値の場合に失敗します。

@body().summary.amount

式に明示的な値 (文字列リテラル) が含まれている場歳は、単一引用符を使用します。式の周りで使用されるマークアップと競合するため、二重引用符は使用しないでください。

応答本文を使用する

body() 関数を使用してランタイム時の応答本文にアクセスできます。たとえば、請求書一覧アクションは次のデータを返します。

{ “invoices”: [ { “invoiceid”:”1234”}] }

この例では、body() 関数が外側のかっこ ({}) を参照し、配列であるプロパティ invoice があります。

次のロジックを使用して、請求書配列を参照する式を作成します。

@body().invoices

また、次のロジックを使用して配列の最初の項目から 請求書 ID にアクセスする式を作成することができます。

@body().invoices[0].invoiceid

ヘッダー値を使用する

@headers('headerName') 式を使用することで、ヘッダーから値にアクセスできます。また、URL からヘッダーを設定するポリシーテンプレートを使用する際に @headers 式をターゲットテンプレートパラメーターとして使用できます。このアプローチを使用すると、URL から値を取得し、ヘッダーに設定できます。たとえば、コネクタは、この式を使用してサービスからアクセストークンを取得し、ページへの転記を可能にします。次の例は、ページに転記アクションに使用するアクセストークンを取得するポリシーテンプレート構成の外観を示しています。

クエリ値を使用する

ヘッダーの使用と同様に @queryParameters('queryParameterName') 式を使用して要求のクエリパラメーターにアクセスできます。次の例はヘッダーに関する前の例に似ていますが、この例では取得したトークンをクエリパラメーターに配置します。

接続値を使用する

@connectionParameters('connectionParameterName') 式を使用することで、カスタムコネクタ用の接続の設定時に入力された値にアクセスできます。この式を使用すると、認証やホスト URL の値など、カスタムコネクタのユーザーから情報を収集できます。これらのパラメーター値を使用して URL を作成し、その他の接続固有の構成値を入力できます。

apiProperties.json ファイルで構成された接続パラメーターは、新しい接続の作成時にユーザーが入力する [接続] ダイアログボックスの作成に使用されます。

カスタムコネクタで認証を構成すると、自動的に apiProperties が編集され、必須の認証プロパティを追加できます。 paconn を使用してコネクタ定義をダウンロードしたとき、apiProperties.json ファイルを確認すると、API キー認証を構成した場合に次のロジックが追加されるのが分かります。

"api_key": {
        "type": "securestring",
        "uiDefinition": {
          "displayName": "API Key",
          "description": "The API Key for your environment",
          "tooltip": "Provide your API Key",
          "constraints": {
            "tabIndex": 2,
            "clearText": false,
            "required": "true"
          }
        }

その結果、接続の作成時に次の入力フィールドが表示されます。

他の入力を手動で追加して、カスタムコネクタの各ユーザーに固有の他のデータを収集できます。たとえば、追加する共通フィールドは Host URL であるため、コネクタは基になる API の複数のエンドポイントで使用できます。次の例は、API キーに加えて、ホスト URL と請求コードの入力を可能にする apiProperties.json ファイルを表示しています。

"properties": {
    "connectionParameters": {
      "hostUrl": {
        "type": "string",
        "uiDefinition": {
          "constraints": {
            "required": "true"
          },
          "description": "Specify your API URl e.g. https://test.contoso.com",
          "displayName": "API URL",
          "tooltip": "Specify your API URl e.g. https://test.contoso.com"
        }
      },
      "billingCode": {
        "type": "string",
        "uiDefinition": {
          "constraints": {
            "required": "true"
          },
          "description": "billing code",
          "displayName": "Billing Code",
          "tooltip": "Billing Code"
        }
      },
      "api_key": {
        "type": "securestring",
        "uiDefinition": {
          "displayName": "API Key",
          "description": "The API Key for your environment",
          "tooltip": "Provide your API Key",
          "constraints": {
            "tabIndex": 2,
            "clearText": false,
            "required": "true"
          }
        }
      }
    }

このコンフィギュレーションを使用すると、次の [接続] ダイアログボックスが表示されます。

次に、@connectionParameters('hostUrl') および @connectionParameters('billingCode') 式を使用して、ポリシーテンプレート構成で値を使用することができます。

このモジュールの残りの部分では、式の使用例、およびポリシーテンプレートの使用方法についてさらに説明します。

続行

式の基本

応答本文を使用する

ヘッダー値を使用する

クエリ値を使用する

接続値を使用する

フィードバック