AssignMessage ポリシー

概要

Assign Message ポリシーは、API プロキシフローの実行時に新しいリクエストとレスポンスのメッセージを変更または作成します。このポリシーを使用すると、こうしたメッセージに以下の操作を実行できます。

  • 新しいフォーム パラメータ、ヘッダー、クエリ パラメータをメッセージに追加する
  • 既存のプロパティをメッセージ間でコピーする
  • ヘッダー、クエリ パラメータ、フォーム パラメータ、あるいはメッセージのペイロードをメッセージから削除する
  • メッセージに既存のプロパティの値を設定する

Assign Message は、一般的にはリクエストやレスポンスのプロパティの追加、変更、削除に使用します。しかし、カスタム リクエスト メッセージを作成するに記載されているように、カスタムのリクエストやレスポンス メッセージを作成して、別のターゲットに渡すこともできます。

Assign Message ポリシーでは、次の子要素を使用してフロー変数の作成や変更ができます。

<AssignMessage> 要素

Assign Message ポリシーを定義します。

デフォルト値 下記の [デフォルト ポリシー] タブをご覧ください。
要否 必須
複合オブジェクト
親要素 なし
子要素 <Add>
<AssignTo>
<AssignVariable>
<Copy>
<DisplayName>
<IgnoreUnresolvedVariables>
<Remove>
<Set>

<AssignMessage> 要素の構文は次のとおりです。

構文

<AssignMessage> 要素の構文は次のとおりです。

<AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <!-- All AssignMessage child elements are optional -->
      <Add>
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Add>

      <AssignTo createNew="[true|false]" transport="http"
        type="[request|response]">destination_variable_name</AssignTo>

      <AssignVariable>
        <Name>variable_name</Name>
        <Ref>source_variable</Ref>
        <Template>message_template</Template>
        <Value>variable_value</Value>
      </AssignVariable>

      <Copy source="[request|response]">
        <!-- Can also be an empty array (<FormParams/>) -->
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <!-- Can also be an empty array (<Headers/>) -->
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <Path>[false|true]</Path>
        <Payload>[false|true]</Payload>
        <!-- Can also be an empty array (<QueryParams/>) -->
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
        <ReasonPhrase>[false|true]</ReasonPhrase>
        <StatusCode>[false|true]</StatusCode>
        <Verb>[false|true]</Verb>
        <Version>[false|true]</Version>
      </Copy>

      <DisplayName>policy_display_name</DisplayName>

      <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

      <Remove>
        <!-- Can also be an empty array (<FormParams/>) -->
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <!-- Can also be an empty array (<Headers/>) -->
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <Payload>[false|true]</Payload>
        <!-- Can also be an empty array (<QueryParams/>) -->
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Remove>

      <Set>
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <Path>path</Path>
        <Payload contentType="content_type" variablePrefix="prefix"
            variableSuffix="suffix">new_payload</Payload>
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
        <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
        <StatusCode>HTTP_status_code or {variable}</StatusCode>
        <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
        <Version>[1.0|1.1|{variable}]</Verb>
      </Set>

    </AssignMessage>
    

デフォルト ポリシー

次の例は、Edge UI でフローに Assign Message ポリシーを追加したときのデフォルト設定を示しています。

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
      <DisplayName>Assign Message-1</DisplayName>
      <Properties/>
      <Copy source="request">
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <Verb/>
        <StatusCode/>
        <ReasonPhrase/>
        <Path/>
      </Copy>
      <Remove>
        <Headers>
          <Header name="h1"/>
        </Headers>
        <QueryParams>
          <QueryParam name="q1"/>
        </QueryParams>
        <FormParams>
          <FormParam name="f1"/>
        </FormParams>
        <Payload/>
      </Remove>
      <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
      </Add>
      <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <!-- <Verb>GET</Verb> -->
        <Path/>
      </Set>
      <AssignVariable>
        <Name>name</Name>
        <Value/>
        <Ref/>
      </AssignVariable>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

Edge UI に新しい Assign Message ポリシーを挿入すると、テンプレートには使用可能なすべての操作のスタブが組み込まれます。通常は、このポリシーで実行する操作を選択して、残りの子要素を削除します。たとえばコピー操作を実行する場合は、<Copy> 要素を使用し、ポリシーから <Add><Remove> などの子要素を削除して、読みやすくします。

この要素には、すべてのポリシーに共通の次の属性があります。

属性 デフォルト 要否 説明
name なし 必須

ポリシーの内部名です。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて <DisplayName> 要素を使用して、管理 UI プロキシ エディタのポリシーに別の自然言語名でラベルを付けます。

continueOnError false 省略可 ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。ポリシーが失敗してもフロー実行を続行するには、true に設定します。
enabled true 省略可 ポリシーを適用するには「true」に設定します。ポリシーを「turn off」するには、「false」に設定します。false に設定すると、ポリシーがフローに接続されている場合でも適用されません。
async  not_interested false 非推奨 この属性は非推奨となりました。

次の表に、<AssignMessage> の子要素の概要を示します。

子要素 要否 説明
一般的な操作
<Add> 省略可 <AssignTo> 要素で指定されたメッセージ オブジェクトに情報を追加します。

<Add> はメッセージに元のメッセージには存在しないヘッダーやパラメータを追加します。既存のヘッダーやパラメータを上書きするには、<Set> 要素を使用します。

<Copy> 省略可 source 属性で指定されたメッセージの情報を<AssignTo> 要素で指定されたメッセージ オブジェクトにコピーします。
<Remove> 省略可 <AssignTo> 要素で指定されたメッセージ変数から指定された要素を削除します。
<Set> 省略可 <AssignTo> 要素で指定された、リクエストやレスポンスの既存のプロパティ値を置き換えます。

<Set> は、元のメッセージに既存のヘッダーやパラメータを上書きします。新しいヘッダーやパラメータを追加するには、<Add> 要素を使用します。

その他の子要素
<AssignTo> 省略可 Assign Message ポリシーの操作対象となるメッセージを指定します。これは、標準のリクエストやレスポンスでも、新しいカスタム メッセージでもかまいません。
<AssignVariable> 省略可 フロー変数に値を割り当てます。変数が存在しない場合は、<AssignVariable> によって作成されます。
<IgnoreUnresolvedVariables> 省略可 未解決の変数に突き当たった場合に、処理を停止するかどうかを決定します。

後続のセクションでは、これらの子要素についてそれぞれ説明します。

次の例では、Assign Message ポリシーの使用方法をいくつか紹介しています。

1: ヘッダーを追加する

次の例は、<Add> 要素を使用してリクエストにヘッダーを追加します。

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
      <Add>
        <Headers>
          <Header name="user-agent">{request.user.agent}</Header>
        </Headers>
      </Add>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

2: ペイロードを削除する

次の例は、<Remove> 要素を使用してレスポンスからペイロードを削除します。

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
      <DisplayName>remove-1</DisplayName>
      <Remove>
        <Payload>true</Payload>
      </Remove>
      <AssignTo createNew="false" transport="http" type="response"/>
    </AssignMessage>
    

3: レスポンスを変更する

次の例は、ヘッダーを追加することで既存のレスポンス オブジェクトを変更します。

<AssignMessage name="modify-response">
      <Set>
        <Headers>
          <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
        </Headers>
      </Set>
      <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
      <AssignTo createNew="false" type="response"></AssignTo>
    </AssignMessage>
    

この例では、新しいメッセージは作成されません。その代わりに、HTTP ヘッダーを追加することで既存のレスポンス メッセージを変更しています。

この例では <AssignTo> 要素内の変数名が省略され、type に「response」が指定されているため、ターゲット サーバーから返されるレスポンス オブジェクトがこのポリシーによって変更されます。

このポリシーによってレスポンス メッセージに追加される HTTP ヘッダーは、LookupCache ポリシーによって取り込まれた変数から導出されます。このため、この Assign Message ポリシーによって変更されるレスポンス メッセージには、結果がキャッシュから取得されたかどうかを示す HTTP ヘッダーが組み込まれます。レスポンスでのヘッダーの設定は、デバッグやトラブルシューティングに便利です。

4: 動的コンテンツを設定する

Assign Message を使用してレスポンスやリクエストのメッセージのペイロードに動的なコンテンツを埋め込むことができます。

XML ペイロードに Edge フロー変数を埋め込むには、指定された変数を {prefix.name} のように中かっこで囲みます。

次の例では、user-agent HTTP ヘッダーフロー変数の値を User-agent という XML 要素に埋め込んでいます。

<AssignMessage name="set-dynamic-content">
      <AssignTo createNew="false" type="response"></AssignTo>
      <Set>
        <Payload contentType="text/xml">
          <User-agent>{request.header.user-agent}</User-agent>
        </Payload>
      </Set>
      <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </AssignMessage>
    

JSON ペイロードの場合、次の例のように variablePrefix 属性と variableSuffix 属性を区切り文字とともに使用することで変数を挿入できます。

<AssignMessage name="set-payload">
      <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {
         "user-agent": "@request.header.user-agent#"
      }
      </Payload>
    </AssignMessage>
    

フロー変数の完全なリストについては、フロー変数リファレンスをご覧ください。

Cloud リリース 16.08.17 以降は、中かっこも変数の挿入に使用できます。

5: クエリ パラメータを削除する

次の例は、リクエストから apikey クエリ パラメータを削除します。

<AssignMessage name="remove-query-param">
      <Remove>
        <QueryParams>
          <QueryParam name="apikey"/>
        </QueryParams>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

ユーザーの認証に VerifyAPIKey ポリシーを使用する場合は、リクエスト メッセージから apikey クエリ パラメータを削除することをおすすめします。このようにすることで、機密のキー情報がバックエンドのターゲットに渡されないようにします。

6: 変数を設定または取得する

