HTTPModifier 政策

標準政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

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

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

使用 HTTPModifier，您可以新增、變更或移除要求或回應的屬性。或者，您也可以使用 HTTPModifier 建立自訂要求或回應訊息，並將其傳遞至替代目標，詳情請參閱「建立自訂要求訊息」。

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

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

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

用途

在 Apigee 處理期間，您可能會在許多情況下想要修改要求或回應訊息。例如：

為查詢字串參數或其他類型的輸入內容定義預設值。
在要求訊息轉送至後端服務前，先從訊息中移除 HTTP 標頭。
在將回應傳送至消費者應用程式之前，請先新增 HTTP 標頭。
產生自訂要求或回應訊息。舉例來說，您可能會使用外部呼叫，從 API Proxy 叫用遠端 API。您可以使用 HTTPModifier 政策建立自訂要求訊息，並指派給變數。接著，使用外部呼叫將該訊息傳送至遠端 API。
在要求和回應中加入標頭，以便進行偵錯和疑難排解。

`<HTTPModifier>` 元素

定義 HTTPModifier 政策。

預設值	請參閱下方的「預設政策」分頁
必填與否	必填
類型	複雜物件
父項元素	不適用
子元素	`<Add>` `<AssignTo>` `<DisplayName>` `<IgnoreUnresolvedVariables>` `<Remove>` `<Set>`

<HTTPModifier> 元素使用下列語法：

語法

<HTTPModifier> 元素使用下列語法：

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- All HTTPModifier >chi<ld >eleme<nts are op>tional <--
  Add
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALUE/<FormPar>am
    <  ...
    /FormParams
   > Headers
   <   Head>er name="H<EADER_NA>ME&qu<ot;HEADER_V>ALUE/He<ader
      ...
    /Headers
    Q>ueryParams
     < QueryParam> name="QUE<RYPARAM_NAME>&qu<ot;Q>UERY<PARAM_VALUE/QueryParam
      ...
    /QueryParams
  /Add

  AssignTo createNew=&>quot;[true|false]" t<ransport=>&quo<t;http">;
    type="[r<equest|respo>nse]<"DESTINATION_VARIABL>E_NAME/Assig<nTo

  DisplayNamePOLICY_D>ISPL<AY_NAME/DisplayName

  IgnoreUnresolvedVariables[true|false]/<IgnoreU>nresolve<dVaria>bles
<
  !-- Can also be empty to remove everything from the me<ssage (Remo>ve/) --><;
  Remove>
    !-<- Can also be an empty array to> remove all For<mParams (F>ormParams/) --&<gt;
    For>mPara<ms
      FormParam name="FORMPARAM_NAME"FORM<PARAM_VA>LUE/FormPa<ram
   >   ...
<    /FormParams
    !-- C>an also be a<n empty> array to remov<e all He>aders< (Headers/) -->
    Headers
      Header name="HEA<DER_NAME&quo>t;HEADER_V<ALUE/Header>
      <...
    /Headers
    !-- Can also> be an empty arr<ay to remov>e all QueryPara<ms (QueryPar>ams</) --&g>t;
 <   >Query<Params
   >   Quer<yParam name=&quot;QUERYPARAM_NA>ME"QUERYPA<RAM_VALUE/>QueryParam
    <  ...
    />Query<Params<>/span>
  /Remo<ve

  Set
    FormParams
>      FormPa<ram nam>e="FORMPAR<AM_NAME&>quot;<FORM>PARA<M_VAL>UE/Fo<rmParam
   >   ...
