HTTPModifier 政策

結果

HTTPModifier 政策可變更現有要求或回應訊息。

這項政策可讓您對這些訊息執行下列動作：

  • 新增表單參數、標頭或查詢參數至郵件
  • 移除郵件中的標頭、查詢參數和表單參數
  • 設定訊息中現有屬性的值

使用 HTTPModifier 時，您可以新增、變更或移除要求或回應的屬性。您也可以使用 HTTPModifier 建立自訂要求或回應訊息，並將其傳遞至其他目標，如「建立自訂要求訊息」一文所述。

HTTPModifier 政策可使用下列子項元素建立流程變數：

<Add>、<Set> 和 <Remove> 元素的排序順序相當重要。政策會按照政策設定中顯示的順序執行這些動作。如果您需要移除所有標頭，然後設定特定標頭，請在 <Set> 元素之前加入 <Remove> 元素。

這項政策是標準政策，可部署至任何環境類型。如要瞭解政策類型和各環境類型的可用性，請參閱「政策類型」。

<HTTPModifier> 元素

定義 HTTPModifier 政策。

預設值 請參閱下方的「Default Policy」分頁
是否必要？ 必填
類型 複雜物件
上層元素 N/A
子元素 <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>

在 Apigee UI 中插入新的 HTTPModifier 政策時，範本會包含所有可能作業的 Stub。通常，您會選取要透過這項政策執行哪些作業，並移除其他子元素。舉例來說，如果您要執行新增作業，請使用 <Add> 元素，並從政策中移除 <Remove> 和其他子項元素，讓政策更易於閱讀。

這個元素包含下列所有政策都適用的屬性：

屬性 預設 是否必要？ 說明
name 不適用 必要

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
enabled 是 選用 設為 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> 元素，從初始要求取得三個查詢字串參數的值，並將這些值設為目標端點要求的表單參數：

<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 會將修改後的要求傳送至目標端點。

您可以使用偵錯工具查看流程。您會發現要求主體包含網址編碼表單資料，這類資料原本會以查詢字串參數的形式傳入：

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 Proxy 收到的 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"/>-- no-op -->
  ...
</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>

建立新要求或回應物件時，HTTPModifier 政策的其他元素 (例如 <Add> 和 <Set>) 會對該新要求物件採取動作。

您可以在流程中稍後的其他政策中，透過名稱存取新的要求物件，也可以使用 ServiceCallout 政策，將新的要求物件傳送至外部服務。

下表說明 <AssignTo> 的屬性：

屬性 說明 是否必要 類型
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>

從訊息中移除標頭、查詢參數或表單參數。空白代碼會移除所有對應參數，包括標頭、表單參數和查詢參數。

受影響的訊息可以是要求或回應。您可以使用 <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

以下範例會從要求中移除三個表單參數：

<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 的第二個值。如果 f3 只有一個值，則不會移除。

只有在符合下列條件時，才能使用 <FormParams>：

  • 訊息類型：要求
  • Content-Type：application/x-www-form-urlencoded

<Headers> (<Remove> 的子項)

從要求或回應中移除指定的 HTTP 標頭，該標頭由 <AssignTo> 元素指定。

預設值 不適用
是否必要？ 選用
類型 <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 的第二個值。如果 h3 只有一個值，則不會移除。

<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 的第二個值。如果 qp3 只有一個值，則不會移除。

範例 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> 元素使用以下語法：

語法

<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> 的子項)

覆寫要求或回應中現有的 HTTP 標頭，這些標頭由 <AssignTo> 元素指定。

預設值 不適用
是否必要？ 選用
類型 <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 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因 修正
entities.UnresolvedVariable 500 訊息範本變數未定義或超出範圍。
steps.httpmodifier.InvalidStatusCode 500 狀態碼的解析值無效。如需更多資訊，請參閱錯誤字串。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因 修正
InvalidIndex 如果 HTTPModifier 政策的 <Remove> 元素中指定的索引為 0 或負數，則 API Proxy 的部署作業會失敗。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統就會設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

變數 地點 範例
httpmodifier.POLICY_NAME.failed POLICY_NAME 是擲回錯誤的政策的使用者指定名稱。 httpmodifier.HM-SetResponse.failed = true

錯誤回應範例

{
   "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 查看政策架構。