次の例では、3 つの Assign Message ポリシーを使用しています。

  1. リクエストに 3 つのフロー変数を作成し、静的な値を割り当てます。
  2. リクエスト フローの 2 番目のポリシーでフロー変数を動的に取得します。
  3. レスポンスのペイロードでこれらの変数を設定します。
    <!-- Policy #1: Set variables in the request -->
    <AssignMessage continueOnError="false" enabled="true" name="set-variables">
        <!-- Create a variable named myAppSecret -->
        <AssignVariable>
            <Name>myAppSecret</Name>
            <Value>42</Value>
        </AssignVariable>
        <!-- Create a variable named config.environment -->
        <AssignVariable>
            <Name>config.environment</Name>
            <Value>test</Value>
        </AssignVariable>
        <!-- Create a variable named config.protocol -->
        <AssignVariable>
            <Name>config.protocol</Name>
            <Value>gopher</Value>
        </AssignVariable>
        <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
        <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

最初のポリシーは、<AssignVariable> 要素でリクエスト内に 3 つの変数を作成して設定します。各 <Name> 要素は変数名を指定し、<Value> は値を指定します。

2 番目のポリシーは、<AssignVariable> 要素を使用して値を読み込み、3 つの新しい変数を作成します。

    <!-- Policy #2: Get variables from the request -->
    <AssignMessage continueOnError="false" enabled="true" name="get-variables">
      <AssignTo createNew="false" transport="http" type="request"/>
      <!-- Get the value of myAppSecret and create a new variable, secret -->
      <AssignVariable>
        <Name>secret</Name>
        <Ref>myAppSecret</Ref>
        <Value>0</Value>
      </AssignVariable>
      <!-- Get the value of config.environment and create a new variable, environment -->
      <AssignVariable>
        <Name>environment</Name>
        <Ref>config.environment</Ref>
        <Value>default</Value>
      </AssignVariable>
      <!-- Get the value of config.protocol and create a new variable, protocol -->
      <AssignVariable>
        <Name>protocol</Name>
        <Ref>config.protocol</Ref>
        <Value>default</Value>
      </AssignVariable>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    </AssignMessage>
    

2 番目のポリシーの <Ref> 要素は参照元の変数を参照し、<Name> 要素は新しい変数の名前を指定します。<Ref> 要素によって参照される変数にアクセスできない場合は、<Value> 要素で指定された値を指定できます。

このポリシーセットを試す方法

  1. ポリシー #1 と #2 をリクエスト フローに追加します。必ずポリシー #1 をポリシー #2 の前に配置します。
  2. 3 番目のポリシーをレスポンス フローに追加します。
  3. 3 番目のポリシーは <Set> 要素を使用してレスポンスに変数を追加します。次の例は、Edge がクライアントに返すレスポンスに XML ペイロードを作成します。
        <!-- Policy #3: Add variables to the response -->
        <AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
          <DisplayName>put-em-in-the-payload</DisplayName>
          <Set>
            <Payload contentType="application/xml">
              <wrapper>
                <secret>{secret}</secret>
                <config>
                  <environment>{environment}</environment>
                  <protocol>{protocol}</protocol>
                </config>
              </wrapper>
            </Payload>
          </Set>
          <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
          <AssignTo createNew="false" transport="http" type="response"/>
        </AssignMessage>
        

    <Set> でフロー変数にアクセスする構文は中かっこで囲む必要があることに注意します。

    必ず、<Payload> 要素の contentType 属性を「application/xml」に設定してください。

  4. 次の例のように、リクエストを API プロキシに送信します。
    curl -vL https://ahamilton-eval-test.apigee.net/myproxy

    必要に応じて、xmllint などのユーティリティを使用して結果をパイプ処理して、XML が見やすく書式設定された構造で表示されるようにします。

    curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -

    レスポンスの本文は、次のようになります。

    <wrapper>
          <secret>42</secret>
          <config>
            <environment>test</environment>
            <protocol>gopher</protocol>
          </config>
        </wrapper>

7: Service Callout のレスポンス ヘッダーを取得する

次の例では、API プロキシ リクエストに ServiceCallout ポリシーが存在し、そのレスポンスに同じ名前(Set-Cookie)の複数のヘッダーが含まれているとします。Service Callout のレスポンス変数がデフォルトの calloutResponse であるとすると、次のポリシーによって 2 番目の Set-Cookie ヘッダー値が取得されます。

<AssignMessage continueOnError="false" enabled="true" name="get-header">
      <Set>
        <Payload contentType="application/json">
          {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
        </Payload>
      </Set>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

すべてのヘッダー値をリストするには、代わりに次の変数を使用します。

{calloutResponse.header.Set-Cookie.values}

このリファレンスの各子要素については、他にも例を用意しています。その他の例については、GitHub で AssignMessage の例をご覧ください。

子要素のリファレンス

このセクションでは、<AssignMessage> の子要素について説明します。

<Add>

リクエストやレスポンスに <AssignTo> 要素で指定された情報を追加します。

<Add> 要素は、元のメッセージに存在しない新しいプロパティをメッセージに追加します。既存のプロパティの値を変更する場合は、<Set> 要素を使用します。

デフォルト値 なし
要否 省略可
複合型
親要素 <AssignMessage>
子要素 <FormParams>
<Headers>
<QueryParams>

<Add> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Add>
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Add>
    </AssignMessage>
    

例 1

次の例は、<FormParams> 要素を使用して最初のリクエストから 3 つのクエリ文字列パラメータの値を取得し、それらをターゲット エンドポイントのリクエスト上でフォーム パラメータとして設定します。

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
      <Add>
        <FormParams>
          <FormParam name="name">{request.queryparam.name}</FormParam>
          <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
          <FormParam name="lang">{request.queryparam.lang}</FormParam>
        </FormParams>
      </Add>
      <AssignTo transport="http" type="request"/>
    </AssignMessage>
    

例 2

次の例は、<Headers> 要素を使用して、ターゲット エンドポイントのリクエストに User-Agent ヘッダーを追加します。

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
      <Add>
        <Headers>
          <Header name="user-agent">{request.user.agent}</Header>
        </Headers>
      </Add>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

例 3

次の例は、<QueryParams> 要素を使用して、単一のクエリ パラメータと静的な値をリクエストに追加します。

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
      <Add>
        <QueryParams>
          <QueryParam name="myParam">42</QueryParam>
        </QueryParams>
      </Add>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

この例では、リクエストのプリフローで <Add> を使用しています。Trace ツールなどのツールで結果を表示すると、「http://httpbin.org/get」へのリクエストが「http://httpbin.org/get?myParam=42」になることがわかります。

<Add> の子要素では、メッセージ テンプレートという動的な文字列置換がサポートされます。

<FormParams><Add> の子)

リクエスト メッセージに新しいフォーム パラメータを追加します。この要素はレスポンス メッセージには作用しません。

デフォルト値 なし
要否 省略可
<FormParam> 要素の配列
親要素 <Add>
子要素 <FormParam>

<FormParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Add>
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
      <AssignTo createNew="[true|false]" transport="http"
        type="[request|response]">destination_variable_name</AssignTo>
      </Add>
    </AssignMessage>
    

例 1

次の例は、単一のフォーム パラメータ(「answer」)と静的な値(「42」)をリクエストに追加します。

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-1">
      <Add>
        <FormParams>
          <FormParam name="answer">42</FormParam>
        </FormParams>
      </Add>
      <AssignTo transport="http" type="request"></AssignTo>
    </AssignMessage>
    

例 2

次の例は、name クエリ文字列パラメータの値を取得し、それをフォーム パラメータとしてリクエストに追加します。

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-2">
      <Add>
        <FormParam name="name">{request.queryparam.name}</FormParam>
      </Add>
    </AssignMessage>
    

この例では、<AssignTo> でターゲットが指定されていない点にご注意ください。このポリシーでは、パラメータはリクエストのみに追加されます。

例 3

次の例は、複数のフォーム パラメータをリクエストに追加します。

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
      <Add>
        <FormParams>
          <FormParam name="name">{request.queryparam.name}</FormParam>
          <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
          <FormParam name="lang">{request.queryparam.lang}</FormParam>
        </FormParams>
      </Add>
      <AssignTo transport="http" type="request"/>
    </AssignMessage>
    

この例では、元のリクエストからクエリ文字列パラメータを取得し、ターゲット エンドポイントに送信されるリクエストにフォーム パラメータとして追加します。

Trace ツールを使用すると、フローを確認できます。リクエストの本文に URL エンコード型のフォームデータが含まれていることがわかります。これは元々、クエリ文字列パラメータとして渡されたものです。

%7Busername%7D=nick&%7Bzip_code%7D=90210&%7Bdefault_language%7D=en

<FormParams> は、次の条件を満たす場合にのみ使用できます。

  • HTTP 動詞: POST
  • メッセージ タイプ: リクエスト
  • 以下のいずれか(または両方):
    • フォームデータ: なんらかの値または ""(空の文字列)に設定。たとえば、curl では -d "" をリクエストに追加します。
    • Content-Length ヘッダー: 0 に設定(元のリクエストにデータがない場合、それ以外の場合は現在のバイト単位の長さ)。たとえば、curl では、-H "Content-Length: 0" をリクエストに追加します。

例:

curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
      https://ahamilton-eval-test.apigee.net/am-test

<FormParams> を追加すると、メッセージのターゲット サービスへの送信前に Edge によってリクエストの Content-Type ヘッダーが「application/x-www-form-urlencoded」に設定されます。

<Headers><Add> の子)

<AssignTo> 要素で指定されたリクエストやレスポンスに新しいヘッダーを追加します。

デフォルト値 なし
要否 省略可
<Header> 要素の配列
親要素 <Add>
子要素 <Header>

<Headers> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Add>
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
      </Add>
    </AssignMessage>
    

例 1

次の例は、リクエスト メッセージに user-agent ヘッダーを追加して、request.user.agent フロー変数の値を割り当てます。

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
      <Add>
        <Headers>
          <Header name="user-agent">{request.user.agent}</Header>
        </Headers>
      </Add>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

