AssignMessage ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

ポリシーアイコン

What

AssignMessage ポリシーでは、API プロキシのフローの中で、既存のリクエストやレスポンスのメッセージの変更や、新しいリクエストやレスポンスのメッセージの作成を行うことができます。このポリシーを使用すると、そのようなメッセージに対して以下の操作を実行できます。

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

AssignMessage では、メッセージに適用される上記のオペレーションのいずれとも無関係に、任意のコンテキスト変数を設定することもできます。

AssignMessage では、リクエストとレスポンスいずれかのプロパティの追加、変更、削除ができます。カスタムリクエストメッセージを作成するで説明されているように、代わりに AssignMessage を使用してカスタムのリクエストメッセージやレスポンスメッセージを作成し、別のターゲットに渡すことができます。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

ユースケース

Apigee による処理中にリクエストやレスポンスのメッセージの変更が必要になる状況はよくあります。次に例を示します。

クエリ文字列パラメータや他の型の入力のデフォルト値を定義する。
メッセージをバックエンドサービスに転送する前に、リクエストメッセージから HTTP ヘッダーを削除する。
レスポンスをユーザーアプリに送信する前に HTTP ヘッダーを追加する。
レスポンスの送信前に JSON または XML メッセージコンテンツを挿入する。
完全なリクエストやレスポンスのメッセージを生成する。たとえば、ServiceCallout ポリシーを使用して、API プロキシからリモート API を呼び出す場合などが考えられます。この場合、まず AssignMessage ポリシーを使用して作成したカスタムリクエストメッセージを変数に割り当て、そのメッセージを ServiceCallout を使用してリモート API に送信します。
デバッグやトラブルシューティングのためにリクエストとレスポンスにヘッダーを追加する。

動画

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

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

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

<Add> 要素、<Copy> 要素、<Set> 要素、<Remove> 要素を整理する順序が重要です。このポリシーでは、ポリシー構成に出現する順序でこれらのアクションを実行します。すべてのヘッダーを削除してから特定のヘッダーを設定する必要がある場合は、<Set> 要素の前に <Remove> 要素を含める必要があります。

`<AssignMessage>` 要素

AssignMessage ポリシーを定義します。