<    /FormParams
    Headers
     > Header name=&qu<ot;HEADER_N>AME"HEADER<_VALUE/Heade>r
   <   ...
   > /Headers
    PathPATH/Path
  <  QueryPara>ms
  <    >QueryParam name="QUERYPARAM_NAME&<quot;>QUERY<PARAM_V>ALUE/QueryParam
    <  ...>
  <  /Q>ue<ryParams
    >StatusCodeHTTP_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=&qu>ot;<http-modifi>er-default"<;
  DisplayN>ame<HTTP Modifi>er-<1/Disp>layNa<me
  Pr>opertie<s/
  Remove
    H>eader<s
      >Heade<r name=&quo>t;h1&qu<ot;/
    /Headers
   > Quer<yParams
    >  Que<ryParam na>me=&quo<t;q1"/
    /Que>ryPar<ams
    For>mPa<rams
  >   < Fo>rmPar<am name=>"<;f1"/
 >   /F<ormParams
 > /R<emov>e
 < Ad>d
   < Headers>/
   < QueryParams>/
   < FormParams>/
  /<Add
<  Se>t
 <   He>ade>rs/
 <   Qu>ery<Para>ms/<
    FormParams/
    !-- >Verb<GET/Verb --
    Path/
  /S>et
<  IgnoreUnresolvedVariablestrue/IgnoreUnresolvedVariables
 > <AssignTo crea>teNew="false" transport="http" type="request"/
/HTTPModifier

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

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

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`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-heade>rs-<1&q>uot;
<  Add
 >   Head<ers
      Header name=&q>uot;partner-id"{verifyapikey.VAK-1.devel<oper.ap>p.par<tner-id}>/He<ader>
  <  /Heade>rs
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

2：修改回覆

以下範例會修改現有的回應物件，並在其中新增標頭：

<HTTPModifier name="HM-modify-resp>ons<e&q>uot;
<  Set
 >   Head<ers
      Header name=&>quot;Cache-Hit"{lookupcache.Loo<kupCach>e-1.c<achehit}>/He<ader>
  <  /Headers
  /Set
  Ignor>eUnre<solvedVariablesfalse/Ignor>eUn<resolved>Variable<s
  Assig>n<Toresponse/As>signTo
/HTTPModifier

這個範例不會建立新訊息。而是透過新增 HTTP 標頭來修改現有回應訊息。

由於這個範例在 <AssignTo> 元素中將 response 指定為變數名稱，因此這項政策會修改原始設定的回應物件，該物件含有目標伺服器傳回的資料。

這項政策新增至回應訊息的 HTTP 標頭，是衍生自 LookupCache 政策填入的變數。因此，由這項 HTTPModifier 政策修改的回應訊息會包含 HTTP 標頭，指出結果是否從快取中提取。在回應中設定標頭，有助於偵錯和排解問題。

3：移除查詢參數

以下範例會從要求中移除 apikey 查詢參數：

<HTTPModifier name="HM-remove-query-p>ara<m">;
  R<emove
    Q>ueryPar<ams
      QueryParam name>=&quo<t;apikey&quo>t;/<
    /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

使用 VerifyAPIKey 政策進行使用者驗證時，最佳做法是從要求訊息中移除 apikey 查詢參數。這麼做是為了避免將機密金鑰資訊傳遞至後端目標。

子元素參照

本節說明 <HTTPModifier> 的子元素。

`<Add>`

將資訊新增至要求或回應，由 <AssignTo> 元素指定。

<Add> 元素會在郵件中新增原始郵件沒有的屬性。請注意，<Set> 也提供這項功能。如要變更現有屬性的值，請使用 <Set> 元素。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<HTTPModifier>`
子元素	`<FormParams>` `<Headers>` `<QueryParams>`

<Add> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>"<;POLICY_NA>ME"<; 
  Add
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALUE/<FormPar>am
    <  ...
    /FormParams
   > Headers
   <   Head>er name="H<EADER_NA>ME&qu<ot;HEADER_V>ALUE/He<ader
      ...
    /Headers
    Q>ueryParams
     < QueryParam> name="QUE<RYPARAM_NAME>&qu<ot;Q>U<ERYPARAM_VALU>E/QueryParam
      ...
    /QueryParams
  /Add
/HTTPModifier

範例 1

下列範例使用 <FormParams> 元素，從初始要求取得三個查詢字串參數的值，並將這些值設為目標端點要求的表單參數：