<QueryParams><Add> の子)

新しいクエリ パラメータをリクエストに追加します。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
<QueryParam> 要素の配列
親要素 <Add>
子要素 <QueryParam>

<QueryParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Add>
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Add>
    </AssignMessage>
    

例 1

次の例は、リクエストにクエリ パラメータ「myParam」を追加し、値「42」を割り当てます。

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
      <Add>
        <QueryParams>
          <QueryParam name="myParam">42</QueryParam>
        </QueryParams>
      </Add>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

<QueryParams> は、次の条件を満たす場合にのみ使用できます。

  • HTTP 動詞: GET
  • メッセージ タイプ: リクエスト

さらに、<AssignTo> 要素の type 属性がリクエスト メッセージである場合のみクエリ パラメータを設定できます。この要素をレスポンスに設定しても効果はありません。

ポリシー(<Add><QueryParams/></Add>)でクエリ パラメータの空の配列を定義した場合、このポリシーではクエリ パラメータが追加されません。これは、<QueryParams> を省略した場合と同じ動作となります。

<AssignTo>

Assign Message ポリシーの操作対象のオブジェクトを決定します。選択肢は次のとおりです。

  • リクエスト メッセージ: API プロキシによって受信された request
  • レスポンス メッセージ: ターゲット サーバーから返された response
  • カスタム メッセージ: カスタムのリクエスト オブジェクトかレスポンス オブジェクト

場合によっては、Assign Message ポリシーの操作対象オブジェクトを変更できないので注意してください。たとえば、<Add><Set> を使用して、レスポンスのクエリ パラメータ(<QueryParams>)やフォーム パラメータ(<FormParams>)の追加や変更を行うことはできません。操作できるのはリクエストのクエリ パラメータとフォーム パラメータのみです。

デフォルト値 なし
要否 省略可
文字列
親要素 <AssignMessage>
子要素 なし

<AssignTo> を指定しない場合、ポリシーはその実行場所に基づいて、デフォルトのリクエストまたはレスポンスに作用します。ポリシーがリクエスト フローで実行される場合は、リクエスト メッセージに作用します。レスポンス フローで実行される場合は、デフォルトでレスポンスに作用します。

<AssignTo> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <AssignTo createNew="[true|false]" transport="http"
        type="[request|response]">destination_variable_name</AssignTo>
    </AssignMessage>
    

例 1

次の例は、ターゲットが、ターゲット エンドポイントに送信される元のリクエストであることを指定します。

<AssignMessage name="assignto-1">
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

createNew を「false」(デフォルト)に設定すると、この例では新しいリクエストが作成されません。このポリシーのすべての操作が元のリクエストに作用します。

例 2

次の例は、新しいリクエスト オブジェクトを作成します。

<AssignMessage name="assignto-2">
      <AssignTo createNew="true" transport="http" type="request"/>
    </AssignMessage>
    

新しいリクエストやレスポンスのオブジェクトを作成すると、Assign Message ポリシーの他の要素(<Add><Set><Set> など)はその新しいリクエスト オブジェクトに作用します。

フローの後続部分で他のポリシーの新しいリクエスト オブジェクトにアクセスできます。また、ServiceCallout ポリシーを使用して新しいリクエスト オブジェクトを外部サービスに送信することもできます。

例 3

次の例は、「MyRequestObject」という新しいリクエスト オブジェクトを作成します。

<AssignMessage name="assignto-2">
      <AssignTo createNew="true" transport="http" type="request"&gt;MyRequestObject&lt;/AssignTo>
    </AssignMessage>
    

新しいリクエストやレスポンスのオブジェクトを作成すると、Assign Message ポリシーの他の要素(<Add><Set><Set> など)はその新しいリクエスト オブジェクトに作用します。

フローの後続部分で他のポリシーの新しいリクエスト オブジェクトにアクセスできます。また、ServiceCallout ポリシーを使用して新しいリクエスト オブジェクトを外部サービスに送信することもできます。

次の表に、<AssignTo> の属性を示します。

属性 説明 要否
createNew

値の割り当て時にこのポリシーで新しいメッセージが作成されるかどうかを決定します。

「true」の場合は、type で指定されたタイプ(「リクエスト」か「レスポンス」)の新しい変数が作成されます。新しい変数の名前を指定しない場合は、type の値に基づいて新しいリクエストかレスポンスのいずれかが作成されます。

「false」の場合は、次のいずれかの処理が行われます。

  • <AssignTo> で変数名をリクエストまたはレスポンスに解決できる場合は、処理が続行されます。たとえば、ポリシーがリクエスト フロー内にある場合、変数はリクエスト オブジェクトです。ポリシーがレスポンス内にある場合、変数はレスポンス オブジェクトです。
  • <AssignTo> を解決できない場合、またはメッセージ以外のタイプに解決される場合は、エラーがスローされます。

createNew の指定がない場合、このポリシーは次のいずれかの処理を行います。

  • <AssignTo> がメッセージに解決される場合は、処理が次のステップに進みます。
  • <AssignTo> を解決できない場合、またはメッセージ以外のタイプに解決された場合は、type で指定されたタイプの新しい変数が作成されます。
省略可 ブール値
transport

リクエスト / レスポンスのメッセージ タイプにトランスポート タイプを指定します。

デフォルト値は「http」(唯一サポートされる値)です。

省略可 文字列
type createNew が「true」のときに、新しいメッセージのタイプを指定します。有効な値は「request」か「response」です。

デフォルト値は「request」です。この属性を省略すると、Edge ではこのポリシーが実行されるフロー内の場所に応じて、リクエストまたはレスポンスが作成されます。

省略可 文字列

<AssignVariable>

宛先フロー変数(Assign Message ポリシーによって値が設定される変数など)に値を割り当てます。フロー変数が存在しない場合は、<AssignVariable> によって作成されます。

デフォルト値 なし
要否 省略可
複合型
親要素 <AssignMessage>
子要素 <Name> (必須)
<Ref>
<Template>
<Value>

宛先フロー変数に割り当てる値は、次のいずれかにできます。

  • リテラル文字列: <Value> 子要素を使用して、宛先フロー変数にリテラル文字列値を指定します。
  • フロー変数: <Ref> 子要素を使用して宛先フロー変数に既存のフロー変数の値を指定します。参照元として使用できるフロー変数の完全なリストについては、フロー変数リファレンスをご覧ください。
  • メッセージ テンプレート: <Template> 子要素を使用して、宛先フロー変数にメッセージ テンプレートを指定します。

<AssignVariable> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <AssignVariable>
        <Name>variable_name</Name>
        <Ref>source_variable</Ref>
        <Template>message_template</Template>
        <Value>variable_value</Value>
      </AssignVariable>
    </AssignMessage>
    

<Ref> 要素を使用して参照元の変数を指定します。<Ref> によって参照される変数にアクセスできない場合は、<Value> 要素で指定される値が Edge で使用されます。<Template> を定義すると、他の子要素よりも優先されます。

例 1

次の例では、新しい変数 myvar の値をリテラル値「42」に設定します。

<AssignMessage name="assignvariable-1">
      <AssignVariable>
        <Name>myvar</Name>
        <Value>42</Value>
      </AssignVariable>
    </AssignMessage>
    

例 2

次の例は、フロー変数 request.header.user-agent の値を宛先フロー変数 myvar に割り当て、クエリ パラメータ country の値を宛先フロー変数 Country に割り当てます。

<AssignMessage name="assignvariable-2">
      <AssignVariable>
        <Name>myvar</Name>
        <Ref>request.header.user-agent</Ref>
        <Value>ErrorOnCopy</Value>
      </AssignVariable>
      <AssignVariable>
        <Name>Country</Name>
        <Ref>request.queryparam.country</Ref>
        <Value>ErrorOnCopy</Value>
      </AssignVariable>
    </AssignMessage>
    

いずれかの割り当てが失敗した場合、Edge は宛先フロー変数に値「ErrorOnCopy」を割り当てます。

myvar または Country のフロー変数が存在しない場合は、<AssignVariable> によって作成されます。

例 3

次の例では、<Template> 子要素を使用して、リテラル文字列(ハイフン)で 2 つのコンテキスト変数を連結します。

<AssignMessage name='template-1'>
      <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
      <AssignVariable>
        <Name>my_destination_variable</Name>
        <Value>BADDBEEF</Value>
        <Template>{system.uuid}-{messageid}</Template>
      </AssignVariable>
    </AssignMessage>
    

<AssignVariable> の一般的な用途は、リクエストで渡すことができるクエリ パラメータ、ヘッダー、その他の値にデフォルト値を設定することです。これは、<Ref><Value> の両方の子要素の組み合わせを使用して行います。詳細については、<Ref> の例をご覧ください。

<Name><AssignVariable> の子)

宛先フロー変数(たとえば、Assign Message ポリシーによって値が設定される変数)の名前を指定します。<AssignVariable> で指定された変数が存在しない場合は、ポリシーによってその名前の変数が作成されます。

デフォルト値 なし
要否 必須
文字列
親要素 <AssignVariable>
子要素 なし

<Name> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <AssignVariable>
        <Name>variable_name</Name>
      </AssignVariable>
    </AssignMessage>
    

例 1

次の例は、宛先変数に myvar を指定し、リテラル値「42」に設定します。

<AssignMessage name="assignvariable-1">
      <AssignVariable>
        <Name>myvar</Name>
        <Value>42</Value>
      </AssignVariable>
    </AssignMessage>
    

myvar が存在しない場合は、<AssignVariable> によって作成されます。

<Ref><AssignVariable> の子)

割り当ての参照元をフロー変数として指定します。フロー変数は、あらかじめ定義されたフロー変数(フロー変数リファレンスに存在するもの)か、ユーザーが作成したカスタムフロー変数のいずれかにできます。