デフォルト値	下の「デフォルトポリシー」タブをご覧ください。
必須かどうか	必須
型	複合オブジェクト
親要素	なし
子要素	`<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>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>

  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</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>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>

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

  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</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>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>

</AssignMessage>

デフォルトポリシー

次の例は、Apigee UI のフローに AssignMessage ポリシーを追加する場合のデフォルトの設定を示しています。

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <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>

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

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

属性	デフォルト	必須かどうか	説明
`name`	なし	必須	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
`continueOnError`	false	省略可	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`enabled`	true	省略可	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。
`async`	false	非推奨	この属性は非推奨となりました。

次の表は、<AssignMessage> の子要素の概要をまとめたものです。

子要素	必須かどうか	説明
一般的な操作
`<Add>`	省略可	`<AssignTo>` 要素で指定されたメッセージオブジェクトに情報を追加します。 `<Add>` は、元のメッセージに存在しないヘッダーまたはパラメータをメッセージに追加します。なお、`<Set>` にもこの機能があります。既存のヘッダーまたはパラメータを上書きするには、`<Set>` 要素を使用します。
`<Copy>`	省略可	`source` 属性で指定されたメッセージから、`<AssignTo>` 要素で指定されたメッセージオブジェクトに情報をコピーします。
`<Remove>`	省略可	`<AssignTo>` 要素で指定されたメッセージ変数から指定された要素を削除します。
`<Set>`	省略可	`<AssignTo>` 要素で指定された、リクエストやレスポンスの既存のプロパティ値を置き換えます。 `<Set>` は、元のメッセージにすでに存在するヘッダーまたはパラメータを上書きします。存在しない場合は、新たに追加します。
その他の子要素
`<AssignTo>`	省略可	AssignMessage ポリシーで操作するメッセージを指定します。これは、標準のリクエストやレスポンスでも、新しいカスタムメッセージでもかまいません。
`<AssignVariable>`	省略可	フロー変数に値を割り当てます。変数が存在しない場合は、`<AssignVariable>` によって変数が作成されます。
`<IgnoreUnresolvedVariables>`	省略可	未解決の変数を検出したときに処理を停止するかどうかを決定します。

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

例

次の例では、AssignMessage ポリシーの使用方法を示しています。

1: ヘッダーを追加する

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

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

この例では、<AssignTo> 要素の変数名として response が指定されているため、このポリシーによりターゲットサーバーから返されたデータで最初に設定されたレスポンスオブジェクトが変更されます。

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

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

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

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

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

<AssignMessage name="AM-set-dynamic-content">
  <AssignTo>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>

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

また、中かっこも変数の挿入に使用できます。

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

次の例では、リクエストから apikey クエリパラメータが削除されます。

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

次の例では、3 つの AssignMessage ポリシーが使用されています。

リクエストに 3 つのフロー変数を作成し、静的な値を割り当てます。
リクエストフローの 2 番目のポリシーでフロー変数を動的に取得します。
レスポンスのペイロードでこれらの変数を設定します。

<!-- Policy #1: Set variables in the request -->
<AssignMessage name="AM-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>
</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 と #2 をリクエストフローに追加します。ポリシー #1 はポリシー #2 の前に配置します。
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 に設定してください。

次の例のように、リクエストを 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: ServiceCallout のレスポンスヘッダーを取得する

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

<AssignMessage name="AM-Payload-from-SC-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

すべてのヘッダー値を一覧表示するには、代わりに次の変数を使用します。

{calloutResponse.header.Set-Cookie.values}

8: フォームパラメータ、ヘッダー、クエリパラメータを保存および削除する

<Remove> を使用してヘッダー、クエリパラメータ、またはフォームパラメータを削除する必要があるものの、ポリシーフローの後の部分でそれらの値へのアクセスを保持する必要がある場合は、<AssignVariable> を使用して値を保存できます。

<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-StoreAndRemove">
  <DisplayName>AM-StoreAndRemove</DisplayName>
  <AssignVariable>
    <Name>var_grant_type</Name>
    <Ref>request.formparam.grant_type</Ref>
  </AssignVariable>
  <Remove>
    <Headers/>
    <FormParams/>
    <Payload/>
  </Remove>
  <Set>
    <Headers>
      <Header name="Content-Type">application/x-www-form-urlencoded</Header>
      <Header name="Accept">application/json</Header>
      <Header name="Grant-Type">{var_grant_type}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

注: Assign Message ポリシーで <Remove> を使用して削除されたフォームパラメータ、ヘッダー、クエリパラメータには、この例で説明されているように、値が変数に保存されている場合を除き、ポリシーフローの完了後にアクセスすることはできません。

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

子要素のリファレンス

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

`<Add>`

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

<Add> 要素によって、元のメッセージに存在しない新しいプロパティがメッセージに追加されます。なお、<Set> にもこの機能があります。既存のプロパティの値を変更する場合は、<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 name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 2

次の例では、<Headers> 要素を使用して、ターゲットエンドポイントに送信されるリクエストに partner-id ヘッダーが追加されています。

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 3

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

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

この例では、リクエストのプリフローで <Add> が使用されています。デバッグの概要などのツールで結果を確認すると、https://example-target.com/get へのリクエストは https://example-target.com/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 name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 2

次の例では、name クエリパラメータの値が取得されてフォームパラメータとしてリクエストに追加され、クエリパラメータが削除されています。

<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>

この例では <AssignTo> でターゲットが指定されていません。このポリシーは、パラメータをそのリクエストのみに追加します。

例 3

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

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

この例では、元のリクエストからクエリ文字列パラメータが取得され、別の名前のフォームパラメータとして追加されます。次に、元のクエリパラメータが削除されます。 Apigee により、変更されたリクエストがターゲットエンドポイントに送信されます。

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

username=nick&zip_code=90210&default_language=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> を追加すると、メッセージのターゲットサービスへの送信前に Apigee によってリクエストの 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

次の例では、partner-id ヘッダーがリクエストメッセージに追加され、そのヘッダーに verifyapikey.VAK-1.developer.app.partner-id フロー変数の値が割り当てられます。

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</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 name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

HTTP 動詞: GET、POST、PATCH、DELETE
メッセージタイプ: リクエスト

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

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

`<AssignTo>`

AssignMessage ポリシーで操作するオブジェクトを決定します。次から選択します。

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

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

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<AssignMessage>`
子要素	なし

<AssignTo> を指定しないか、<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

次の例では、<AssignTo> のテキストでメッセージが指定されていません。これは、ポリシーの実行場所に応じてポリシーが request メッセージまたは response メッセージのいずれかで動作することを意味します。

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

createNew="false" を指定していて、メッセージ名を明示的に指定しない場合、<AssignTo> の他の属性は無関係です。この場合、<AssignTo> 要素を完全に省略することもできます。

例 2

次の例では、既存のオブジェクトが上書きされて、新しいリクエストオブジェクトが作成されます。

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

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

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

例 3

次の例では、MyRequestObject という名前の新しいリクエストオブジェクトが作成されています。

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

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

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

属性説明必須かどうか種類