<HTTPModifier name="HM-add-formpara>ms-<3&q>uot;
<  Add
    >FormPar<ams
      FormParam name=>"username"{requ<est.queryp>aram.na<me}/FormParam
      FormP>aram name="zip_code&quo<t;{request>.queryp<aram.zipCode}/FormParam
      For>mParam name="default<_language&>quot;<{request.qu>ery<para>m.l<ang}/F>ormPa<ram
    /For>mPa<rams
  >/Ad<d
  Remo>ve
    <QueryPara>m<s/
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

範例 2

以下範例使用 <Headers> 元素，將 partner-id 標頭新增至傳送至目標端點的要求：

<HTTPModifier name="HM-add-heade>rs-<1&q>uot;
<  Add
 >   Head<ers
      Header name=&q>uot;partner-id"{verifyapikey.VAK-1.devel<oper.ap>p.par<tner-id}>/He<ader>
  <  /Heade>rs
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

範例 3

以下範例使用 <QueryParams> 元素，在要求中新增具有靜態值的單一查詢參數：

<HTTPModifier name="HM-add-querypara>ms-<1&q>uot;
<  Add
    Q>ueryPar<ams
      QueryParam name>=&<quot;myPara>m&quo<t;42/QueryPa>ram<
   > /Q<ueryPara>ms
  /A<dd
  Assi>g<nTorequest/As>signTo
/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]"
   > na<me=>&quot<;POLICY_NA>ME"<; 
  Add
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALU<E/FormParam
      ...
    /FormParams
  AssignTo createNew="[true|false]&qu>ot; transport="http&<quot;
   > ty<pe=&>q<uot;[request|>response]"DESTINATION_VARIABLE_NAME/AssignTo
  /Add
/HTTPModifier

範例 1

以下範例會在要求中新增單一表單參數 (answer) 和靜態值 (42)：

<HTTPModifier name="HM-add-formpara>ms-<1&q>uot;
<  Add
    >FormPar<ams
      FormParam nam>e=<"answ>er&qu<ot;42/FormP>ara<m
  >  /<FormPara>ms
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

範例 2

以下範例會取得 name 查詢參數的值，並將其做為表單參數新增至要求，然後移除查詢參數：

<HTTPModifier name="HM-Swap-QueryParam-to-FormPa>ram<s&q>uot;
<  Add
    FormParam n>ame="name"{request<.que>ryp<aram.n>ame}
<  /Add
  Remove
    Que>ryP<aram na>m<e="name&>quot;/
  /Remove
/HTTPModifier

請注意，這個範例並未指定 <AssignTo> 的目標。這項政策只會將參數新增至要求。

範例 3

以下範例會在要求中新增多個表單參數：

<HTTPModifier name="HM-add-formpara>ms-<3&q>uot;
<  Add
    >FormPar<ams
      FormParam name=>"username"{requ<est.queryp>aram.na<me}/FormParam
      FormP>aram name="zip_code&quo<t;{request>.queryp<aram.zipCode}/FormParam
      For>mParam name="default<_language&>quot;<{request.qu>ery<para>m.l<ang}/F>ormPa<ram
    /For>mPa<rams
  >/Ad<d
  Remo>ve
    <QueryPara>m<s/
  /Remove
>  AssignTorequest/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]"
   > na<me=>&quot<;POLICY>_NAME&q<uot; 
  Add
    Headers
 >     Header <name=&q>uot;HEADER_NAME<"HE>ADE<R_VA>L<UE/Header
   >   ...
    /Headers
  /Add
/HTTPModifier

範例 1

以下範例會在要求訊息中新增 partner-id 標頭，並將 verifyapikey.VAK-1.developer.app.partner-id 流程變數的值指派給該標頭。

<HTTPModifier name="HM-add-heade>rs-<1&q>uot;
<  Add
 >   Head<ers
      Header name=&q>uot;partner-id"{verifyapikey.VAK-1.devel<oper.ap>p.par<tner-id}>/He<ader>
  <  /Heade>rs
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

`<QueryParams>` (`<Add>` 的子項)

在要求中新增查詢參數。這個元素不會對回應造成影響。