<Ref> の値は常にフロー変数として解釈されるため、値にリテラル文字列を指定することはできません。リテラル文字列値を割り当てるには、<Value> 要素を使用します。

デフォルト値 なし
要否 省略可
文字列
親要素 <AssignVariable>
子要素 なし

<Ref> を使用してフロー変数を指定する場合は、通常のフロー変数の参照で使用される中かっこ「{}」を省略します。たとえば、新しい変数の値を client.host フロー変数の値に設定する場合は次のようになります。

Do this (no brackets):
      <Ref>client.host</Ref>

    Do NOT do this (brackets):
      <Ref>{client.host}</Ref>

宛先フロー変数にデフォルト値を定義するには、<Value><Ref> と組み合わせて使用します。<Ref> で指定されるフロー変数が存在しないか、読み込めない、または null である場合、Edge は <Value> の値を宛先フロー変数に割り当てます。

<Ref> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <AssignVariable>
        <Name>variable_name</Name>
        <Ref>source_variable</Ref>
      </AssignVariable>
    </AssignMessage>
    

例 1

次の例は、フロー変数 request.header.user-agent の値を宛先フロー変数 myvar に割り当て、クエリ パラメータ country の値を Country 変数に割り当てます。

<AssignMessage name="assignvariable-4">
      <AssignVariable>
        <Name>myvar</Name>
        <Ref>request.header.user-agent</Ref>
      </AssignVariable>
      <AssignVariable>
        <Name>Country</Name>
        <Ref>request.queryparam.country</Ref>
      </AssignVariable>
    </AssignMessage>
    

この例では、どちらの割り当てについても Edge にデフォルト(またはフォールバック値)が設定されていません。

例 2

次の例は、フロー変数 request.header.user-agent の値を宛先フロー変数 myvar に割り当て、クエリ パラメータ country の値を Country 変数に割り当てます。

<AssignMessage name="assignvariable-2">
      <AssignVariable>
        <Name>myvar</Name>
        <Ref>request.header.user-agent</Ref>
        <Value>ErrorOnCopy</Value>
      </AssignVariable>
      <AssignVariable>
        <Name>Country</Name>
        <Ref>request.queryparam.country</Ref>
        <Value>ErrorOnCopy</Value>
      </AssignVariable>
    </AssignMessage>
    

この例で、request.header.user-agent フロー変数の値、または Country クエリ パラメータの値が null、読み取り不能、または形式が不適切な場合、Edge は新しい変数に値「ErrorOnCopy」を割り当てます。

例 3

<AssignVariable> の一般的な用途は、リクエストで渡すことができるクエリ パラメータ、ヘッダーまたはその他の値にデフォルト値を設定することです。たとえば、リクエストで「w」という単一のクエリ パラメータを取得する、天気情報の API プロキシを作成するとします。このパラメータには天気情報を取得する都市の ID が格納されます。リクエスト URL の形式は次のようになります。

http://myCO.com/v1/weather/forecastrss?w=city_ID

「w」にデフォルト値を定義するには、次のような Assign Message ポリシーを作成します。

<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3">
      <AssignTo createNew="false" transport="http" type="request"/>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
      <AssignVariable>
        <Name>request.queryparam.w</Name>
        <Ref>request.queryparam.w</Ref>
        <Value>12797282</Value>
      </AssignVariable>
    </AssignMessage>
    

この例で、<AssignVariable>request.queryparam.w の値を取得して、それを自身に割り当てます。フロー変数が null の場合、つまり、「w」クエリ パラメータがリクエストで省略されている場合、この例では、<Value> 要素のデフォルト値が使用されます。したがって、この API プロキシに対し、「w」クエリ パラメータを省略したリクエストを行うことができます。

http://myCO.com/v1/weather/forecastrss

このため、上記の場合も API プロキシから有効な結果が返されることになります。

<Value> の使用時とは異なり、<Ref> の値は requestresponse、または target オブジェクトのプロパティなどのフロー変数にする必要があります。この値はユーザーが作成したカスタムフロー変数にすることもできます。

<Ref> の値に存在しないフロー変数を指定し、<IgnoreUnresolvedVariables> の値が「true」の場合は、Edge によってエラーがスローされます。

<Template><AssignVariable> の子)

割り当ての参照元をメッセージ テンプレートとして指定します。これにより、中かっこで囲まれた <Template> 要素内の変数名をリテラル文字列で連結できます。また、メッセージ テンプレートは、エスケープ文字や大文字小文字の変換にも対応しています。

デフォルト値 なし
要否 省略可
文字列
親要素 <AssignVariable>
子要素 なし

<Template> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <AssignVariable>
        <Template>message_template</Template>
      </AssignVariable>
    </AssignMessage>
    

例 1

次の例では、メッセージ テンプレートの構文を使用して、2 つのコンテキスト変数をリテラル文字列で連結します。

<AssignMessage name='template-1'>
      <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
      <AssignVariable>
        <Name>my_destination_variable</Name>
        <Value>BADDBEEF</Value>
        <Template>{system.uuid}-{messageid}</Template>
      </AssignVariable>
    </AssignMessage>
    

<Value><AssignVariable> の子)

<AssignVariable> で設定された宛先フロー変数の値を定義します。この値は常にリテラル文字列として解釈されるため、値を中かっこ(「{}」)で囲んでもフロー変数として使用することはできません。フロー変数を使用する場合は、<Ref> を使用します。

デフォルト値 なし
要否 省略可
文字列
親要素 <AssignVariable>
子要素 なし

<Ref> 要素と組み合わせて使用すると、<Value> はデフォルト(またはフォールバック)値として機能します。<Ref> の指定がない場合、解決できない場合、null の場合は、<Value> の値が使用されます。

<Value> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <AssignVariable>
        <Name>variable_name</Name>
        <Value>variable_value</Value>
      </AssignVariable>
    </AssignMessage>
    

例 1

次の例は、宛先フロー変数 myvar の値をリテラル値「42」に設定します。

<AssignMessage name="assignvariable-1">
      <AssignVariable>
        <Name>myvar</Name>
        <Value>42</Value>
      </AssignVariable>
    </AssignMessage>
    

例 2

次の例は、フロー変数 request.header.user-agent の値をフロー変数 myvar に割り当て、クエリ パラメータ country の値を Country 変数に割り当てます。

<AssignMessage name="assignvariable-2">
      <AssignVariable>
        <Name>myvar</Name>
        <Ref>request.header.user-agent</Ref>
        <Value>ErrorOnCopy</Value>
      </AssignVariable>
      <AssignVariable>
        <Name>Country</Name>
        <Ref>request.queryparam.country</Ref>
        <Value>ErrorOnCopy</Value>
      </AssignVariable>
    </AssignMessage>
    

どちらかの割り当てが失敗すると、<AssignVariable> は宛先フロー変数に値「ErrorOnCopy」を割り当てます。

<Copy>

source 属性で指定されたメッセージの値を<AssignTo> 要素で指定されたメッセージにコピーします。<AssignTo> でターゲットを指定しない場合は、ポリシーはその実行場所に応じてリクエストかレスポンスに値をコピーします。

デフォルト値 なし
要否 省略可
文字列
親要素 <AssignVariable>
子要素 <FormParams>
<Headers>
<Path>
<Payload>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

<Copy> 要素の構文は次のとおりです。

構文

<AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
        <Copy source="[request|response]">
        <!-- Can also be an empty array (<FormParams/>) -->
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <!-- Can also be an empty array (<Headers/>) -->
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <Path>[false|true]</Path>
        <Payload>[false|true]</Payload>
        <!-- Can also be an empty array (<QueryParams/>) -->
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
        <ReasonPhrase>[false|true]</ReasonPhrase>
        <StatusCode>[false|true]</StatusCode>
        <Verb>[false|true]</Verb>
        <Version>[false|true]</Version>
      </Copy>
      <!-- Used as the destination for the <Copy> values -->
      <AssignTo createNew="[true|false]" transport="http"
        type="[request|response]">destination_variable_name</AssignTo>
    </AssignMessage>
      

例 1

次の例は、リクエストのヘッダー、3 つのフォーム パラメータ、パス、すべてのクエリ パラメータが、新しいカスタム リクエストにコピーされます。

<AssignMessage continueOnError="false" enabled="true" name="copy-1">
      <Copy source="request">
        <Headers>
          <Header name="Header_Name_1">Header value 1</Header>
        </Headers>
        <FormParams>
          <FormParam name="Form_Param_Name_1">Form param value 1</FormParam>
          <FormParam name="Form_Param_Name_2">Form param value 1</FormParam>
          <FormParam name="Form_Param_Name_3">Form param value 1</FormParam>
        </FormParams>
        <Payload>false</Payload>
        <Path>true</Path>
        <QueryParams/>
        <ReasonPhrase>false</ReasonPhrase>
        <StatusCode>false</StatusCode>
        <Verb>false</Verb>
        <Version>false</Version>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request"/>
    </AssignMessage>

<Copy> 要素には次の属性があります。

属性 説明 要否
source

コピー元のオブジェクトを指定します。

  • source の指定がない場合は、単純なメッセージとして扱われます。たとえば、ポリシーがリクエスト フローに存在する場合は、コピー元はデフォルトで request オブジェクトになります。ポリシーがレスポンス フローに存在する場合は、デフォルトで response オブジェクトになります。source を省略した場合は、フロー変数の絶対参照をコピー元として使用できます。たとえば、値を {request.header.user-agent} と指定します。
  • コピー元の変数を解決できなかった場合、またはメッセージ以外のタイプに解決された場合、<Copy> はレスポンスできません。
省略可 文字列

<FormParams><Copy> の子)

<Copy> 要素の source 属性で指定されたリクエストのフォーム パラメータを、<AssignTo> 要素で指定されたリクエストにコピーします。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
<FormParam> 要素の配列または空の配列
親要素 <Copy>
子要素 <FormParam>

<FormParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <!-- Can also be an empty array (<FormParams/>) -->
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、リクエストの単一のフォーム パラメータをカスタム リクエスト「MyCustomRequest」にコピーします。

<AssignMessage name="copy-formparams-1">
      <Copy source="request">
        <FormParams>
          <FormParam name="paramName">Form param value 1</FormParam>
        </FormParams>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

例 2

次の例は、すべてのフォーム パラメータをカスタム リクエスト「MyCustomRequest」にコピーします。

<AssignMessage name="copy-formparams-2">
      <Copy source="request">
        <FormParams/>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

例 3

次の例は、3 つのフォーム パラメータをカスタム リクエスト「MyCustomRequest」にコピーします。

<AssignMessage name="copy-formparams-3">
      <Copy source="request">
        <FormParams>
          <FormParam name="paramName1"/>
          <FormParam name="paramName2"/>
          <FormParam name="paramName3"/>
        </FormParams>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

例 4

同じ名前のフォーム パラメータが複数存在する場合は、次の構文を使用します。

<AssignMessage name="copy-formparams-4">
      <Copy source="request">
        <FormParams>
          <FormParam name="f1"/>
          <FormParam name="f2"/>
          <FormParam name="f3.2"/>
        </FormParams>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

この例では、「f1」、「f2」、および「f3」の 2 番目の値がコピーされます。「f3」の値が 1 つのみの場合はコピーされません。

<FormParams> は、次の条件を満たす場合にのみ使用できます。

  • HTTP 動詞: POST
  • メッセージ タイプ: レスポンス
  • 以下のいずれか(または両方):
    • フォームデータ: なんらかの値または ""(空の文字列)に設定。たとえば、curl では -d "" をリクエストに追加します。
    • Content-Length ヘッダー: 0(元のリクエストにデータがない場合。それ以外の場合は現在の長さ)。たとえば、curl では、-H "Content-Length: 0" をリクエストに追加します。

<FormParams> をコピーすると、メッセージをターゲット サービスに送信する前に、<Copy> によってメッセージの Content-Type が「application/x-www-form-urlencoded」に設定されます。

<Headers><Copy> の子)

<Copy> 要素の source 属性で指定されたリクエスト / レスポンス メッセージの HTTP ヘッダーを<AssignTo> 要素で指定されたリクエスト / レスポンス メッセージにコピーします。

デフォルト値 なし
要否 省略可
<Header> 要素の配列または空の配列
親要素 <Copy>
子要素 <Header>

<Headers> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <!-- Can also be an empty array (<Headers/>) -->
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、リクエストの user-agent ヘッダーを新しいカスタム リクエスト オブジェクトにコピーします。

<AssignMessage name="copy-headers-1">
      <Copy source="request">
        <Headers>
          <Header name="user-agent"/>
        </Headers>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

例 2

すべてのヘッダーをコピーするには、次の例で示されるように空の <Headers> 要素を使用します。

<AssignMessage name="copy-headers-2">
      <Copy source="request">
        <Headers/>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

例 3

同じ名前のヘッダーが複数存在する場合は、次の構文を使用します。

<AssignMessage name="copy-headers-3">
      <Copy source="request">
        <Headers>
          <Header name="h1"/>
          <Header name="h2"/>
          <Header name="h3.2"/>
        </Headers>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

この例では、「h1」、「h2」、および「h3」の 2 番目の値がコピーされます。「h3」の値が 1 つのみの場合はコピーされません。

<Path><Copy> の子)

コピー元リクエストのパスをコピー先リクエストにコピーするかどうかを決定します。この要素はレスポンスには作用しません。

「true」の場合、このポリシーは <Copy> 要素の source 属性のパスを<AssignTo> 要素で指定されたリクエスト メッセージにコピーします。

デフォルト値 false
要否 省略可
ブール値
親要素 <Copy>
子要素 なし

<Path> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <Path>[false|true]</Path>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、Assign Message によって、コピー元のリクエストのパスが新しいカスタム リクエスト オブジェクトにコピーされることを示しています。

<AssignMessage name="copy-path-1">
      <Copy source="request">
        <Path>true</Path>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

<Path> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: リクエスト

<Payload><Copy> の子)

ペイロードをコピー元からコピー先にコピーするかどうかを決定します。コピー元とコピー先は、リクエストとレスポンスのどちらでもかまいません。

「true」の場合、このポリシーは <Copy> 要素の source 属性で指定されたメッセージから<AssignTo> 要素で指定されたメッセージに、ペイロードをコピーします。

デフォルト値 false
要否 省略可
ブール値
親要素 <Copy>
子要素 なし

<Payload> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <Payload>[false|true]</Payload>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、<Payload> を「true」に設定し、リクエストのペイロードがリクエストからレスポンスにコピーされるようにします。

<AssignMessage name="copy-payload-1">
      <Copy source="request">
        <Payload>true</Payload>
      </Copy>
      <AssignTo createNew="true" transport="http" type="response"/>
    </AssignMessage>
    

<QueryParams><Copy> の子)

<Copy> 要素の source 属性で指定されたリクエストから<AssignTo> 要素で指定されたリクエストに、クエリ文字列パラメータをコピーします。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
<QueryParam> 要素の配列または空の配列
親要素 <QueryParam>
子要素 なし

<QueryParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <!-- Can also be an empty array (<QueryParams/>) -->
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、リクエストから新しいカスタム リクエスト オブジェクトに「my_param」クエリ パラメータをコピーします。

<AssignMessage name="copy-queryparams-1">
      <Copy source="request">
        <QueryParams>
          <QueryParam name="my_param"/>
        </QueryParams>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

例 2

次の例は、リクエストのすべてのクエリ パラメータを新しいカスタム リクエスト オブジェクトにコピーします。

<AssignMessage name="copy-queryparams-2">
      <Copy source="request">
        <QueryParams/>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

例 3

同じ名前のクエリ パラメータが複数存在する場合は、次の構文を使用します。

<AssignMessage name="copy-queryparams-3">
      <Copy source="request">
        <QueryParams>
          <QueryParam name="qp1"/>
          <QueryParam name="qp2"/>
          <QueryParam name="qp3.2"/>
        </QueryParams>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

この例では、「qp1」、「qp2」、および「qp3」の 2 番目の値がコピーされます。「qp3」の値が 1 つのみの場合はコピーされません。

<QueryParams> は、次の条件を満たす場合にのみ使用できます。

  • HTTP 動詞: GET
  • メッセージ タイプ: リクエスト

<ReasonPhrase><Copy> の子)

コピー元レスポンスからコピー先レスポンスに理由句をコピーするかどうかを決定します。この要素はリクエストには作用しません。

「true」の場合、このポリシーは <Copy> 要素の source 属性で指定されたレスポンスから<AssignTo> 要素で指定されたレスポンスにReasonPhrase をコピーします。

デフォルト値 false
要否 省略可
ブール値
親要素 <Copy>
子要素 なし

<ReasonPhrase> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <ReasonPhrase>[false|true]</ReasonPhrase>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、<ReasonPhrase> を「true」に設定して、<Copy> によってデフォルトのレスポンスからカスタム レスポンス オブジェクトに理由句がコピーされるようにします。

<AssignMessage name="copy-reasonphrase-1">
      <Copy source="response">
        <ReasonPhrase>true</ReasonPhrase>
      </Copy>
      <AssignTo createNew="trie" transport="http" type="response">MyCustomResponse</AssignTo>
    </AssignMessage>
    

<ReasonPhrase> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: レスポンス

<StatusCode><Copy> の子)

コピー元レスポンスからコピー先レスポンスにステータス コードがコピーされるかどうかを決定します。この要素はリクエストには作用しません。

「true」の場合、このポリシーは <Copy> 要素の source 属性で指定されたレスポンス メッセージから、<AssignTo> 要素で指定されたレスポンス メッセージにステータス コードをコピーします。

デフォルト値 false
要否 省略可
ブール値
親要素 <Copy>
子要素 なし

<StatusCode> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <StatusCode>[false|true]</StatusCode>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、<StatusCode> を「true」に設定して、デフォルトのレスポンス オブジェクトから新しいカスタム レスポンス オブジェクトにステータス コードがコピーされるようにします。

    <AssignMessage name="copy-statuscode-1">
      <Copy source="response">
        <StatusCode>true</StatusCode>
      </Copy>
      <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
    </AssignMessage>
    

<StatusCode> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: レスポンス

<StatusCode> の一般的な用途は、<AssignTo>createNew 属性が「true」の場合に、ターゲットから受信したレスポンスと同じステータスがプロキシ レスポンスに設定されるようにすることです。

<Verb><Copy> の子)

コピー元リクエストからコピー先リクエストに HTTP 動詞をコピーするかどうかを決定します。この要素はレスポンスには作用しません。

「true」の場合、<Copy> 要素の source 属性にある動詞を <AssignTo> 要素で指定されたリクエストにコピーします。

デフォルト値 false
要否 省略可
ブール値
親要素 <Copy>
子要素 なし

<Verb> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <Verb>[false|true]</Verb>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、<Verb> を「true」に設定して、デフォルトのリクエストから新しいカスタム リクエストに動詞をコピーします。

<AssignMessage name="copy-verb-1">
      <Copy source="request">
        <Verb>true</Verb>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

<Verb> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: リクエスト

<Version><Copy> の子)

コピー元リクエストからコピー先リクエストに HTTP バージョンをコピーするかどうかを決定します。この要素はレスポンスには作用しません。

「true」の場合、<Copy> 要素の source 属性にある HTTP バージョンを <AssignTo> 要素で指定されたオブジェクトにコピーします。

デフォルト値 false
要否 省略可
ブール値
親要素 <Copy>
子要素 なし

<Version> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Copy source="[request|response]">
        <Version>[false|true]</Version>
      </Copy>
    </AssignMessage>
    