属性	説明	必須かどうか	種類
`createNew`	値を割り当てるときに、このポリシーによって新しいメッセージが作成されるかどうかを決定します。 `true` の場合、ポリシーは `type` で指定された型（`request` または `response`）の新しい変数を作成します。新しい変数の名前を指定しない場合、ポリシーは `type` の値に応じて新しいリクエストまたはレスポンスオブジェクトを作成します。注意: 新しいリクエストオブジェクトまたはレスポンスオブジェクトを作成すると、既存のリクエストオブジェクトまたはレスポンスオブジェクトが削除され、新しいものに置き換えられます。このため、オブジェクト内のすべての情報が失われることになります。 `false` の場合、ポリシーは次のいずれかの方法で対応します。 `<AssignTo>` で変数名をリクエストまたはレスポンスに解決できる場合は、処理が続行されます。たとえば、ポリシーがリクエストフロー内にある場合、変数はリクエストオブジェクトです。ポリシーがレスポンス内にある場合、変数はレスポンスオブジェクトです。 `<AssignTo>` を解決できない場合、またはメッセージ以外のタイプに解決される場合は、エラーがスローされます。 `createNew` の指定がない場合、このポリシーは次のいずれかの処理を行います。 `<AssignTo>` がメッセージに解決される場合は、次のステップに進みます。 `<AssignTo>` を解決できない場合、またはメッセージ以外のタイプに解決された場合は、`type` で指定されたタイプの新しい変数が作成されます。	省略可	ブール値
`transport`	リクエストまたはレスポンスのメッセージタイプにトランスポートタイプを指定します。デフォルト値は `http`（サポートされる唯一の値）です。	省略可	文字列
`type`	`createNew` が `true` の場合、新しいメッセージのタイプを指定します。有効な値は `request` または `response` です。デフォルト値は `request` です。この属性を省略すると、Apigee ではこのポリシーが実行されるフロー内の場所に応じて、リクエストまたはレスポンスが作成されます。	省略可	文字列

createNew

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

true の場合、ポリシーは type で指定された型（request または response）の新しい変数を作成します。新しい変数の名前を指定しない場合、ポリシーは type の値に応じて新しいリクエストまたはレスポンスオブジェクトを作成します。

false の場合、ポリシーは次のいずれかの方法で対応します。

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

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

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

省略可

ブール値

transport

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

デフォルト値は http（サポートされる唯一の値）です。

省略可

文字列

type

createNew が true の場合、新しいメッセージのタイプを指定します。有効な値は request または response です。

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

省略可

文字列

`<AssignVariable>`

宛先フロー変数（AssignMessage ポリシーによって値が設定される変数など）に値を割り当てます。フロー変数が存在しない場合は、<AssignVariable> によって作成されます。AssignMessage ポリシー内では複数の AssignVariable 要素を使用できます。これらは、ポリシー構成に記述されている順序で実行されます。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<AssignMessage>`
子要素	`<Name>` （必須） `<PropertySetRef>` `<Ref>` `<ResourceURL>` `<Template>` `<Value>`

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

リテラル文字列: <Value> 子要素を使用して、宛先フロー変数にリテラル文字列値を指定します。
フロー変数: <Ref> 子要素を使用して宛先フロー変数に既存のフロー変数の値を指定します。参照元として使用できるフロー変数の完全なリストについては、フロー変数リファレンスをご覧ください。
プロパティセット: <PropertySetRef> 子要素を使用して、プロパティセットの名前 / 鍵ペアから値を取得して、フロー変数に格納します。プロパティセットには動的にアクセスできます。
リソース URL: <ResourceURL> 子要素を使用して、タイプが XSL、XSD、WSDL、JavaScript、OpenAPI Spec のテキストリソースの URL を指定します。これにより、リソースの内容を名前付きフロー変数に割り当てます。
メッセージテンプレート: <Template> 子要素を使用して、宛先フロー変数にメッセージテンプレートを指定します。

これらの子要素の優先順位は、ResourceURL、Template、Ref、Value、PropertySetRef の順です。

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

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

例 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>

どちらかの割り当てが失敗すると、代わりに値 ErrorOnCopy が宛先フロー変数に割り当てられます。

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

例 3

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

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

例 4

次の例では、<AssignVariable> を使用して、プロキシリクエストからターゲットリクエストにパス接尾辞が伝播されるというデフォルトの動作が無効にされています。

<AssignMessage name='AM-PathSuffixFalse'>
  <AssignVariable>
    <Name>target.copy.pathsuffix</Name>
    <Value>false</Value>
  </AssignVariable>
</AssignMessage>

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

`<Name>`（`<AssignVariable>` の子）

宛先フロー変数（AssignMessage ポリシーによって値が設定される変数など）の名前を指定します。<Name> で指定された変数が存在しない場合は、ポリシーによってその名前の変数が作成されます。

デフォルト値	なし
必須かどうか	必須
型	文字列
親要素	`<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> によって作成されます。

注: ratelimit という名前は予約されています。詳細については、Apigee コミュニティの Quota Policy Throws NullPointerException をご覧ください。

`<PropertySetRef>`（`<AssignVariable>` の子）

