HTTPModifier ポリシー

概要

HTTPModifier ポリシーでは、既存のリクエストまたはレスポンスのメッセージを変更できます。

このポリシーを使用すると、そのようなメッセージに対して以下の操作を実行できます。

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

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

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

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

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。すべてのユーザーがポリシーや環境のタイプを知る必要はありません。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。

ユースケース

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

クエリ文字列パラメータや他の型の入力のデフォルト値を定義する。
メッセージをバックエンドサービスに転送する前に、リクエストメッセージから HTTP ヘッダーを削除する。
レスポンスをユーザーアプリに送信する前に HTTP ヘッダーを追加する。
カスタマイズされたリクエストメッセージやレスポンスメッセージを生成する。たとえば、外部コールアウトを使用して、API プロキシからリモート API を呼び出すことができます。HTTPModifier ポリシーを使用して、カスタムリクエストメッセージを作成し、それを変数に割り当てることができます。次に、外部コールアウトを使用してそのメッセージをリモート API に送信します。
デバッグやトラブルシューティングのためにリクエストとレスポンスにヘッダーを追加する。

`<HTTPModifier>` 要素

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

デフォルト値	下の「デフォルトポリシー」タブをご覧ください。
必須かどうか	必須
型	複合オブジェクト
親要素	なし
子要素	`<Add>` `<AssignTo>` `<DisplayName>` `<IgnoreUnresolvedVariables>` `<Remove>` `<Set>`

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