例 1

次の例は、リクエストで <Version> を「true」に設定して、デフォルトのリクエスト オブジェクトのバージョンを新しいカスタム リクエスト オブジェクトにコピーします。

<AssignMessage name="copy-version-1">
      <Copy source="request">
        <Version>true</Version>
      </Copy>
      <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

<Version> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: リクエスト

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

デフォルト値 該当なし
要否 省略可。<DisplayName> 要素を省略した場合、ポリシーの name 属性の値が使用されます
文字列
親要素 <PolicyElement>
子要素 なし

<DisplayName> 要素の構文は次のとおりです。

構文

    <PolicyElement>
      <DisplayName>policy_display_name</DisplayName>
      ...
    </PolicyElement>
    

    <AssignMessage>
      <DisplayName>My Validation Policy</DisplayName>
    </AssignMessage>
    

<DisplayName> 要素に属性や子要素はありません。

<IgnoreUnresolvedVariables>

未解決の変数に突き当たった場合に、処理を停止するかどうかを決定します。

デフォルト値 true
要否 省略可
ブール値
親要素 <AssignMessage>
子要素 なし

未解決の変数を無視して処理を続行するには「true」に設定します。それ以外の場合は「false」に設定します。デフォルト値は「true」です。

<IgnoreUnresolvedVariables> を「true」に設定することは、変数値の設定と取得に限定される点で、<AssignMessage>continueOnError を「true」に設定することとは異なります。continueOnError を「true」に設定すると、Edge では変数使用時に発生したエラーだけではなく、すべてのエラーが無視されます。

<IgnoreUnresolvedVariables> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
    </AssignMessage>
    

例 1

次の例は、<IgnoreUnresolvedVariables> を「true」に設定します。

<AssignMessage name="ignoreunresolvedvariables">
      <Copy source="response">
        ...
        <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
      </Copy>
    </AssignMessage>
    

<Remove>

ヘッダー、クエリ パラメータ、フォーム パラメータ、メッセージ ペイロードをメッセージから削除します。メッセージはリクエストでも、レスポンスでもかまいません。<AssignTo> 要素を使用して、<Remove> の操作対象のメッセージを指定します。

デフォルト値 なし
要否 省略可
複合型
親要素 <AssignMessage>
子要素 <FormParams>
<Headers>
<Payload>
<QueryParams>

<Remove> の一般的な用途は、受信リクエスト オブジェクトからの機密情報が含まれるクエリ パラメータを削除して、バックエンド サーバーに渡されないようにすることです。

<Remove> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Remove>
        <!-- Can also be an empty array (<FormParams/>) -->
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <!-- Can also be an empty array (<Headers/>) -->
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <Payload>[false|true]</Payload>
        <!-- Can also be an empty array (<QueryParams/>) -->
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Remove>
    </AssignMessage>
    

例 1

次の例は、レスポンスからメッセージの本文を削除します。

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
      <DisplayName>remove-1</DisplayName>
      <Remove>
        <Payload>true</Payload>
      </Remove>
      <AssignTo createNew="false" transport="http" type="response"/>
    </AssignMessage>
    

レスポンス フローではこのポリシーによってレスポンスの本文が削除され、HTTP ヘッダーのみがクライアントに返されます。

例 2

次の例は、受信リクエストからすべてのフォーム パラメータとクエリ パラメータを削除します。

<AssignMessage continueOnError="false" enabled="true" name="remove-2">
      <Remove>
        <!-- Empty (<FormParams/>) removes all form parameters -->
        <FormParams/>
        <QueryParams>
          <QueryParam name="qp1"/>
        </QueryParams>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

<FormParams><Remove> の子)

指定されたフォーム パラメータをリクエストから削除します。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
<FormParam> 要素の配列または空の配列
親要素 <Remove>
子要素 <FormParam>

<FormParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Remove>
        <!-- Can also be an empty array (<FormParams/>) -->
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
      </Remove>
    </AssignMessage>
    

例 1

次の例は、リクエストから 3 つのフォーム パラメータを削除します。

<AssignMessage name="remove-formparams-1">
      <Remove>
        <FormParams>
          <FormParam name="form_param_1"/>
          <FormParam name="form_param_2"/>
          <FormParam name="form_param_3"/>
        </FormParams>
      </Remove>
      <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
    </AssignMessage>
    

例 2

次の例は、リクエストからすべてのフォーム パラメータを削除します。

<AssignMessage name="remove-formparams-2">
      <Remove>
        <FormParams/>
      </Remove>
      <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
    </AssignMessage>
    

例 3

同じ名前のフォーム パラメータが複数存在する場合は、次の構文を使用します。

<AssignMessage name="remove-formparams-3">
      <Remove>
        <FormParams>
          <FormParam name="f1"/>
          <FormParam name="f2"/>
          <FormParam name="f3.2"/>
        </FormParams>
      </Remove>
      <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
    </AssignMessage>
    

この例では、「f1」、「f2」と、「f3」の 2 番目の値が削除されます。「f3」の値が 1 つのみの場合は削除されません。

<FormParams> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: リクエスト
  • Content-Type: "application/x-www-form-urlencoded"

<Headers><Remove> の子)

<AssignTo> 要素によって指定されたリクエストやレスポンスから、指定された HTTP ヘッダーを削除します。

デフォルト値 なし
要否 省略可
<Header> 要素の配列または空の配列
親要素 <Remove>
子要素 <Header>

<Headers> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Remove>
        <!-- Can also be an empty array (<Headers/>) -->
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
      </Remove>
    </AssignMessage>
    

例 1

次の例は、リクエストから user-agent ヘッダーを削除します。

<AssignMessage name="remove-headers-1">
      <Remove>
        <Headers>
          <Header name="user-agent"/>
        </Headers>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

例 2

次の例は、リクエストからすべてのヘッダーを削除します。

<AssignMessage name="remove-headers-2">
      <Remove>
        <Headers/>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

例 3

同じ名前のヘッダーが複数存在する場合は、次の構文を使用します。

<AssignMessage name="remove-headers-3">
      <Remove>
        <Headers>
          <Header name="h1"/>
          <Header name="h2"/>
          <Header name="h3.2"/>
        </Headers>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

この例では、「h1」、「h2」と、「h3」の 2 番目の値がリクエストから削除されます。「h3」の値が 1 つのみの場合は削除されません。

<Payload><Remove> の子)

<AssignTo> 要素で指定されたリクエストやレスポンスのペイロードを、<Remove> で削除するかどうかを決定します。ペイロードをクリアするには「true」に設定し、それ以外の場合は「false」に設定します。デフォルト値は「false」です。

デフォルト値 false
要否 省略可
ブール値
親要素 <Remove>
子要素 なし

<Payload> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Remove>
        <Payload>[false|true]</Payload>
      </Remove>
    </AssignMessage>
    

例 1

次の例は、<Payload> を「true」に設定して、リクエストのペイロードがクリアされるようにします。

<AssignMessage name="remove-payload-1">
      <Remove>
        <Payload>true</Payload>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

<QueryParams><Remove> の子)

指定されたクエリ パラメータをリクエストから削除します。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
<QueryParam> 要素の配列または空の配列
親要素 <Remove>
子要素 <QueryParam>

<QueryParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Remove>
        <!-- Can also be an empty array (<QueryParams/>) -->
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Remove>
    </AssignMessage>
    

例 1

次の例は、リクエストから単一のクエリ パラメータを削除します。

<AssignMessage name="remove-queryparams-1">
      <Remove>
          <QueryParams>
            <QueryParam name="qp1"/>
          </QueryParams>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

例 2

次の例は、リクエストからすべてのクエリ パラメータを削除します。

<AssignMessage name="remove-queryparams-2">
      <Remove>
          <QueryParams/>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

例 3

同じ名前のクエリ パラメータが複数存在する場合は、次の構文を使用します。

<AssignMessage name="remove-queryparams-3">
      <Remove>
          <QueryParams>
            <QueryParam name="qp1"/>
            <QueryParam name="qp2"/>
            <QueryParam name="qp3.2"/>
          </QueryParams>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

この例では、「qp1」、「qp2」と、「qp3」の 2 番目の値がリクエストから削除されます。「qp3」の値が 1 つのみの場合は削除されません。

例 4

次の例は、リクエストから apikey クエリ パラメータを削除します。

<AssignMessage name="remove-query-param">
      <Remove>
        <QueryParams>
          <QueryParam name="apikey"/>
        </QueryParams>
      </Remove>
      <AssignTo createNew="false" transport="http" type="request"/>
    </AssignMessage>
    

<QueryParams> は、次の条件を満たす場合にのみ使用できます。

  • HTTP 動詞: GET
  • メッセージ タイプ: リクエスト

<Set>

<AssignTo> 要素で指定されたリクエストまたはレスポンスのメッセージの情報を設定します。<Set> は、元のメッセージの既存のヘッダーやパラメータを上書きします。新しいヘッダーやパラメータを作成する場合は、<Add> 要素を使用します。

デフォルト値 なし
要否 省略可
複合型
親要素 <AssignMessage>
子要素 <FormParams>
<Headers>
<Payload>
<Path>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

<Set> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
        <Path>path</Path>
        <Payload contentType="content_type" variablePrefix="prefix"
            variableSuffix="suffix">new_payload</Payload>
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
        <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
        <StatusCode>HTTP_status_code or {variable}</StatusCode>
        <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
        <Version>[1.0|1.1|{variable}]</Verb>
      </Set>
    </AssignMessage>
    

例 1

次の例は <Set> 要素を示しています。