この要素を使用すると、プロパティセットの名前 / 鍵ペアの値を動的に取得できます。プロパティセットの詳細については、プロパティセットの使用をご覧ください。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<AssignVariable>`
子要素	なし

プロパティセットは名前 / 鍵ペアで構成されます。たとえば、propset1.id=12345 のような形式です。ここで、propset1 はプロパティセットの名前、id は鍵、12345 は鍵の値です。

PropertySetRef 子要素を使用すると、プロパティセットの名前や鍵を動的に選択できます。1 つのプロパティセットのファイルに 200 個のルーティングルールがあるとします。プロパティセットのルールには、次のようにアクセスできます。ここで、routingrules はプロパティセット名で、rule1、rule2、rulen はキーです。

propertyset.routingrules.rule1
propertyset.routingrules.rule2
propertyset.routingrules.rulen

API プロキシフローでこれらのプロパティにアクセスするには、選択するルールを設計時に確認しておく必要があります。ただし、ルール名はリクエストヘッダーまたはペイロードに含まれているものとします。ルールを選択する 1 つの方法は、次のようなコードで JavaScript ポリシーを使用することです。

context.getVariables("propertyset.routingrules." + ruleName); //assuming ruleName was populated earlier.

一方、AssignMessage の PropertySetRef 機能を使用すると、JavaScript を導入しなくてもプロパティキーを動的に選択できます。

<PropertySetRef> 要素では、フロー変数とリテラル文字列値を組み合わせて使用できます。詳細については、例をご覧ください。

注: この機能を使用する場合は、propertyset.PROPNAME.KEY のように、接頭辞 propertyset を使用してプロパティセットを参照しないでください。接頭辞 propertyset は想定されています。

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
  </AssignVariable>
</AssignMessage>

例 1

この例では、プロパティセットキーからフロー変数に値が割り当てられます。この場合、プロパティセット名はヘッダー propset_name から取得され、キーはヘッダー propset_key で指定され、キーに割り当てられた値は変数 flow_variable に保存されます。

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.{request.header.propset_key}</PropertySetRef>
  </AssignVariable>
</AssignMessage>

<PropertySetRef> 要素では、フロー変数とリテラル文字列の組み合わせを使用できます。

例 2

この例では、固定キー名（リテラル文字列）を使用して、プロパティセットキーの値がフロー変数に割り当てられます。この場合、プロパティセット名がヘッダー propset_name から取得されます。キーはリテラル文字列 key1 で、キーに割り当てられた値が変数 flow_variable に保存されます。

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.key1</PropertySetRef>
  </AssignVariable>
</AssignMessage>

<PropertySetRef> 要素では、フロー変数とリテラル文字列の組み合わせを使用できます。

`<Ref>`（`<AssignVariable>` の子）

アサインメントの参照元をフロー変数として指定します。フロー変数は、あらかじめ定義されたフロー変数（フロー変数リファレンスに存在するもの）か、ユーザーが作成したカスタムフロー変数のいずれかを使用できます。

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

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<AssignVariable>`
子要素	なし

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

  DO specify the variable name without brackets:
  <Ref>client.host</Ref>

  DO NOT use brackets:
  <Ref>{client.host}</Ref>

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

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

例 2

<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、読み取りできない、または不正な形式の場合、Apigee によって値 ErrorOnCopy が新しい変数に割り当てられます。

例 3

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

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

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

<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 プロキシから有効な結果が返されることになります。

<Ref> の値は、request、response、target のオブジェクトのプロパティやカスタムフロー変数の名前など、フロー変数でなければなりません。

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

`<ResourceURL>`（`<AssignVariable>` の子）