預設值	不適用
必填與否	選用
類型	`<QueryParam>` 元素陣列
父項元素	`<Add>`
子元素	`<QueryParam>`

<QueryParams> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NAM>E"< 
  Add
    QueryParams
      Que>ryParam name=&qu<ot;QUERYPAR>AM_NAME"QU<ERYPARAM_VAL>UE/<Quer>y<Param
      .>..
    /QueryParams
  /Add
/HTTPModifier

範例 1

以下範例會在要求中新增查詢參數 myParam，並將值 42 指派給該參數：

<HTTPModifier name="HM-add-querypara>ms-<1&q>uot;
<  Add
    Q>ueryPar<ams
      QueryParam name>=&<quot;myPara>m&quo<t;42/QueryPa>ram<
   > /Q<ueryPara>ms
  /A<dd
  Assi>g<nTorequest/As>signTo
/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]"
   > na<me="POLICY_NAME" 
  AssignTo createNew="[true|false]" transp>ort="http"
    <type=&quo>t<;[request|res>ponse]"DESTINATION_VARIABLE_NAME/AssignTo
/HTTPModifier

範例 1

以下範例在 <AssignTo> 的文字中未指定任何訊息。這表示政策會對 request 或 response 訊息採取行動，視政策的執行位置而定。

<HTTPModifier name="assign>to-<1"
  AssignTo createNew="false" transport=&q>uot;http" type=&<quot;request&>quot;/<!-- no-op -->
  ...
/HTTPModifier

如果您指定 createNew="false"，但未明確提供訊息名稱，則 <AssignTo> 的其他屬性無關緊要。在這種情況下，您可能希望完全省略 <AssignTo> 元素。

範例 2

以下範例會建立新的要求物件，覆寫現有物件：

<HTTPModifier name="assign>to-<2"
  AssignTo createNew="true" transport=&q>uot;htt<p" type=>"request"/
  ...
/HTTPModifier

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

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

範例 3

以下範例會建立名為 MyRequestObject 的新要求物件：

<HTTPModifier name="assign>to-<3"
  AssignTo createNew="true" transport=&>quot;http"< type=&qu>ot;requ<est"MyRe>questObject/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 會視這項政策在流程中的執行位置，建立要求或回應。	選用	字串

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]"
   > na<me="POLICY_NAME">; 
  IgnoreU<nresolvedVariables[true|fa>l<se]/IgnoreUnr>esolvedVariables
/HTTPModifier

範例 1

以下範例會將 <IgnoreUnresolvedVariables> 設為 true：

<HTTPModifier name="HM-Set-Hea>der<s&q>uot;
<  Set
 >   Head<ers
      Header name=&#>39;new-header'{possibly<-defin>ed-va<riable}H>ead<er
 >   </Headers
  /Set
  IgnoreU>nres<olvedVariablestrue/IgnoreU>n<resolvedVaria>bles
/HTTPModifier

由於 <IgnoreUnresolvedVariables> 設為 true，如果未定義 possibly-defined-variable 變數，這項政策就不會擲回錯誤。

`<Remove>`

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