<AssignMessage continueOnError="false" enabled="true" name="set-1">
      <Set>
        <FormParams>
          <FormParam name="myparam">{request.header.myparam}</FormParam>
        </FormParams>
        <Headers>
            <Header name="user-agent">{request.header.user-agent}</Header>
        </Headers>
        <QueryParams>
          <QueryParam name="name">{request.header.name}</QueryParam>
          <QueryParam name="address">{request.header.address}</QueryParam>
        </QueryParams>
        <!-- <Verb>GET</Verb> -->
        <Payload contentType="text/plain">42</Payload>
        <Path/>
        <ReasonPhrase>Bad request</ReasonPhrase>
        <StatusCode>400</StatusCode>
        <Verb>POST</Verb>
        <Verb>{my_variable}</Verb>
        <Version>1.1</Version>
      </Set>
      <AssignTo createNew="false" transport="http" type="response"/>
    </AssignMessage>
    

<FormParams><Set> の子)

リクエストに既存のフォーム パラメータを上書きして、この要素で指定される新しい値に置き換えます。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
<FormParam> 要素の配列
親要素 <Set>
子要素 <FormParam>

<FormParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <FormParams>
          <FormParam name="formparam_name">formparam_value</FormParam>
          ...
        </FormParams>
      </Set>
    </AssignMessage>
    

例 1

次の例は、新しいカスタム リクエストの request.header.myparam 変数の値に「myparam」というフォーム パラメータを設定します。

<AssignMessage name="set-formparams-1">
      <Set>
        <FormParams>
          <FormParam name="myparam">{request.header.myparam}</FormParam>
        </FormParams>
      </Set>
        <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
    </AssignMessage>
    

<FormParams> は、次の条件を満たす場合にのみ使用できます。

  • HTTP 動詞: POST
  • メッセージ タイプ: リクエスト

ポリシー(<Add><FormParams/></Add>)に空のフォーム パラメータを定義した場合、そのポリシーはフォーム パラメータを追加しません。これは <FormParams> を省略した場合と同じ動作となります。

ターゲット エンドポイントへの送信前に、<Set> によってメッセージの Content-Type が「application/x-www-form-urlencoded」に変更されます。

<Headers><Set> の子)

<AssignTo> 要素によって指定されるリクエストやレスポンスに既存の HTTP ヘッダーを上書きします。

デフォルト値 なし
要否 省略可
<Header> 要素の配列
親要素 <Set>
子要素 <Header>

<Headers> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <Headers>
          <Header name="header_name">header_value</Header>
          ...
        </Headers>
      </Set>
    </AssignMessage>
    

例 1

次の例は、request.header.user-agent 変数の値に user-agent ヘッダーを設定します。

<AssignMessage name="set-headers-1">
      <Set>
        <Headers>
          <Header name="user-agent">{request.header.user-agent}</Header>
        </Headers>
      </Set>
      <AssignTo createNew="true" transport="http" type="response"/>
    </AssignMessage>
    

ポリシー(<Add><Headers/></Add>)で空のヘッダーを定義した場合、そのポリシーはヘッダーを追加しません。これは <Headers> を省略した場合と同じ動作となります。

<Path><Set> の子)

<Payload><Set> の子)

<AssignTo> 要素で指定されたリクエストやレスポンスのメッセージ本文を定義します。ペイロードは、書式なしテキスト、JSON、XML などの任意の有効なコンテンツ タイプにできます。

デフォルト値 空の文字列
要否 省略可
文字列
親要素 <Set>
子要素 なし

<Payload> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <Payload contentType="content_type" variablePrefix="prefix"
            variableSuffix="suffix">new_payload</Payload>
      </Set>
    </AssignMessage>
    

例 1

次の例は、書式なしテキストのペイロードを設定します。

<AssignMessage name="set-payload-1">
      <Set>
        <Payload contentType="text/plain">42</Payload>
      </Set>
    </AssignMessage>
    

例 2

次の例は、JSON ペイロードを設定します。

<AssignMessage name="set-payload-2">
      <Set>
        <Payload contentType="application/json">
          {"name":"foo", "type":"bar"}
        </Payload>
      </Set>
    </AssignMessage>
    

例 3

次の例は、変数名を中かっこで囲むことで、変数値をペイロードに挿入します。

<AssignMessage name="set-payload-3">
      <Set>
        <Payload contentType="application/json">
          {"name":"foo", "type":"{variable_name}"}
        </Payload>
      </Set>
    </AssignMessage>
    

たとえば、Cloud リリース 16.08.17 より前などの古いバージョンの Apigee Edge では、JSON ペイロード内で中かっこを使用して変数参照を指定することはできませんでした。こうした以前のリリースでは、variablePrefixvariableSuffix の属性を使用して区切り文字を指定し、これらを使用して次のように変数名を囲む必要がありました。

<AssignMessage name="set-payload-3b">
      <Set>
        <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
          {"name":"foo", "type":"@variable_name#"}
        </Payload>
      </Set>
    </AssignMessage>
    

このような古い構文も引き続き機能します。

例 4

<Payload> のコンテンツがメッセージ テンプレートとして扱われます。このため、Assign Message ポリシーではランタイム時に中かっこで囲まれた変数が参照される変数の値に置き換えられます。

次の例は、中かっこの構文を使用してペイロードの一部を変数値に設定します。

<AssignMessage name="set-payload-4">
      <Set>
        <Payload contentType="text/xml">
          <root>
            <e1>sunday</e1>
            <e2>funday</e2>
            <e3>{var1}</e3>
          </root>
        </Payload>
      </Set>
    </AssignMessage>
    

次の表に、<Payload> の属性を示します。

属性 説明 要否
contentType

指定した場合、contentType の値が Content-Type HTTP ヘッダーに割り当てられます。

省略可 文字列
variablePrefix 必要に応じてフロー変数の先頭の区切り文字を指定します。デフォルトは「{」です。詳細については、フロー変数のリファレンスをご覧ください。 省略可 Char
variableSuffix 必要に応じてフロー変数の末尾の区切り文字を指定します。デフォルトは「}」です。詳細については、フロー変数のリファレンスをご覧ください。 省略可 Char

<QueryParams><Set> の子)

リクエストの既存のクエリ パラメータを新しい値で上書きします。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
<QueryParam> 要素の配列
親要素 <Set>
子要素 <QueryParam>

<QueryParams> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <QueryParams>
          <QueryParam name="queryparam_name">queryparam_value</QueryParam>
          ...
        </QueryParams>
      </Set>
    </AssignMessage>
    

例 1

次の例は、request.header.address 変数の値に「address」クエリ パラメータを設定します。

<AssignMessage continueOnError="false" enabled="true" name="set-queryparams-1">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.header.address}</QueryParam>
        </QueryParams>
      </Set>
    </AssignMessage>
    

<QueryParams> は、次の条件を満たす場合にのみ使用できます。

  • HTTP 動詞: GET
  • メッセージ タイプ: リクエスト

ポリシー(<Set><QueryParams/></Set>)に空のクエリ パラメータを定義した場合、そのポリシーはクエリ パラメータを設定しません。これは、<QueryParams> を省略した場合と同じ動作となります。

<ReasonPhrase><Set> の子)

レスポンスに理由句を設定します。これは通常、デバッグのために <StatusCode> と組み合わせて設定します。この要素はリクエストには作用しません。

デフォルト値 なし
要否 省略可
文字列
親要素 <Set>
子要素 なし

<ReasonPhrase> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
      </Set>
    </AssignMessage>
    

例 1

次の例は、単一の理由句を設定します。

<AssignMessage name="set-reasonphrase-1">
      <Set>
        <ReasonPhrase>Bad medicine</ReasonPhrase>
      </Set>
      <AssignTo createNew="true" transport="http" type="response"/>
    </AssignMessage>
    

例 2

<ReasonPhrase> のコンテンツがメッセージ テンプレートとして扱われます。このため、次の例に示すように、中かっこで囲まれた変数名がランタイム時に参照先変数の値に置き換えられます。

<AssignMessage name="set-reasonphrase-2">
      <Set>
        <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
      </Set>
      <AssignTo createNew="true" transport="http" type="response"/>
    </AssignMessage>
    

<ReasonPhrase> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: レスポンス

<StatusCode><Set> の子)

レスポンスにステータス コードを設定します。この要素はリクエストには作用しません。

デフォルト値 「200」(<AssignTo>createNew 属性が「true」の場合)
要否 省略可
文字列または variable
親要素 <Set>
子要素 なし

<StatusCode> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <StatusCode>HTTP_status_code or {variable}</StatusCode>
      </Set>
    </AssignMessage>
    

例 1

次の例は、単純なステータス コードを設定します。

<AssignMessage name="set-statuscode-1">
      <Set>
        <StatusCode>404</StatusCode>
      </Set>
      <AssignTo createNew="true" transport="http" type="response"/>
    </AssignMessage>
    

例 2

<StatusCode> のコンテンツがメッセージ テンプレートとして扱われます。このため、次の例に示すように、中かっこで囲まれた変数名がランタイム時に参照先変数の値に置き換えられます。

<AssignMessage name="set-statuscode-2">
      <Set>
        <StatusCode>{calloutresponse.status.code}</StatusCode>
      </Set>
      <AssignTo createNew="true" transport="http" type="response"/>
    </AssignMessage>
    

<StatusCode> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: レスポンス

<Verb><Set> の子)

リクエストに HTTP 動詞を設定します。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
文字列または variable
親要素 <Set>
子要素 なし

<Verb> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
      </Set>
    </AssignMessage>
    

例 1

次の例は、リクエストに単純な動詞を設定します。

<AssignMessage name="set-verb-1">
      <Set>
        <Verb>POST</Verb>
      </Set>
      <AssignTo createNew="true" transport="http" type="request"/>
    </AssignMessage>
    

例 2

<Verb> のコンテンツがメッセージ テンプレートとして扱われます。このため、中かっこで囲まれた変数名がランタイム時に参照先変数の値に置き換えられます。

次の例は、変数を使用して動詞を入力します。

<AssignMessage name="set-verb-2">
      <Set>
        <Verb>{my_variable}</Verb>
      </Set>
      <AssignTo createNew="true" transport="http" type="request"/>
    </AssignMessage>
    