変数の割り当ての参照元としてテキストリソースの URL を指定します。Apigee は、<Name> で指定されたフロー変数を、参照先のリソースの内容とともに読み込みます。リソースには、XSD、XSL、WSDL、JavaScript、プロパティセット、OpenAPI 仕様のタイプが使用できます。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<AssignVariable>`
子要素	なし

<ResourceURL> によって指定されたリソースが存在しない場合は、<IgnoreUnresolvedVariables> の値が true であれば、Apigee によって値 null が宛先フロー変数に割り当てられます。<IgnoreUnresolvedVariables> の値が false であれば、Apigee はエラーをスローします。

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
  </AssignVariable>
</AssignMessage>

テキスト値は文字列値を取り、メッセージテンプレートとして解釈されます。次のいずれかが有効です。

<ResourceURL>jsc://my-js-file.js</ResourceURL>
<ResourceURL>wsdl://{variable-goes-here}</ResourceURL>
<ResourceURL>{variable-goes-here}</ResourceURL>

例 1

次の例では、jsc フォルダのプロキシ、フロー変数 assigned-variable に読み込まれた JSON リソースの値が割り当てられます。

<AssignMessage name='AM-From-ResourceURL-Proxy-JSC'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>jsc://settings.json</ResourceURL>
  </AssignVariable>
</AssignMessage>

例 2

次の例では、oas フォルダ内のプロキシに読み込まれた OpenAPI 仕様リソースの値が、フロー変数 assigned-variable に割り当てられ、その値がレスポンス本文の Payload として設定されます。

<AssignMessage name='AM-Response'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>oas://Fulfillment.yaml</ResourceURL>
  </AssignVariable>
  <Set>
    <Payload contentType='application/yaml'>{assigned-variable}</Payload>
  </Set>
</AssignMessage>

`<Template>`（`<AssignVariable>` の子）

メッセージテンプレートを指定します。メッセージテンプレートを使用すると、ポリシーの実行時に変数内の文字列を置き換え、中かっこで囲まれた変数名とリテラル文字列を組み合わせることができます。また、メッセージテンプレートは、エスケープ文字や大文字小文字の変換を行う関数にも対応しています。

ref 属性を使用して、変数の値がメッセージテンプレートであるフロー変数を指定します。たとえば、デベロッパーアプリのカスタム属性としてメッセージテンプレートを格納できます。Apigee が API キーまたはセキュリティトークンを検証した後（追加のポリシーを通じて）、デベロッパーアプリの識別を行うときに、<AssignVariable> 要素はアプリのカスタム属性のメッセージテンプレートを使用できます。このメッセージテンプレートは、セキュリティポリシーのフロー変数として利用できます。次の例では、API 呼び出しを行うデベロッパーアプリの message_template と呼ばれるカスタム属性でメッセージテンプレートが使用可能であることを前提としています。ここで、VerifyAPIKey ポリシーは、アプリの API キーの検証に使用されたポリシーです。

<Template ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<AssignVariable>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
  </AssignVariable>
</AssignMessage>

例 1

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

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

例 2

次の例では、あらかじめ定義されたメッセージテンプレートを値とするフロー変数が指定されています。このオプションは、ポリシーを変更せずに、あらかじめ定義されたテンプレートを実行時に挿入する場合に使用します。

<AssignMessage name='AV-via-template-indirectly'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>
  </AssignVariable>
</AssignMessage>

例 3

次の例では、フロー変数とテキスト値が指定されています。この場合、参照される変数が null でない場合、その値がテンプレートとして使用されます。参照される値が null の場合、テキスト値（この場合は {system.uuid}-{messageid}）がテンプレートとして使用されます。このパターンは override 値を指定する場合に便利です。特に、デフォルトのテンプレート（テキスト部分）を動的に設定された値でオーバーライドする場合に便利です。たとえば、条件文で Key-Value マップから値を取得し、参照される変数をその値に設定できます。

<AssignMessage name='AV-template-with-fallback'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Template ref='my_variable'>{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> でターゲットを指定しない場合は、このポリシーが実行されるフロー内の場所に応じて、ポリシーはリクエストかレスポンスに値をコピーします。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<AssignMessage>`
子要素	`<FormParams>` `<Headers>` `<Path>` `<Payload>` `<QueryParams>` `<StatusCode>` `<Verb>` `<Version>`

<Copy> 要素の下に子要素を指定しない場合、指定されたソースメッセージのすべての部分がコピーされます。

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
    <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</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>
    <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 つのフォームパラメータ、パス、すべてのクエリパラメータが、request メッセージから newRequest と言う名前の新しいカスタムリクエストにコピーされます。

<AssignMessage name="AM-copy-1">
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1"/>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1"/>
      <FormParam name="Form_Param_Name_2"/>
      <FormParam name="Form_Param_Name_3"/>
    </FormParams>
    <Path>true</Path>
    <QueryParams/>
  </Copy>
</AssignMessage>

<Payload> や <Verb> などの要素が存在しないため、ポリシーはメッセージのこれらの部分をコピーしません。

例 2

次の例では、まず既存の response メッセージからすべてが削除され、次にすべての値が secondResponse という別のメッセージから response メッセージにコピーされます。

<AssignMessage name='AM-Copy-Response'>
  <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>

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

属性説明必須かどうか種類

ソース

属性	説明	必須かどうか	種類
ソース	コピー元のオブジェクトを指定します。 `source` が指定されていない場合は、デフォルトで `message` に設定されます。この値は、ポリシーが実行されるフローによって異なります。ポリシーがリクエストフロー内で実行される場合、`message` 変数は `request` オブジェクトを参照します。ポリシーがレスポンスフロー内で実行される場合、`message` 変数は `response` オブジェクトを参照します。 `source` 属性で指定された変数が解決できない場合、またはメッセージ以外のタイプに解決される場合、`<Copy>` は無効になります。 `source` に指定する値は、デフォルトの宛先メッセージであるか、`<AssignTo>` で明示的に指定された宛先であるかにかかわらず、宛先メッセージとは異なります。`source` が宛先メッセージと同じ場合、`<Copy>` の効果はなくなります。	省略可	文字列

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