構文

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

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- All HTTPModifier 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>

  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>

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

  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all FormParams (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array to remove all Headers (<Headers/>) -->
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <!-- Can also be an empty array to remove all QueryParams (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <Path>PATH</Path>
    <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>

</HTTPModifier>

デフォルトポリシー

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

<HTTPModifier continueOnError="false" enabled="true" name="http-modifier-default">
  <DisplayName>HTTP Modifier-1</DisplayName>
  <Properties/>
  <Remove>
    <Headers>
      <Header name="h1"/>
    </Headers>
    <QueryParams>
      <QueryParam name="q1"/>
    </QueryParams>
    <FormParams>
      <FormParam name="f1"/>
    </FormParams>
  </Remove>
  <Add>
    <Headers/>
    <QueryParams/>
    <FormParams/>
  </Add>
  <Set>
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <!-- <Verb>GET</Verb> -->
    <Path/>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</HTTPModifier>

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

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

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

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

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

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

例

HTTPModifier ポリシーの使用方法の例をいくつか次に示します。

1: ヘッダーを追加する

次の例では、<Add> 要素を使用してリクエストにヘッダーを追加しています。この例の VerifyAPIKey 変数は、VerifyAPIKey ポリシーによって生成されます。

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

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

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

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

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

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

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

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

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

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

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

子要素のリファレンス

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

`<Add>`

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

<Add> 要素によって、元のメッセージに存在しない新しいプロパティがメッセージに追加されます。なお、<Set> にもこの機能があります。既存のプロパティの値を変更する場合は、<Set> 要素を使用します。

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

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

構文

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

例 1

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

<HTTPModifier name="HM-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>
</HTTPModifier>

例 2

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

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

例 3

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

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

この例では、リクエストのプリフローで <Add> を使用しています。デバッグツールなどのツールで結果を確認すると、https://example-target.com/get へのリクエストは https://example-target.com/get?myParam=42 になっています。

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

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

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

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

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

構文

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

例 1

次の例では、単一のフォームパラメータ（answer）と静的値（42）がリクエストに追加されています。

<HTTPModifier name="HM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</HTTPModifier>

例 2

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

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

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

例 3

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

<HTTPModifier name="HM-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>
</HTTPModifier>

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

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

username=nick&zip_code=90210&default_language=en

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

HTTP 動詞: GET、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> 要素の構文は次のとおりです。

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Add>
</HTTPModifier>

例 1

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

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

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>
</HTTPModifier>

例 1

次の例では、クエリパラメータ myParam がリクエストに追加され、値 42 が割り当てられます。

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

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

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

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

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

`<AssignTo>`

HTTPModifier ポリシーで操作するオブジェクトを決定します。次のオプションがあります。

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

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
</HTTPModifier>

例 1

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

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

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

例 2

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

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

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

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

例 3

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

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

フローの後続部分で他のポリシーの新しいリクエストオブジェクトに名前でアクセスできます。また、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 ではこのポリシーが実行されるフロー内の場所に応じて、リクエストまたはレスポンスが作成されます。

省略可

文字列

`<DisplayName>`

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

<DisplayName> 要素はすべてのポリシーに共通です。

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

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

構文

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

例

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

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

`<IgnoreUnresolvedVariables>`

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

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

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

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

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

構文

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

例 1

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

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

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

`<Remove>`

メッセージからヘッダー、クエリパラメータ、フォームパラメータを削除します。空のタグを指定すると、対応するすべてのパラメータ（ヘッダー、formparams、queryparams など）が削除されます。

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all FormParams (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array to remove all Headers (<Headers/>) -->
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <!-- Can also be an empty array to remove all QueryParams (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Remove>
</HTTPModifier>

例 1

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

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

例 2

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

<HTTPModifier name="HM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</HTTPModifier>

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

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all FormParams (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Remove>
</HTTPModifier>

例 1

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

<HTTPModifier name="HM-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>
</HTTPModifier>

例 2

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

<HTTPModifier name="HM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

例 3

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

<HTTPModifier name="HM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

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

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

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

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all Headers (<Headers/>) -->
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Remove>
</HTTPModifier>

例 1

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

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

例 2

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

<HTTPModifier name="HM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

例 3

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

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

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

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all QueryParams (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Remove>
</HTTPModifier>

例 1

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

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

例 2

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

<HTTPModifier name="HM-remove-queryparams-2">
  &tl;Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

例 3

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

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

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

例 4

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

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

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

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

`<Set>`

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

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

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

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

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

構文

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

例

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

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

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Set>
</HTTPModifier>

例 1

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

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

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

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

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

<Set> は、メッセージの Content-Type を application/x-www-form-urlencoded に変更した後、それをターゲットエンドポイントに送信します。

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Set>
</HTTPModifier>

例 1

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

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

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

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

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

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

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

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Set>
</HTTPModifier>

例 1

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

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

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

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

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

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

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

デフォルト値	「200」（`<AssignTo>` の `createNew` 属性が「true」に設定されている場合）
必須かどうか	省略可
型	文字列または `VARIABLE`
親要素	`<Set>`
子要素	なし

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

構文

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
  </Set>
</HTTPModifier>

例 1

次の例では、単純なステータスコードが設定されます。

<HTTPModifier name="HM-set-statuscode-404">
  <Set>
    <StatusCode>404<<StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</HTTPModifier>

例 2

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

<HTTPModifier name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</HTTPModifier>

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

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

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

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

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

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

構文

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

例 1

次の例では、リクエストに単純な動詞が設定されます。

<HTTPModifier name="HM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</HTTPModifier>

例 2

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

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

<HTTPModifier name="HM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</HTTPModifier>

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

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

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

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

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

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

構文

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

例 1

次の例では、バージョン番号が 1.1 に設定されています。

<HTTPModifier name="HM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
</HTTPModifier>

例 2

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

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

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

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

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

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

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

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

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

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

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

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

例 1

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

<HTTPModifier name="HTTPModifier-3">
  <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.addy}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</HTTPModifier>

この例では

MyCustomRequest という新しいリクエストメッセージオブジェクトが作成されます。
MyCustomRequest では、このポリシーは次の処理を行います。
- カスタムメッセージの address クエリパラメータを受信リクエストの addy クエリパラメータの値に設定します。
- HTTP 動詞を GET に設定します。
<IgnoreUnresolvedVariables> を false に設定します。<IgnoreUnresolvedVariables> が false の場合、ポリシー構成で参照されている変数のいずれかが存在しないと、Apigee は API フローで障害状態に入ります。

例 2

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

<HTTPModifier name="HTTPModifier-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <Set>
    <Verb>POST</Verb>
  </Set>
</HTTPModifier>

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

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

<HTTPModifier name="HM-Set-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</HTTPModifier>

エラーコード

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

ランタイムエラー

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

障害コード	HTTP ステータス	原因	修正
`entities.UnresolvedVariable`	`500`	メッセージテンプレート変数が定義されていないか、範囲外です。
`steps.httpmodifier.InvalidStatusCode`	`500`	ステータスコードの解決済みの値が無効です。詳細については、障害文字列をご覧ください。

デプロイエラー

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

エラー名	原因	修正
`InvalidIndex`	`HTTPModifier` ポリシーの `<Remove>` 要素で指定されたインデックスが `0` または負の数の場合、API プロキシのデプロイに失敗します。

障害変数

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

変数	説明	例
`httpmodifier.POLICY_NAME.failed`	`POLICY_NAME` は、障害が発生したポリシーのユーザー指定の名前です。	`httpmodifier.HM-SetResponse.failed = true`

エラーレスポンスの例

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

{
   "fault":{
      "detail":{
         "errorcode":"steps.httpmodifier.InvalidStatusCode"
      },
      "faultstring":"HTTPModifier[HM-SetResponse]: Invalid status code bad_request"
   }
}

障害ルールの例

<FaultRule name="HTTPModifier Faults">
    <Step>
        <Name>HM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "InvalidStatusCode")</Condition>
    </Step>
    <Condition>(httpmodifier.failed = true)</Condition>
</FaultRule>

スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。参照用のポリシースキーマは GitHub から入手できます。

HTTPModifier ポリシー

概要

ユースケース

<HTTPModifier> 要素

構文

デフォルト ポリシー

例

1: ヘッダーを追加する

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

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

子要素のリファレンス

<Add>

構文

例 1

例 2

例 3

<FormParams>（<Add> の子）

構文

例 1

例 2

例 3

<Headers>（<Add> の子）

構文

例 1

<QueryParams>（<Add> の子）

構文

例 1

<AssignTo>

構文

例 1

例 2

例 3

<DisplayName>

構文

例

<IgnoreUnresolvedVariables>

構文

例 1

<Remove>

構文

例 1

例 2

<FormParams>（<Remove> の子）

構文

例 1

例 2

例 3

<Headers>（<Remove> の子）

構文

例 1

例 2

例 3

<QueryParams>（<Remove> の子）

構文

例 1

例 2

例 3

例 4

<Set>

構文

例

<FormParams>（<Set> の子）

構文

例 1

<Headers>（<Set> の子）

構文

例 1

<Path>（<Set> の子）

<QueryParams>（<Set> の子）

構文

例 1

<StatusCode>（<Set> の子）

構文

例 1

例 2

<Verb>（<Set> の子）

構文

例 1

例 2

<Version>（<Set> の子）

`<HTTPModifier>` 要素

デフォルトポリシー

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

`<Add>`

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

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

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

`<AssignTo>`

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<Remove>`

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

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

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

`<Set>`

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

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

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

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

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

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

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

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

ランタイムエラー

エラーレスポンスの例