<Verb> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: リクエスト

<Version><Set> の子)

リクエストに HTTP バージョンを設定します。この要素はレスポンスには作用しません。

デフォルト値 なし
要否 省略可
文字列または variable
親要素 <Set>
子要素 なし

<Version> 要素の構文は次のとおりです。

構文

    <AssignMessage
        continueOnError="[false|true]"
        enabled="[true|false]"
        name="policy_name" >
      <Set>
        <Version>[1.0|1.1|{variable}]</Verb>
      </Set>
    </AssignMessage>
    

例 1

次の例は、バージョン番号を「1.1」に設定します。

<AssignMessage name="set-version-1">
      <Set>
        <Version>1.1</Version>
      </Set>
      <AssignTo createNew="true" transport="http" type="request"/>
    </AssignMessage>
    

例 2

次の例は、中かっこで囲まれた変数を使用してバージョン番号を設定します。

<AssignMessage name="set-version-2">
      <Set>
        <Version>{my_version}</Version>
      </Set>
      <AssignTo createNew="true" transport="http" type="request"/>
    </AssignMessage>
    

<Version> のコンテンツがメッセージ テンプレートとして扱われます。このため、中かっこで囲まれた変数名がランタイム時に参照先変数の値に置き換えられます。

<Version> は、次の条件を満たす場合にのみ使用できます。

  • メッセージ タイプ: リクエスト

カスタム リクエスト メッセージを作成する

Assign Message を使用してカスタム リクエスト メッセージを作成できます。作成したカスタム リクエストは、以下の方法で使用できます。

  • 他のポリシーでその変数にアクセスする
  • 外部サービスに渡す

カスタム リクエスト メッセージを作成するには、Assign Message ポリシーに <AssignTo> 要素を使用します。次の例に示すように、createNew を「true」に設定し、要素の本文で新しいメッセージの名前を指定します。

<AssignMessage name="assignto-2">
      <AssignTo createNew="true" transport="http" type="request"/>
    </AssignMessage>

デフォルトの場合、Edge はカスタム リクエスト メッセージに対して何も行いません。作成後も Edge は元のリクエストでフローを続行します。カスタム リクエストを使用するには、カスタム リクエストを外部サービスに渡せるようにする ServiceCallout ポリシーなどのポリシーをプロキシに追加します。

次の例は、カスタム リクエスト メッセージを作成します。

例 1

次の例は、Assign Message を使用してカスタム リクエスト オブジェクトを作成します。

<AssignMessage name="AssignMessage-3">
      <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
      <Copy>
        <Headers>
         <Header name="user-agent"/>
        </Headers>
      </Copy>
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.addy}</QueryParam>
        </QueryParams>
        <Verb>GET</Verb>
      </Set>
      <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </AssignMessage>
    

この例は、以下のように実行されます。

  • 「MyCustomRequest」という新しいリクエスト メッセージ オブジェクトを作成します。
  • MyCustomRequest では、このポリシーは次の処理を行います。
    • 受信リクエストの user-agent HTTP ヘッダーの値を新しいメッセージにコピーします。<Copy> では user-agent フロー変数に対する絶対参照が使用されるため、<Copy>source 属性を指定する必要はありません。
    • カスタム メッセージの address クエリ パラメータを受信リクエストの addy クエリ パラメータの値に設定します。
    • HTTP 動詞を GET に設定します。
  • <IgnoreUnresolvedVariables> を「false」に設定します。<IgnoreUnresolvedVariables> が「false」のときにポリシーで追加しようとする変数のいずれかが存在しない場合、Edge は API フローの処理を停止します。

例 2

次は、Assign Message を使用してカスタム リクエスト オブジェクトを作成する方法を示すもう一つの例です。

<AssignMessage name="AssignMessage-2">
      <AssignTo createNew="true" type="request">partner.request</AssignTo>
      <Set>
        <Verb>POST</Verb>
        <Payload contentType="text/xml">
          <request><operation>105</operation></request>
        </Payload>
      </Set>
    </AssignMessage>
    

この例は、「partner request」という新しいカスタム リクエストを作成します。次に、新しいリクエストの <Verb><Payload> を設定します。

カスタム リクエスト メッセージには、フローの後続部分で出現する別の Assign Message ポリシーでアクセスできます。次の例は、カスタム リクエスト メッセージの user-agent ヘッダーの値を取得します。

<AssignMessage name="custom-request-1-access">
      <DisplayName>custom-request-1-access</DisplayName>
      <AssignTo createNew="false" type="request"></AssignTo>
      <Set>
        <Headers>
          <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header>
        </Headers>
      </Set>
    </AssignMessage>
    

動画

Assign Message ポリシーの詳細については、次の動画をご覧ください。

動画 説明
Assign Message ポリシーを使用する理由 Assign Message ポリシーを使用することで、バックエンド コードを変更せずに API リクエストやレスポンスを変更するメリットについて学びます。
Assign Message ポリシーを使用して API 要素をコピーする Assign Message ポリシーを使用して、API リクエストやレスポンスから要素をコピーして新しいリクエスト / レスポンス オブジェクトを構築します。
Assign Message ポリシーを使用して API 要素を削除する Assign Message ポリシーを使用して、ターゲット バックエンドに到達する前に API 要素を削除して API を変更します。
Assign Message ポリシーを使用して API 要素を追加して設定する Assign Message ポリシーを使用して、クエリ パラメータ、ヘッダー、フォーム パラメータ、ペイロードを追加して、API リクエストやレスポンスを変更します。
Assign Message ポリシーを使用してカスタム変数を作成する Assign Message ポリシーを使用してカスタムフロー変数を設定し、API プロキシ内の他のポリシーでその変数を利用します。
Assign Message ポリシーを使用して新しいリクエスト / レスポンス オブジェクトを作成する API のランタイム時に Assign Message ポリシーを使用して新しい API リクエスト / レスポンス オブジェクトを作成します。
Assign Message ポリシーを使用して擬似 API を作成する レスポンス フローに Assign Message ポリシーを追加して、単純な疑似 REST API を作成します。
Assign Message ポリシーを使用してペイロードを設定、変更する API のランタイム時に Assign Message ポリシーを使用して SOAP ペイロードを設定し、REST リクエストを SOAP リクエストに変換します。

エラーコード

このセクションでは、このポリシーによってエラーが発生したときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。この情報は、障害に対処するための障害ルールを作成するうえで重要です。詳しくは、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

実行時のエラー

これらのエラーは、ポリシーの実行時に発生する可能性があります。

障害コード HTTP ステータス 原因 修正
steps.assignmessage.SetVariableFailed 500 ポリシーで変数を設定できませんでした。未解決の変数の名前については、障害文字列を参照してください。
steps.assignmessage.VariableOfNonMsgType 500

このエラーは、<Copy> 要素の source 属性がメッセージ型以外の変数に設定されている場合に発生します。

メッセージ型の変数は、いずれも HTTP リクエストまたはレスポンス全体を代表するものです。組み込み Edge フロー変数 requestresponsemessage はメッセージ型です。メッセージ変数の詳細については、変数リファレンスをご覧ください。

build
steps.assignmessage.UnresolvedVariable 500

このエラーは、Assign Message ポリシーで指定された変数が次のいずれかである場合に発生します。

  • 範囲外(ポリシーが実行されている特定のフローで使用できない)
  • または
  • 解決できない(定義されていない)
build

デプロイエラー

これらのエラーは、このポリシーを含むプロキシをデプロイするときに発生する可能性があります。

エラー名 原因 修正
InvalidIndex Assign Message ポリシーの <Copy> または <Remove> 要素に指定されたインデックスが 0 か負の数の場合、API プロキシのデプロイに失敗します。 build
InvalidVariableName 子要素 <Name> が空か、<AssignVariable> 要素で指定されていない場合、値を割り当てる有効な変数名が存在しないため、API プロキシのデプロイに失敗します。有効な変数名が必要です。 build
InvalidPayload ポリシーで指定されたペイロードが無効です。

障害変数

以下の変数は、実行時にこのポリシーによりエラーが発生したときに設定されます。詳しくは、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明
fault.name="fault_name" fault_name は、前述の実行時のエラーの表にリストアップされている障害名です。障害名は、障害コードの最後の部分です。 fault.name Matches "UnresolvedVariable"
assignmessage.policy_name.failed policy_name は、障害をスローしたポリシーの、ユーザーが指定した名前です。 assignmessage.AM-SetResponse.failed = true

エラー レスポンスの例

    {
       "fault":{
          "detail":{
             "errorcode":"steps.assignmessage.VariableOfNonMsgType"
          },
          "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message"
       }
    }
    

障害ルールの例

    <faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Assign Message Faults">
        <Step>
            <Name>AM-CustomNonMessageTypeErrorResponse</Name>
            <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
        </Step>
        <Step>
            <Name>AM-CustomSetVariableErrorResponse</Name>
            <Condition>(fault.name = "SetVariableFailed")</Condition>
        </Step>
        <Condition>(assignmessage.failed = true) </Condition>
    </FaultRule>
    

スキーマ

各ポリシータイプは XML スキーマ(.xsd)によって定義されます。GitHub に参照用のポリシー スキーマが用意されています。

関連トピック

API Platform サンプルで、AssignMessage ポリシーの作業サンプルをご利用いただけます。

ProxyEndpoint からの target.url をオーバーライドする方法の高度な例については、こちらの Apigee コミュニティの記事をご覧ください。

ServiceCallout ポリシーで実行中の「set path」を確認するには、Apigee GitHub で実際にやってみて学ぶの例をご覧ください。リポジトリのクローンを作成し、トピックの手順に沿ってください。この例では、Assign Message を使用してリクエストのパスを設定してから、Service Callout ポリシーを使用して外部サービスへのリクエストを行います。