source が指定されていない場合は、デフォルトで message に設定されます。この値は、ポリシーが実行されるフローによって異なります。ポリシーがリクエストフロー内で実行される場合、message 変数は request オブジェクトを参照します。ポリシーがレスポンスフロー内で実行される場合、message 変数は response オブジェクトを参照します。
source 属性で指定された変数が解決できない場合、またはメッセージ以外のタイプに解決される場合、<Copy> は無効になります。
source に指定する値は、デフォルトの宛先メッセージであるか、<AssignTo> で明示的に指定された宛先であるかにかかわらず、宛先メッセージとは異なります。source が宛先メッセージと同じ場合、<Copy> の効果はなくなります。

省略可

文字列

`<FormParams>`（`<Copy>` の子）

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

デフォルト値	なし
必須かどうか	省略可
型	`<FormParam>` 要素の配列または空の配列
親要素	`<Copy>`
子要素	`<FormParam>`

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- 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 属性で指定されたリクエストまたはレスポンスのメッセージから、<AssignTo> 要素で指定されたリクエストまたはレスポンスのメッセージへ、HTTP ヘッダーをコピーします。

デフォルト値	なし
必須かどうか	省略可
型	`<Header>` 要素の配列または空の配列
親要素	`<Copy>`
子要素	`<Header>`

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

例 1

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

<AssignMessage name="AM-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> 要素で指定されたリクエストメッセージにパスをコピーします。

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	`<Copy>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

例 1

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

<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> 要素によって指定されたメッセージにペイロードをコピーします。

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	`<Copy>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

例 1

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

<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

`<QueryParams>`（`<Copy>` の子）

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

デフォルト値	なし
必須かどうか	省略可
型	`<QueryParam>` 要素の配列または空の配列
親要素	`<QueryParam>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- 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、POST、PATCH、DELETE
メッセージタイプ: リクエスト

`<StatusCode>`（`<Copy>` の子）

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

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

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	`<Copy>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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> を使用できるのは、コピー元とコピー先のメッセージの種類が「Response」の場合のみです。

<StatusCode> の一般的な用途は、プロキシレスポンスのステータスコードをターゲットから受信した値とは異なる値に設定することです。

`<Verb>`（`<Copy>` の子）

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

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

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	`<Copy>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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> 要素で指定されたオブジェクトにコピーします。

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	`<Copy>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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> 要素はすべてのポリシーに共通です。

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

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

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

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

`<IgnoreUnresolvedVariables>`

未解決の変数を検出したときに処理を停止するかどうかを決定します。

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	`<AssignMessage>`
子要素	なし

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

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

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

構文

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

例 1

次の例では、<IgnoreUnresolvedVariables> が true に設定されます。

<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

<IgnoreUnresolvedVariables> が true に設定されているため、possibly-defined-variable 変数が定義されていない場合、このポリシーはエラーをスローしません。

`<Remove>`

ヘッダー、クエリパラメータ、フォームパラメータ、メッセージペイロードをメッセージから削除します。<Remove> タグが空の場合、メッセージからすべてが削除されます。