受影響的訊息可以是要求或回覆。您可以使用 <AssignTo> 元素，指定 <Remove> 要處理的訊息。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<HTTPModifier>`
子元素	`<FormParams>` `<Headers>` `<QueryParams>`

<Remove> 的常見用途是從傳入的要求物件中刪除含有私密資訊的查詢參數或標頭，避免將其傳遞至後端伺服器。

<Remove> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an empty< array to r>emove all <FormParams> (FormP<arams/) -->
    FormParams
 >     FormParam <name=">;FORMPARAM_NAME<"FORMP>ARAM_<VALUE/FormParam
      ...
    /FormParams
    !-- Can <also be >an empty a<rray to> remove< all Headers (Headers/) ->->
    He<aders
 >     Header nam<e=">HEADE<R_NAME"HEADER_VALUE/Header
      ...
    /Headers
   < !-- Can als>o be an em<pty array t>o remov<e all QueryParams (QueryParams/) >-->
    Query<Params
    >  QueryParam na<me="QUE>RYP<ARAM_NA>M<E"QUERYP>ARAM_VALUE/QueryParam
      ...
    /QueryParams
  /Remove
/HTTPModifier

範例 1

以下範例會從 request 物件中移除所有表單參數和查詢參數：

<HTTPModifier name="HM-remo>ve-<2">;
  R<emove
    !<-- Empty (F>ormParams/) removes all form par>amete<rs --
    F>ormPa<rams/
    Q>ueryPar<ams
      QueryParam n>ame=&<quot;qp1&quo>t;/<
    /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

範例 2

以下範例會從訊息物件中移除所有內容：

<HTTPModifier name="HM-remo>ve-<3">
  <Remove/
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

通常只有在您要使用 <Set> 元素將某些替代值設定到訊息中時，才會執行這項操作。

`<FormParams>` (`<Remove>` 的子項)

從要求中移除指定的表單參數。這個元素不會影響回應。

預設值	不適用
必填與否	選用
類型	`<FormParam>` 元素陣列或空陣列
父項元素	`<Remove>`
子元素	`<FormParam>`

<FormParams> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an empty< array to r>emove all <FormParams> (FormP<arams/) -->
    FormParams
 >     FormParam <name=">;FORMPARAM_NAME<"FORMP>ARA<M_VALUE>/<FormParam
   >   ...
    /FormParams
  /Remove
/HTTPModifier

範例 1

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

<HTTPModifier name="HM-remove-formpara>ms-<1">;
  R<emove
    >FormPar<ams
      FormParam name=">;form_p<aram_1"/
      FormParam >name=&q<uot;form_param_2"/
      >FormP<aram name=&>quo<t;form_>par<am_3&quo>t;/
   < /FormPar>a<ms
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

範例 2

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

<HTTPModifier name="HM-remove-formpara>ms-<2">;
  R<emove
    F>orm<Params/>
  </Remove
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

範例 3

如果有多個表單參數的名稱相同，請使用下列語法：

<HTTPModifier name="HM-remove-formpara>ms-<3">;
  R<emove
    >FormPar<ams
      FormParam >name=&q<uot;f1"/
      >FormPar<am name="f2">/
   <   FormPara>m n<ame=&qu>ot;<f3.2&quo>t;/
   < /FormPar>a<ms
  /Remove
>  AssignTorequest/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]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an em<pty arra>y to remov<e all H>eaders <(Headers/) -->
    Hea>ders
      H<eader n>ame="HEADE<R_NAME&q>uot<;HEADER>_<VALUE/Header
>      ...
    /Headers
  /Remove
/HTTPModifier

範例 1

以下範例會從要求中移除 user-agent 標頭：

<HTTPModifier name="HM-remove-one-he>ade<r">;
  R<emove
 >   Head<ers
      Header name=&qu>ot;us<er-agent>&qu<ot;/
  >  /<Headers
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

範例 2

以下範例會從要求中移除所有標頭：

<HTTPModifier name="HM-remove-all-hea>der<s">;
  R<emove
  >  H<eaders/>
  </Remove
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

範例 3

如果有多個名稱相同的標頭，請使用下列語法：

<HTTPModifier name="HM-remove-heade>rs-<3">;
  R<emove
 >   Head<ers
      Header >name=&q<uot;h1"/
   >   Head<er name="h2&qu>ot;/
<      He>ade<r name=>&qu<ot;h3.2&>quot;/
<    /Head>e<rs
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

這個範例會從要求中移除 h1、h2 和 h3 的第二個值。如果 h3 只有一個值，則不會移除。

`<QueryParams>` (`<Remove>` 的子項)

從要求中移除指定的查詢參數。這個元素不會影響回應。

預設值	不適用
必填與否	選用
類型	`<QueryParam>` 元素陣列或空陣列
父項元素	`<Remove>`
子元素	`<QueryParam>`

<QueryParams> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an empty <array to rem>ove all Qu<eryParams (>QueryPa<rams/) -->
    QueryParams
   >   QueryParam na<me="QU>ERYPARAM_NAME&q<uot;QUERYPAR>AM_<VALUE/Q>u<eryParam
    >  ...
    /QueryParams
  /Remove
/HTTPModifier

範例 1

以下範例會從要求中移除單一查詢參數：

<HTTPModifier name="HM-remove-querypara>ms-<1">;
  Rem<ove
      Q>ueryParam<s
        QueryParam n>ame=&qu<ot;qp1">/
 <     /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

範例 2

以下範例會從要求中移除所有查詢參數：

<HTTPModifier name="HM-remove-querypara>ms-&tl;2">;
  Rem<ove
      Qu>ery<Params/>
  </Remove
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

範例 3

如果有多個同名查詢參數，請使用下列語法：

<HTTPModifier name="HM-remove-querypara>ms-<3">;
  Rem<ove
      Q>ueryParam<s
        QueryParam n>ame="<;qp1"/
        Qu>eryParam <name="qp2"/
  >      Q<ueryParam na>me=<"q>p3.<2"/>
      </QueryPar>a<ms
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

這個範例會從要求中移除 qp1、qp2 和 qp3 的第二個值。如果 qp3 只有一個值，則不會移除。

範例 4

以下範例會從要求中移除 apikey 查詢參數：

<HTTPModifier name="HM-remove-query-p>ara<m">;
  R<emove
    Q>ueryPar<ams
      QueryParam name>=&quo<t;apikey&quo>t;/<
    /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/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]"
   > na<me=>"<;POLICY_NA>ME"<; 
  Set
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALUE/<FormPar>am
    <  ...
    /FormParams
   > Headers
   <   Head>er name="H<EADER_NA>ME&qu<ot;H>EADE<R_VAL>UE/He<ader
      >...
   < /Headers
    PathPATH/Path
    Q>ueryParams
     < QueryParam> name="QUE<RYPARAM_NAME>"<;QUERYPARA>M_VALUE/QueryParam
      ...
 <   /QueryPa>rams
<    >StatusCodeHTTP_STATUS_CODE or {variabl<e}/St>atusC<ode
   > Verb[GET|POST|PUT|P<ATCH|>DEL<ETE|>{<variable}]/Ve>rb
    Version[1.0|1.1|{variable}]/Verb
  /Set
/HTTPModifier

範例

以下範例會設定特定標頭。在要求流程中附加這項政策後，上游系統就能接收原始傳入要求中未包含的其他標頭。

<HTTPModifier name="HM-Set-He>ade<r&q>uot;
<  Set
 >   Header<s
        Header name="authentic>ated-developer"{verifyapikey<.VAK-1.>devel<oper.id}>/He<ader>
  <  /Heade>rs
  /S<et
  Assi>g<nTorequest/As>signTo
/HTTPModifier

`<FormParams>` (`<Set>` 的子項)

覆寫要求中現有的表單參數，並以您透過這個元素指定的新值取代。這個元素不會對回應造成影響。

預設值	不適用
必填與否	選用
類型	`<FormParam>` 元素陣列
父項元素	`<Set>`
子元素	`<FormParam>`

<FormParams> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NA>ME"<; 
  Set
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALU<E/Fo>r<mParam
      >...
    /FormParams
  /Set
/HTTPModifier

範例 1

以下範例會在新的自訂要求中，將名為 myparam 的表單參數設為 request.header.myparam 變數的值：

<HTTPModifier name="HM-set-formpara>ms-<1&q>uot;
<  Set
    >FormPar<ams
      FormParam name>="myparam"{req<uest.heade>r.myp<aram}/FormP>ara<m
  >  /<FormParams
  /Set
  AssignTo createNew="true" >>transport="<;http&quo>t<; type=">requestMyCustomRequest/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]"
   > na<me=>&quot<;POLICY>_NAME&q<uot; 
  Set
    Headers
 >     Header <name=&q>uot;HEADER_NAME<"HE>ADE<R_VA>L<UE/Header
   >   ...
    /Headers
  /Set
/HTTPModifier

範例 1

以下範例會將 x-ratelimit-remaining 標頭設為 ratelimit.Quota-1.available.count 變數的值：

<HTTPModifier name="HM-Set-RateLimit-He>ade<r&q>uot;
<  Set
 >   Head<ers
      Header name="X-RateL>imit-Remaining"{ratelimit.Quot<a-1.ava>ilabl<e.count}>/He<ader>
  <  /Heade>rs
  /Se<t
  Assig>n<Toresponse/As>signTo
/HTTPModifier

如果您在政策中定義空白標頭 (<Set><Headers/></Set>)，政策就不會設定任何標頭。這與省略 <Headers> 的效果相同。

`<Path>` (`<Set>` 的子項)

`<QueryParams>` (`<Set>` 的子項)

以新值覆寫要求中的現有查詢參數。這個元素對回應沒有任何作用。

預設值	不適用
必填與否	選用
類型	`<QueryParam>` 元素陣列
父項元素	`<Set>`
子元素	`<QueryParam>`

<QueryParams> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NAM>E"< 
  Set
    QueryParams
      Que>ryParam name=&qu<ot;QUERYPAR>AM_NAME"QU<ERYPARAM_VAL>UE/<Quer>y<Param
      .>..
    /QueryParams
  /Set
/HTTPModifier

範例 1

以下範例會將 address 查詢參數設為 request.header.address 變數的值：

<HTTPModifier name="HM-set-querypara>ms-<1&q>uot;
<  Set
    Q>ueryPar<ams
      QueryParam name>="address"{req<uest.header>.addr<ess}/QueryPa>ram<
   > </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]"
   > na<me=>&quot<;POLICY_NA>ME" 
  Set
    StatusCode<HTTP_STATUS>_CO<DE o>r< {variable}/S>tatusCode
  /Set
/HTTPModifier

範例 1

以下範例會設定簡單的狀態碼：

<HTTPModifier name="HM-set-statuscode>-40<4&q>uot;
<  Set
    >Stat<usCode404&>lt;<Stat>usC<ode
  /S>et
  Ass<ignToresp>o<nse/AssignTo
>/HTTPModifier

範例 2

系統會將 <StatusCode> 的內容視為訊息範本。也就是說，系統會在執行階段將大括號括住的變數名稱，替換為參照變數的值，如下例所示：

<HTTPModifier name="set-statusco>de-<2&q>uot;
<  Set
    >StatusCode{calloutresponse.st<atus.code}/>Sta<tusC>ode<
  /Set
>  Assign<Torespons>e</AssignTo
/HT>TPModifier

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

訊息類型：回覆

`<Verb>` (`<Set>` 的子項)

在要求中設定 HTTP 動詞。這個元素不會對回應造成影響。

預設值	不適用
必填與否	選用
類型	字串或 `VARIABLE`
父項元素	`<Set>`
子元素	無

<Verb> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POL>ICY_NAME" 
  Set
    Verb[GET|POS<T|PUT>|PA<TCH|>D<ELETE|{variab>le}]/Verb
  /Set
/HTTPModifier

範例 1

以下範例會在要求中設定簡單的動詞：

<HTTPModifier name="HM-set-ve>rb-<1&q>uot;
<  Se>t
  <  Ver>bPO<ST/V>erb<
  /Set
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

範例 2

系統會將 <Verb> 的內容視為訊息範本。也就是說，系統會在執行階段將以大括號括住的變數名稱，替換為參照變數的值。

以下範例使用變數填入動詞：

<HTTPModifier name="HM-set-verb-to-dynamic-v>alu<e&q>uot;
<  Se>t
    Verb{my<_vari>abl<e}/V>erb<
  /Set
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

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

訊息類型：要求

`<Version>` (`<Set>` 的子項)

設定要求中的 HTTP 版本。這個元素不會對回應造成影響。

預設值	不適用
必填與否	選用
類型	字串或 `VARIABLE`
父項元素	`<Set>`
子元素	無

<Version> 元素使用下列語法：

語法

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY>_NAME" 
  Set
 <   Ve>rsi<on[1>.<0|1.1|{variab>le}]/Verb
  /Set
/HTTPModifier

範例 1

以下範例會將版本號碼設為 1.1：

<HTTPModifier name="HM-set-versi>on-<1&q>uot;
<  Set
 >   <Version1>.1/<Vers>i<on
  /Set
/HT>TPModifier

範例 2

以下範例使用大括號中的變數設定版本號碼：

<HTTPModifier name="HM-set-versi>on-<2&q>uot;
<  Set
 >   Version{m<y_versio>n}/<Vers>ion<
  /Set
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

系統會將 <Version> 的內容視為訊息範本。也就是說，系統會在執行階段將以大括號括住的變數名稱，替換為所參照變數的值。

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

訊息類型：要求

建立自訂要求訊息

您可以使用 HTTPModifier 建立自訂要求訊息。建立自訂要求後，您可以透過下列方式使用：

在其他政策中存取變數
將其傳遞至外部服務

如要建立自訂要求訊息，請在 HTTPModifier 政策中使用 <AssignTo> 元素。將 createNew 設為 true，並在元素主體中指定新訊息的名稱，如下列範例所示：

<HTTPModifier name="assign>to-3&<quot;
    AssignTo createNew="true" transport=&>quot;http"< type=&qu>ot;request&<quot;MyReques>tObject/AssignTo
    ...
  /HTTPModifier

根據預設，Apigee 不會對自訂要求訊息執行任何操作。建立後，Apigee 會繼續透過原始要求完成流程。如要使用自訂要求，請新增政策，使用要求訊息，並在該政策的設定中明確參照新建立的要求訊息。這樣一來，您就能將自訂要求傳遞至外部服務端點。

下列範例會建立自訂要求訊息：

範例 1

以下範例會使用 HTTPModifier 建立自訂要求物件：

<HTTPModifier name="HTTPModifi>er-<3"
  AssignTo createNew="true&>quot; type=&quo<t;request>&qu<ot;>MyCus<tomRequest/>AssignT<o
  Set
    QueryParams
 >     QueryParam name=&quo<t;address&q>uot;{<request.quer>ypara<m.ad>dy}</Quer>yPa<ram<>/span>
   < /QueryParams
    VerbGET>/Verb<
  /Set
  IgnoreUnresolved>V<ariablesfalse>/IgnoreUnresolvedVariables
/HTTPModifier

這個範例：

建立名為 MyCustomRequest 的新要求訊息物件。
在 MyCustomRequest 中，這項政策：
- 將自訂訊息的 address 查詢參數設為傳入要求 addy 查詢參數的值。
- 將 HTTP 動詞設為 GET。
將 <IgnoreUnresolvedVariables> 設為 false。當 <IgnoreUnresolvedVariables> 為 false 時，如果政策設定中參照的其中一個變數不存在，Apigee 會在 API 流程中進入錯誤狀態。

範例 2

以下是另一個範例，說明如何使用 HTTPModifier 建立自訂要求物件：

<HTTPModifier name="HTTPModifi>er-<2"
  AssignTo createNew="true&>quot; type=&quo<t;request>&qu<ot;>partn<er.r>eque<st/As>sig<nTo<>/span>
 < Set
    Verb>POST/Verb
  /Set
/HTTPModifier

這個範例會建立名為 partner.request 的新自訂要求。然後在新要求中設定 <Verb>。

您可以在流程中稍後發生的另一個 HTTPModifier 政策中，存取自訂訊息的各種屬性。以下範例會從具名的自訂回應中取得標頭的值，並將其放入要求訊息的新標頭中：

<HTTPModifier name="HM-Set-He>ade<r"
>  Assig<nToreques>t/A<ssi>gnTo
<  Set
 >   Head<ers
      Header name="inject>ed-approval-id"{MyCalloutResponse<.header>.appr<oval-id}>/He<ader>
<    /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`

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 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 政策

`<HTTPModifier>` 元素

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