AssignMessage ポリシー

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

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

ポリシー アイコン

What

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

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

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

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

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

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 に設定します。関連情報:
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 ポリシーが使用されています。

  1. リクエストに 3 つのフロー変数を作成し、静的な値を割り当てます。
  2. リクエスト フローの 2 番目のポリシーでフロー変数を動的に取得します。
  3. レスポンスのペイロードでこれらの変数を設定します。
<!-- 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. ポリシー #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: 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>

このリファレンスの各子要素については、他にも例を用意しています。その他の例については、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 動詞: GETPOSTPATCHDELETE
  • メッセージ タイプ: リクエスト

また、クエリ パラメータは、<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>

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

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

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

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

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

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

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

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

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

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

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

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

省略可 文字列
type createNewtrue の場合、新しいメッセージのタイプを指定します。有効な値は 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> によって作成されます。

<PropertySetRef><AssignVariable> の子)

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

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

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

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

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

<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

次の例では、フロー変数 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、読み取りできない、または不正な形式の場合、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> の値は、requestresponsetarget のオブジェクトのプロパティやカスタムフロー変数の名前など、フロー変数でなければなりません。

<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> の効果はなくなります。
省略可 文字列

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

この例では、f1f2 と、f3 の 2 番目の値がコピーされます。f3 の値が 1 つしかない場合はコピーされません。

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

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

<FormParams> をコピーすると、<Copy> は、メッセージの Content-Typeapplication/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>

この例では、h1h2 と、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>

この例では、qp1qp2 と、qp3 の 2 番目の値がコピーされます。qp3 の値が 1 つしかない場合はコピーされません。

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

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

<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>continueOnErrortrue に設定することとは異なります。continueOnErrortrue に設定すると、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>

この例では、f1f2 と、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>

この例では、h1h2 と、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>

この例では、qp1qp2 と、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 動詞: GETPOSTPATCHDELETE
  • メッセージ タイプ: リクエスト

<Set>

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

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

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <AssignMessage>
子要素 <FormParams>
<Headers>
<Payload>
<Path>
<QueryParams>
<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>
    <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-Typeapplication/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> の子)

<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 動詞: GETPOSTPATCHDELETE
  • メッセージ タイプ: リクエスト

ポリシー(<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> 要素を使用します。次の例のように、createNewtrue に設定し、要素の本文に新しいメッセージの名前を指定します。

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

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

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

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

エラー レスポンスの例

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

関連トピック

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

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

ServiceCallout ポリシーで実行中の「set path」を確認するには、Apigee GitHub サンプルの実際にやってみて学ぶの例をご覧ください。リポジトリのクローンを作成し、そのトピックの指示に従います。この例では、AssignMessage を使用してリクエストパスが設定され、ServiceCallout ポリシーを使用して外部サービスへのリクエストが行われます。