影響を受けるメッセージはリクエストまたはレスポンスであることが考えられます。<AssignTo> 要素を使用して、<Remove> の操作対象のメッセージを指定します。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<AssignMessage>`
子要素	`<FormParams>` `<Headers>` `<Payload>` `<QueryParams>`

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

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

例 1

次の例では、レスポンスからメッセージの本文が削除されます。

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

例 2

次の例では、request オブジェクトからすべてのフォームパラメータとクエリパラメータが削除されます。

<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 3

次の例では、メッセージオブジェクトからすべてが削除されます。

<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>

これは通常、<Set> 要素または <Copy> 要素を使用して一部の置換値をメッセージに設定する場合にのみ行います。

`<FormParams>`（`<Remove>` の子）

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

デフォルト値	なし
必須かどうか	省略可
型	`<FormParam>` 要素の配列または空の配列
親要素	`<Remove>`
子要素	`<FormParam>`

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

例 1

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

<AssignMessage name="AM-remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 2

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

<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 3

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

<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</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" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

例 1

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

<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 2

次の例では、リクエストからすべてのヘッダーが削除されます。

<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 3

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

<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

`<Payload>`（`<Remove>` の子）

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

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	`<Remove>`
子要素	なし

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

例 1

次の例では、<Payload> が true に設定され、リクエストのペイロードがクリアされます。

<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

`<QueryParams>`（`<Remove>` の子）

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

デフォルト値	なし
必須かどうか	省略可
型	`<QueryParam>` 要素の配列または空の配列
親要素	`<Remove>`
子要素	`<QueryParam>`

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

構文

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

例 1

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

<AssignMessage name="AM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 2

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

<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 3

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

<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

例 4

次の例では、リクエストから apikey クエリパラメータが削除されます。

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

HTTP 動詞: GET、POST、PATCH、DELETE
メッセージタイプ: リクエスト

`<Set>`

<AssignTo> 要素で指定されたリクエストまたはレスポンスメッセージに情報を設定します。<Set> は、元のメッセージにすでに存在するヘッダー、クエリ、フォームパラメータを上書きします。存在しない場合は、新しいパラメータを追加します。

HTTP メッセージのヘッダー、クエリパラメータ、フォームパラメータは複数の値を保持できます。ヘッダーまたはパラメータに値を追加するには、代わりに <Add> 要素を使用します。

デフォルト値	なし
必須かどうか	省略可
型	複合型
親要素	`<AssignMessage>`
子要素	`<FormParams>` `<Headers>` `<Payload>` `<Path>` `<QueryParams>` `<StatusCode>` `<Verb>` `<Version>`

注: <Set> のサブ要素では、メッセージテンプレートと呼ばれる動的文字列置換機能がサポートされます。

<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>
    <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

次の例では、特定のヘッダーが設定されます。このポリシーがリクエストフローに接続されている場合、アップストリームシステムは元のインバウンドリクエストに含まれていない追加のヘッダーを受信できます。

<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 2

次の例では、レスポンスのペイロードと Content-Type ヘッダーが上書きされます。

<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</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

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

<AssignMessage name="AM-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

次の例では、x-ratelimit-remaining ヘッダーが ratelimit.Quota-1.available.count 変数の値に設定されています。

<AssignMessage name="AM-Set-RateLimit-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

ポリシーで空のヘッダー（<Set><Headers/></Set>）を定義した場合、このポリシーではヘッダーが設定されません。これは、<Headers> を省略した場合と同じ効果があります。

`<Path>`（`<Set>` の子）

注:

この要素は現在、プロキシのターゲット URL のオーバーライド / 書き換える設計どおりには機能していません（下記の例を実行して学習する際、ServiceCallout のパスを設定するのに使います）。

場合によっては、API プロキシの TargetEndpoint で定義された URL 以外の URL へのメッセージの送信が必要になります。ターゲット URL を書き換える場合は、<AssignVariable> 要素を使用して TargetEndpoint の target.url 変数をオーバーライドします（Apigee によって TargetEndpoint に変数が設定されるため、ProxyEndpoint の target.url はオーバーライドできません）。

次の例は、AssignMessage ポリシーが target.url をオーバーライドする方法を示しています。ここでも、TargetEndpoint リクエストにこのポリシーを追加します。このポリシーを使用すると、プロキシによって、TargetEndpoint で定義された URL ではなく、以下の URL が呼び出されます。

<AssignMessage name="Assign-Message-1">
...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>http://mocktarget.apigee.net/user?user=Dude</Value>
  </AssignVariable>
...

また、TargetEndpoint で JavaScript ポリシーを使用して target.url をオーバーライドすることもできます。

`<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 では、JSON ペイロード内で中かっこを使用して変数参照を指定することはできませんでした。このようなバージョンでは、variablePrefix 属性と variableSuffix 属性を使用して区切り文字を指定し、次のように変数名を囲む必要がありました。

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

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

例 4

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

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

<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

次の例では、address クエリパラメータが request.header.address 変数の値に設定されています。

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

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

HTTP 動詞: GET、POST、PATCH、DELETE
メッセージタイプ: リクエスト

ポリシー（<Set><QueryParams/></Set>）で空のクエリパラメータを定義した場合、このポリシーではクエリパラメータが設定されません。これは、<QueryParams> を省略した場合と同じです。

`<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="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

例 2

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

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</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="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

例 2

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

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

<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</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="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>

例 2

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

<AssignMessage name="AM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

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

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

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

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

デフォルトの場合、Apigee はカスタムリクエストメッセージに対して何も行いません。作成後、Apigee は元のリクエストでフローを続行します。カスタムリクエストを使用するには、ServiceCallout ポリシーなどのポリシーをプロキシに追加し、そのポリシーの構成で新しく作成されたリクエストメッセージを明示的に参照します。これにより、カスタムリクエストを外部サービスエンドポイントに渡すことができます。

次の例では、カスタムリクエストメッセージが作成されます。

例 1

次の例では、AssignMessage を使用してカスタムリクエストオブジェクトが作成されます。

<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> は source 属性を指定していないため、Apigee は request メッセージをコピー元のソースとして使用します。
- カスタムメッセージの address クエリパラメータを受信リクエストの addy クエリパラメータの値に設定します。
- HTTP 動詞を GET に設定します。
<IgnoreUnresolvedVariables> を false に設定します。<IgnoreUnresolvedVariables> が false の場合、ポリシー構成で参照されている変数のいずれかが存在しないと、Apigee は API フローで障害状態に入ります。

例 2

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

<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> が設定されます。

カスタムメッセージのさまざまなプロパティには、フローの後続部分で出現する別の AssignMessage ポリシーでアクセスできます。次の例では、名前付きカスタムレスポンスからヘッダーの値が取得され、リクエストメッセージの新しいヘッダーに設定されます。

<AssignMessage name="AM-Copy-Custom-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</AssignMessage>

エラーコード

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

ランタイムエラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス原因修正

steps.assignmessage.SetVariableFailed 500 ポリシーが変数を設定できませんでした。未解決の変数の名前については、障害文字列をご覧ください。

障害コード	HTTP ステータス	原因
`steps.assignmessage.SetVariableFailed`	`500`	ポリシーが変数を設定できませんでした。未解決の変数の名前については、障害文字列をご覧ください。
`steps.assignmessage.VariableOfNonMsgType`	`500`	このエラーは、`<Copy>` 要素の `source` 属性が、メッセージ型以外の変数に設定されている場合に発生します。メッセージ型の変数は HTTP リクエストとレスポンス全体を表します。組み込みの Apigee フロー変数 `request`、`response`、`message` はメッセージ型です。メッセージ変数の詳細については、変数リファレンスをご覧ください。
`steps.assignmessage.UnresolvedVariable`	`500`	このエラーは、AssignMessage ポリシーで指定された変数が次のいずれかの場合に発生します。範囲外（ポリシーが実行されている特定のフローで使用できない）または解決不能（未定義）

steps.assignmessage.VariableOfNonMsgType

500

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

メッセージ型の変数は HTTP リクエストとレスポンス全体を表します。組み込みの Apigee フロー変数 request、response、message はメッセージ型です。メッセージ変数の詳細については、変数リファレンスをご覧ください。

steps.assignmessage.UnresolvedVariable

500

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

範囲外（ポリシーが実行されている特定のフローで使用できない）
解決不能（未定義）

デプロイエラー

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

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

障害変数

次の変数は、このポリシーでランタイムエラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数	説明	例
`fault.name="FAULT_NAME"`	`FAULT_NAME` は、上記のランタイムエラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。	`fault.name Matches "UnresolvedVariable"`
`assignmessage.POLICY_NAME.failed`	`POLICY_NAME` は、障害が発生したポリシーのユーザー指定の名前です。	`assignmessage.AM-SetResponse.failed = true`

エラーレスポンスの例

注: ベストプラクティスとして、エラー処理でエラーレスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

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

障害ルールの例

<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 から入手できます。

AssignMessage ポリシー

What

ユースケース

動画

<AssignMessage> 要素

構文

デフォルト ポリシー

例

1: ヘッダーを追加する

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

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

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

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

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

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

8: フォーム パラメータ、ヘッダー、クエリ パラメータを保存および削除する

子要素のリファレンス

<Add>

構文

例 1

例 2

例 3

<FormParams>（<Add> の子）

構文

例 1

例 2

例 3

<Headers>（<Add> の子）

構文

例 1

<QueryParams>（<Add> の子）

構文

例 1

<AssignTo>

構文

例 1

例 2

例 3

<AssignVariable>

構文

例 1

例 2

例 3

例 4

<Name>（<AssignVariable> の子）

構文

例 1

<PropertySetRef>（<AssignVariable> の子）

構文

例 1

例 2

<Ref>（<AssignVariable> の子）

構文

例 1

例 2

例 3

<ResourceURL>（<AssignVariable> の子）

構文

例 1

例 2

<Template>（<AssignVariable> の子）

構文

例 1

例 2

例 3

<Value>（<AssignVariable> の子）

構文

例 1

例 2

<Copy>

構文

例 1

例 2

<FormParams>（<Copy> の子）

構文

例 1

例 2

例 3

例 4

<Headers>（<Copy> の子）

`<AssignMessage>` 要素

デフォルトポリシー

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

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

8: フォームパラメータ、ヘッダー、クエリパラメータを保存および削除する

`<Add>`

`<FormParams>`（`<Add>` の子）

`<Headers>`（`<Add>` の子）

`<QueryParams>`（`<Add>` の子）

`<AssignTo>`

`<AssignVariable>`

`<Name>`（`<AssignVariable>` の子）

`<PropertySetRef>`（`<AssignVariable>` の子）

`<Ref>`（`<AssignVariable>` の子）

`<ResourceURL>`（`<AssignVariable>` の子）

`<Template>`（`<AssignVariable>` の子）

`<Value>`（`<AssignVariable>` の子）

`<Copy>`

`<FormParams>`（`<Copy>` の子）

`<Headers>`（`<Copy>` の子）

`<Path>`（`<Copy>` の子）

`<Payload>`（`<Copy>` の子）

`<QueryParams>`（`<Copy>` の子）

`<StatusCode>`（`<Copy>` の子）

`<Verb>`（`<Copy>` の子）

`<Version>`（`<Copy>` の子）

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<Remove>`

`<FormParams>`（`<Remove>` の子）

`<Headers>`（`<Remove>` の子）

`<Payload>`（`<Remove>` の子）

`<QueryParams>`（`<Remove>` の子）

`<Set>`

`<FormParams>`（`<Set>` の子）

`<Headers>`（`<Set>` の子）

`<Path>`（`<Set>` の子）

`<Payload>`（`<Set>` の子）