您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info
結果
在 API Proxy 流程中,AssignMessage 政策會變更或建立新的要求和回應訊息。 這項政策可讓您對這些郵件執行下列動作:
使用 AssignMessage 政策時,您通常會新增、變更或移除要求或回應的屬性。不過,您也可以使用 AssignMessage 政策建立自訂要求或回應訊息,並將其傳遞至替代目標,詳情請參閱「建立自訂要求訊息」。
AssignMessage 政策可透過下列子項元素建立或變更流程變數:
<AssignMessage>
元素
定義 AssignMessage 政策。
預設值 | 請參閱下方的「預設政策」分頁 |
必填與否 | 必填 |
類型 | 複雜物件 |
父項元素 | 不適用 |
子元素 |
<Add> <AssignTo> <AssignVariable> <Copy> <DisplayName> <IgnoreUnresolvedVariables> <Remove> <Set> |
<AssignMessage>
元素使用下列語法:
語法
<AssignMessage>
元素使用下列語法:
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <!-- All AssignMessage child elements are optional --> <Add> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> <Headers> <Header name="header_name">header_value</Header> ... </Headers> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> </Add> <AssignTo createNew="[true|false]" transport="http" type="[request|response]">destination_variable_name</AssignTo> <AssignVariable> <Name>variable_name</Name> <Ref>source_variable</Ref> <Template>message_template</Template> or <Template ref='template_variable'></Template> <Value>variable_value</Value> </AssignVariable> <Copy source="[request|response]"> <!-- Can also be an empty array (<FormParams/>) --> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> <!-- Can also be an empty array (<Headers/>) --> <Headers> <Header name="header_name">header_value</Header> ... </Headers> <Path>[false|true]</Path> <Payload>[false|true]</Payload> <!-- Can also be an empty array (<QueryParams/>) --> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> <ReasonPhrase>[false|true]</ReasonPhrase> <StatusCode>[false|true]</StatusCode> <Verb>[false|true]</Verb> <Version>[false|true]</Version> </Copy> <DisplayName>policy_display_name</DisplayName> <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables> <Remove> <!-- Can also be an empty array (<FormParams/>) --> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> <!-- Can also be an empty array (<Headers/>) --> <Headers> <Header name="header_name">header_value</Header> ... </Headers> <Payload>[false|true]</Payload> <!-- Can also be an empty array (<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> <Payload contentType="content_type" variablePrefix="prefix" variableSuffix="suffix">new_payload</Payload> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase> <StatusCode>HTTP_status_code or {variable}</StatusCode> <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb> <Version>[1.0|1.1|{variable}]</Verb> </Set> </AssignMessage>
預設政策
以下範例顯示在 Edge UI 中將 AssignMessage 政策新增至流程時的預設設定:
<AssignMessage continueOnError="false" enabled="true" name="assign-message-default"> <DisplayName>Assign Message-1</DisplayName> <Properties/> <Copy source="request"> <Headers/> <QueryParams/> <FormParams/> <Payload/> <Verb/> <StatusCode/> <ReasonPhrase/> <Path/> </Copy> <Remove> <Headers> <Header name="h1"/> </Headers> <QueryParams> <QueryParam name="q1"/> </QueryParams> <FormParams> <FormParam name="f1"/> </FormParams> <Payload/> </Remove> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <!-- <Verb>GET</Verb> --> <Path/> </Set> <AssignVariable> <Name>name</Name> <Value/> <Ref/> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
在 Edge UI 中插入新的 AssignMessage 政策時,範本會包含所有可能作業的存根。通常,您會選取要透過這項政策執行的作業,並移除其餘子元素。舉例來說,如要執行複製作業,請使用 <Copy>
元素,並從政策中移除 <Add>
、<Remove>
和其他子元素,讓政策更容易閱讀。
此元素在所有政策中皆包含下列屬性:
屬性 | 預設 | 必填與否 | Description |
---|---|---|---|
name |
無 | 必要 |
政策的內部名稱。 或者,您也可以使用 |
continueOnError |
false | 選填 | 如果設為「false」,當政策失敗時會傳回錯誤。多數政策預期的行為如下。如果設為「true」,則在政策失敗後,仍會繼續執行流程。 |
enabled |
true | 選填 | 設為「true」即可強制執行政策。將政策設為「false」,即可「關閉」政策。即使政策已附加至流程,系統也不會強制執行這項政策。 |
async |
false | 已淘汰 | 這項屬性已淘汰。 |
下表提供 <AssignMessage>
子元素的高階說明:
子元素 | 是否必要? | 說明 |
---|---|---|
常見作業 | ||
<Add> |
選用 | 將資訊新增至 <AssignTo> 元素指定的訊息物件。
|
<Copy> |
選用 | 將 source 屬性指定的訊息資訊複製到 <AssignTo> 元素指定的訊息物件。 |
<Remove> |
選用 | 從 <AssignTo> 元素中指定的訊息變數刪除指定元素。 |
<Set> |
選用 | 取代要求或回應中現有屬性的值,由 <AssignTo> 元素指定。
|
其他子元素 | ||
<AssignTo> |
選用 | 指定 AssignMessage 政策要處理的訊息。這可以是標準要求或回應,也可以是新的自訂訊息。 |
<AssignVariable> |
選用 | 為流程變數指派值。如果變數不存在,<AssignVariable> 會建立該變數。 |
<IgnoreUnresolvedVariables> |
選用 | 判斷遇到無法解析的變數時,是否停止處理。 |
後續章節將說明這些子元素。
範例
下列範例說明如何使用 AssignMessage 政策:
1:新增標頭
以下範例會使用 <Add>
元素,在要求中新增標頭:
<AssignMessage continueOnError="false" enabled="true" name="add-headers-1"> <Add> <Headers> <Header name="user-agent">{request.user.agent}</Header> </Headers> </Add> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
2:移除酬載
以下範例會使用 <Remove>
元素,從回應中刪除酬載:
<AssignMessage continueOnError="false" enabled="true" name="remove-1"> <DisplayName>remove-1</DisplayName> <Remove> <Payload>true</Payload> </Remove> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
3:修改回覆
以下範例會修改現有的回應物件,並在其中加入標頭:
<AssignMessage name="modify-response"> <Set> <Headers> <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header> </Headers> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignTo createNew="false" type="response"></AssignTo> </AssignMessage>
這個範例不會建立新訊息。而是透過新增 HTTP 標頭來修改現有的回應訊息。
由於這個範例省略 <AssignTo>
元素中的變數名稱,並將 type
指定為「response」,因此這項政策會修改目標伺服器傳回的回應物件。
這項政策新增至回應訊息的 HTTP 標頭,是衍生自 LookupCache 政策填入的變數。因此,經由這項「指派訊息」政策修改的回應訊息會包含 HTTP 標頭,指出結果是否已從快取中提取。在回應中設定標頭,有助於偵錯和疑難排解。
4:設定動態內容
您可以使用「指派訊息」,在回應和要求訊息的酬載中嵌入動態內容。
如要在 XML 酬載中嵌入 Edge 流程變數,請以大括號括住指定變數,例如:{prefix.name}
。
以下範例會將 user-agent
HTTP 標頭流程變數的值,嵌入名為 User-agent
的 XML 元素中:
<AssignMessage name="set-dynamic-content"> <AssignTo createNew="false" type="response"></AssignTo> <Set> <Payload contentType="text/xml"> <User-agent>{request.header.user-agent}</User-agent> </Payload> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
如果是 JSON 酬載,您可以使用 variablePrefix
和 variableSuffix
屬性插入變數,並以分隔符號字元分隔,如下列範例所示:
<AssignMessage name="set-payload"> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> { "user-agent": "@request.header.user-agent#" } </Payload> </AssignMessage>
如需流程變數的完整清單,請參閱流程變數參考資料。
自雲端版本 16.08.17 起,您也可以使用大括號插入變數。
5:移除查詢參數
以下範例會從要求中移除 apikey
查詢參數:
<AssignMessage name="remove-query-param"> <Remove> <QueryParams> <QueryParam name="apikey"/> </QueryParams> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
使用 VerifyAPIKey 政策進行使用者驗證時,最佳做法是從要求訊息中移除 apikey
查詢參數。這麼做是為了防止敏感金鑰資訊傳遞至後端目標。
6:設定/取得變數
以下範例使用三項「指派訊息」政策:
- 在要求中建立三個流程變數,並使用靜態值
- 在要求流程的第二項政策中動態取得流程變數
- 在回應的酬載中設定這些值
<!-- Policy #1: Set variables in the request --> <AssignMessage continueOnError="false" enabled="true" name="set-variables"> <!-- Create a variable named myAppSecret --> <AssignVariable> <Name>myAppSecret</Name> <Value>42</Value> </AssignVariable> <!-- Create a variable named config.environment --> <AssignVariable> <Name>config.environment</Name> <Value>test</Value> </AssignVariable> <!-- Create a variable named config.protocol --> <AssignVariable> <Name>config.protocol</Name> <Value>gopher</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
在第一個政策中,<AssignVariable>
元素會在要求中建立及設定三個變數。每個 <Name>
元素都會指定變數名稱,而 <Value>
則會指定值。
第二項政策會使用 <AssignVariable>
元素讀取值,並建立三個新變數:
<!-- Policy #2: Get variables from the request --> <AssignMessage continueOnError="false" enabled="true" name="get-variables"> <AssignTo createNew="false" transport="http" type="request"/> <!-- Get the value of myAppSecret and create a new variable, secret --> <AssignVariable> <Name>secret</Name> <Ref>myAppSecret</Ref> <Value>0</Value> </AssignVariable> <!-- Get the value of config.environment and create a new variable, environment --> <AssignVariable> <Name>environment</Name> <Ref>config.environment</Ref> <Value>default</Value> </AssignVariable> <!-- Get the value of config.protocol and create a new variable, protocol --> <AssignVariable> <Name>protocol</Name> <Ref>config.protocol</Ref> <Value>default</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </AssignMessage>
在第二項政策中,<Ref>
元素會參照來源變數,而 <Name>
元素則會指定新變數的名稱。如果 <Ref>
元素參照的變數無法存取,可以使用 <Value>
元素指定的值。
如要試用這組政策:
- 將政策 #1 和 #2 新增至要求流程。請務必將政策 1 放在政策 2 之前。
- 在回覆流程中新增第三項政策。
- 第三項政策會使用
<Set>
元素,將變數新增至回應。以下範例會在 Edge 傳回給用戶端的回應中建構 XML 酬載:<!-- Policy #3: Add variables to the response --> <AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload"> <DisplayName>put-em-in-the-payload</DisplayName> <Set> <Payload contentType="application/xml"> <wrapper> <secret>{secret}</secret> <config> <environment>{environment}</environment> <protocol>{protocol}</protocol> </config> </wrapper> </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
請注意,在
<Set>
中存取流程變數的語法,是將變數包在半形大括號中。請務必將
<Payload>
元素的contentType
屬性設為「application/xml」。 - 傳送要求至 API Proxy,例如:
curl -vL https://ahamilton-eval-test.apigee.net/myproxy
您可以選擇透過
xmllint
等公用程式傳送結果,讓 XML 以格式良好的結構顯示:curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -
回應主體應如下所示:
<wrapper> <secret>42</secret> <config> <environment>test</environment> <protocol>gopher</protocol> </config> </wrapper>
7:取得服務呼叫回應標頭
在下列範例中,假設 API Proxy 要求中有 ServiceCallout 政策,且呼叫回應包含多個同名標頭 (Set-Cookie
)。假設服務呼叫的回應變數是預設的 calloutResponse
,下列政策會取得第二個 Set-Cookie
標頭值。
<AssignMessage continueOnError="false" enabled="true" name="get-header"> <Set> <Payload contentType="application/json"> {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"} </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
如要列出所有標頭值,請改用下列變數:
{calloutResponse.header.Set-Cookie.values}
本參考資料中的每個子元素都有額外範例。如需更多範例,請參閱 GitHub 上的「AssignMessage 範例」。
子元素參照
本節說明 <AssignMessage>
的子元素。
<Add>
將資訊新增至要求或回應,由 <AssignTo>
元素指定。
<Add>
元素會在郵件中新增原始郵件沒有的屬性。如要變更現有屬性的值,請使用 <Set>
元素。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 複雜型別 |
父項元素 |
<AssignMessage>
|
子元素 |
<FormParams> <Headers> <QueryParams> |
<Add>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Add> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> <Headers> <Header name="header_name">header_value</Header> ... </Headers> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> </Add> </AssignMessage>
範例 1
下列範例使用 <FormParams>
元素,從初始要求取得三個查詢字串參數的值,並將這些值設為目標端點要求的表單參數:
<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3"> <Add> <FormParams> <FormParam name="name">{request.queryparam.name}</FormParam> <FormParam name="zip">{request.queryparam.zipCode}</FormParam> <FormParam name="lang">{request.queryparam.lang}</FormParam> </FormParams> </Add> <AssignTo transport="http" type="request"/> </AssignMessage>
範例 2
以下範例使用 <Headers>
元素,將 User-Agent
標頭新增至目標端點要求:
<AssignMessage continueOnError="false" enabled="true" name="add-headers-1"> <Add> <Headers> <Header name="user-agent">{request.user.agent}</Header> </Headers> </Add> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
範例 3
下列範例使用 <QueryParams>
元素,在要求中新增具有靜態值的單一查詢參數:
<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1"> <Add> <QueryParams> <QueryParam name="myParam">42</QueryParam> </QueryParams> </Add> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
本範例在要求前置流程中使用 <Add>
。如果您在 Trace 工具等工具中查看結果,對「http://httpbin.org/get」的要求會變成「http://httpbin.org/get?myParam=42」。
<Add>
的子項元素支援動態字串替換,也就是訊息範本。
<FormParams>
(<Add>
的子項)
在要求訊息中新增表單參數。這個元素不會對回覆訊息造成影響。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <FormParam> 元素陣列 |
父項元素 |
<Add>
|
子元素 |
<FormParam> |
<FormParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Add> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> <AssignTo createNew="[true|false]" transport="http" type="[request|response]">destination_variable_name</AssignTo> </Add> </AssignMessage>
範例 1
以下範例會將單一表單參數 (「answer」) 和靜態值 (「42」) 新增至要求:
<AssignMessage continueOnError="false" enabled="true" name="add-formparams-1"> <Add> <FormParams> <FormParam name="answer">42</FormParam> </FormParams> </Add> <AssignTo transport="http" type="request"></AssignTo> </AssignMessage>
範例 2
以下範例會取得 name
查詢字串參數的值,並將其做為表單參數新增至要求:
<AssignMessage continueOnError="false" enabled="true" name="add-formparams-2"> <Add> <FormParam name="name">{request.queryparam.name}</FormParam> </Add> </AssignMessage>
請注意,這個範例並未指定 <AssignTo>
的目標。這項政策只會在要求中加入
參數。
範例 3
以下範例會在要求中新增多個表單參數:
<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3"> <Add> <FormParams> <FormParam name="name">{request.queryparam.name}</FormParam> <FormParam name="zip">{request.queryparam.zipCode}</FormParam> <FormParam name="lang">{request.queryparam.lang}</FormParam> </FormParams> </Add> <AssignTo transport="http" type="request"/> </AssignMessage>
這個範例會從原始要求取得查詢字串參數,並將這些參數新增為表單參數,傳送至目標端點的要求中。
您可以使用追蹤工具查看流程。您會發現要求主體包含網址編碼的表單資料,這些資料原本是以查詢字串參數的形式傳遞:
%7Busername%7D=nick&%7Bzip_code%7D=90210&%7Bdefault_language%7D=en
只有在符合下列條件時,才能使用 <FormParams>
:
- HTTP 動詞:POST
- 訊息類型:要求
- 下列其中一項 (或兩項):
- 表單資料:設為某個值,或「」(空字串)。舉例來說,使用
curl
時,請在要求中加入-d ""
。 Content-Length
標頭:設為 0 (如果原始要求中沒有資料;否則為目前的長度,以位元組為單位)。舉例來說,您可以在要求中加入curl
,然後新增-H "Content-Length: 0"
。
- 表單資料:設為某個值,或「」(空字串)。舉例來說,使用
例如:
curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded" https://ahamilton-eval-test.apigee.net/am-test
新增 <FormParams>
後,Edge 會將要求標頭的 Content-Type
設為「application/x-www-form-urlencoded」,然後再將訊息傳送至目標服務。
<Headers>
(<Add>
的子項)
為 <AssignTo>
元素指定的特定要求或回應新增標頭。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <Header> 元素陣列 |
父項元素 |
<Add>
|
子元素 |
<Header> |
<Headers>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Add> <Headers> <Header name="header_name">header_value</Header> ... </Headers> </Add> </AssignMessage>
範例 1
以下範例會在要求訊息中新增 user-agent
標頭,並將 request.user.agent
流程變數的值指派給該標頭。
<AssignMessage continueOnError="false" enabled="true" name="add-headers-1"> <Add> <Headers> <Header name="user-agent">{request.user.agent}</Header> </Headers> </Add> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
<QueryParams>
(<Add>
的子項)
在要求中新增查詢參數。這個元素不會影響回覆。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <QueryParam> 元素陣列 |
父項元素 |
<Add>
|
子元素 |
<QueryParam> |
<QueryParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Add> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> </Add> </AssignMessage>
範例 1
以下範例會將查詢參數「myParam」新增至要求,並將值「42」指派給該參數:
<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1"> <Add> <QueryParams> <QueryParam name="myParam">42</QueryParam> </QueryParams> </Add> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
只有在符合下列條件時,才能使用 <QueryParams>
:
- HTTP 動詞:GET
- 訊息類型:要求
此外,只有在 <AssignTo>
元素的 type
屬性為要求訊息時,才能設定查詢參數。在回應中設定這些標頭不會產生任何影響。
如果在政策中定義空白的查詢參數陣列 (<Add><QueryParams/></Add>
),政策就不會新增任何查詢參數。這與省略 <QueryParams>
的效果相同。
<AssignTo>
決定 AssignMessage 政策要處理的物件。可採用的選項包括:
請注意,在某些情況下,您無法變更 AssignMessage 政策作用的物件。
舉例來說,您無法使用 <Add>
或 <Set>
在回應中新增或變更查詢參數 (<QueryParams>
) 或表單參數 (<FormParams>
)。您只能在要求中操控查詢參數和表單參數。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串 |
父項元素 |
<AssignMessage>
|
子元素 | 無 |
如未指定 <AssignTo>
,政策會根據政策的執行位置,對預設要求或回應採取行動。如果政策在要求流程中執行,就會影響要求訊息。如果是在回應流程中執行,這項政策預設會影響回應。
<AssignTo>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <AssignTo createNew="[true|false]" transport="http" type="[request|response]">destination_variable_name</AssignTo> </AssignMessage>
範例 1
以下範例指定目標為將傳送至目標端點的原始要求:
<AssignMessage name="assignto-1"> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
將 createNew
設為「false」(預設值) 時,這個範例不會建立新要求。這項政策中的所有作業都會影響原始要求。
範例 2
以下範例會建立新的要求物件:
<AssignMessage name="assignto-2"> <AssignTo createNew="true" transport="http" type="request"/> </AssignMessage>
建立新的要求或回應物件時,AssignMessage 政策的其他元素 (例如 <Add>
、<Set>
和 <Set>
) 會對該新要求物件採取行動。
您可以在流程中稍後存取其他政策中的新要求物件,也可以使用 ServiceCallout 政策將新要求物件傳送至外部服務。
範例 3
以下範例會建立名為「MyRequestObject」的新要求物件:
<AssignMessage name="assignto-2"> <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo> </AssignMessage>
建立新的要求或回應物件時,AssignMessage 政策的其他元素 (例如 <Add>
、<Set>
和 <Set>
) 會對該新要求物件採取行動。
您可以在流程中稍後存取其他政策中的新要求物件,也可以使用 ServiceCallout 政策將新要求物件傳送至外部服務。
下表說明 <AssignTo>
的屬性:
屬性 | 說明 | 是否必要? | 類型 |
---|---|---|---|
createNew |
決定這項政策是否會在指派值時建立新訊息。 如果設為「true」,政策就會建立 如果為「false」,政策會採取下列其中一種做法:
如果未指定
|
選用 | 布林值 |
transport |
指定要求或回應訊息類型的傳輸類型。 預設值為「http」(唯一支援的值)。 |
選用 | 字串 |
type |
當 createNew 為「true」時,指定新訊息的類型。有效值為「request」或「response」。預設值為「request」。如果省略這個屬性,Edge 會視政策在流程中的執行位置,建立要求或回應。 |
選用 | 字串 |
<AssignVariable>
為目的地流程變數指派值 (例如,值是由 AssignMessage 政策設定的變數)。如果流程變數不存在,<AssignVariable>
會建立該變數。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 複雜型別 |
父項元素 |
<AssignMessage>
|
子元素 |
<Name> (必填)<Ref> <Template> <Value> |
指派給目的地流程變數的值可以是下列其中一項:
- 字串常值:使用
<Value>
子項元素,為目的地流程變數指定字串常值。 - 流程變數:使用
<Ref>
子項元素,為目的地流程變數指定現有流程變數的值。如需可用做來源的流程變數完整清單,請參閱流程變數參考資料。 - 訊息範本:使用
<Template>
子項元素,為目的地流程變數指定訊息範本。
<AssignVariable>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <AssignVariable> <Name>variable_name</Name> <Ref>source_variable</Ref> <Template>message_template</Template> or <Template ref='template_variable'></Template> <Value>variable_value</Value> </AssignVariable> </AssignMessage>
使用 <Ref>
元素指定來源變數。如果 Edge 無法存取 <Ref>
參照的變數,就會使用 <Value>
元素指定的值。如果定義
<Template>
,系統會優先採用這個元素,而非其他子元素。
範例 1
以下範例會將新變數 myvar
的值設為字面值「42」:
<AssignMessage name="assignvariable-1"> <AssignVariable> <Name>myvar</Name> <Value>42</Value> </AssignVariable> </AssignMessage>
範例 2
以下範例會將流程變數 request.header.user-agent
的值指派給目的地流程變數 myvar
,並將查詢參數 country
的值指派給目的地流程變數 Country
:
<AssignMessage name="assignvariable-2"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> </AssignMessage>
如果任一指派作業失敗,Edge 會改為將「ErrorOnCopy」值指派給目的地流程變數。
如果 myvar
或 Country
流程變數不存在,<AssignVariable>
會建立這些變數。
範例 3
以下範例使用 <Template>
子項元素,串連兩個內容變數,並在兩者之間加入字串常值 (連字號):
<AssignMessage name='template-1'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Value>BADDBEEF</Value> <Template>{system.uuid}-{messageid}</Template> </AssignVariable> </AssignMessage>
<AssignVariable>
的常見用途是為查詢參數、標頭或其他可隨要求傳遞的值設定預設值。您可以使用 <Ref>
和 <Value>
子項元素組合來執行這項操作。詳情請參閱 <Ref>
的範例。
<Name>
(<AssignVariable>
的子項)
指定目的地流程變數的名稱 (例如,值是由 AssignMessage 政策設定的變數)。如果 <AssignVariable>
中指定的變數不存在,政策會建立該名稱的變數。
預設值 | 不適用 |
必填與否 | 必填 |
類型 | 字串 |
父項元素 |
<AssignVariable>
|
子元素 | 無 |
<Name>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <AssignVariable> <Name>variable_name</Name> </AssignVariable> </AssignMessage>
範例 1
以下範例將目的地變數指定為 myvar
,並將其設為字面值「42」:
<AssignMessage name="assignvariable-1"> <AssignVariable> <Name>myvar</Name> <Value>42</Value> </AssignVariable> </AssignMessage>
如果 myvar
不存在,<AssignVariable>
會建立該檔案。
<Ref>
(<AssignVariable>
的子項)
以流程變數形式指定指派作業的來源。流程變數可以是預先定義的流程變數 (如「流程變數參考資料」所列),也可以是您建立的自訂流程變數。
<Ref>
的值一律會解譯為流程變數,您無法指定常值字串做為值。如要指派字串值,請改用 <Value>
元素。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串 |
父項元素 |
<AssignVariable>
|
子元素 | 無 |
使用 <Ref>
指定流程變數時,請省略通常用於參照流程變數的封閉式大括號「{}」。舉例來說,如要將新變數的值設為 client.host
流程變數的值,請執行下列操作:
Do this (no brackets): <Ref>client.host</Ref> Do NOT do this (brackets): <Ref>{client.host}</Ref>
如要為目的地流程變數定義預設值,請搭配使用 <Value>
和 <Ref>
。如果 <Ref>
指定的流程變數不存在、無法讀取或為空值,Edge 會改為將 <Value>
的值指派給目的地流程變數。
<Ref>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <AssignVariable> <Name>variable_name</Name> <Ref>source_variable</Ref> </AssignVariable> </AssignMessage>
範例 1
以下範例會將流程變數 request.header.user-agent
的值指派給目的地流程變數 myvar
,並將查詢參數 country
的值指派給 Country
變數:
<AssignMessage name="assignvariable-4"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> </AssignVariable> </AssignMessage>
在本範例中,Edge 並未指定任何指派作業的預設值 (或備用值)。
範例 2
以下範例會將流程變數 request.header.user-agent
的值指派給目的地流程變數 myvar
,並將查詢參數 country
的值指派給 Country
變數:
<AssignMessage name="assignvariable-2"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> </AssignMessage>
在本例中,如果 request.header.user-agent
流程變數或 Country
查詢參數的值為空值、無法讀取或格式錯誤,Edge 會將「ErrorOnCopy」值指派給新變數。
範例 3
<AssignVariable>
的常見用途是設定查詢參數、標頭或其他可隨要求傳入的值的預設值。舉例來說,您建立的天氣 API Proxy 要求會採用名為「w」的單一查詢參數。這個參數包含您想查詢天氣的城市 ID。要求網址的格式如下:
http://myCO.com/v1/weather/forecastrss?w=city_ID
如要為「w」定義預設值,請建立類似下列的 AssignMessage 政策:
<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3"> <AssignTo createNew="false" transport="http" type="request"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignVariable> <Name>request.queryparam.w</Name> <Ref>request.queryparam.w</Ref> <Value>12797282</Value> </AssignVariable> </AssignMessage>
在本例中,<AssignVariable>
會取得 request.queryparam.w
的值,並將該值指派給自己。如果流程變數為空值,表示要求中省略了「w」查詢參數,則這個範例會使用 <Value>
元素的預設值。因此,您可以向這個 API 代理提出要求,省略「w」查詢參數:
http://myCO.com/v1/weather/forecastrss
並讓 API Proxy 傳回有效結果。
與使用 <Value>
不同,<Ref>
的值必須是流程變數,例如 request
、response
或 target
物件的屬性。值也可以是您建立的自訂流程變數。
如果您為 <Ref>
的值指定不存在的流程變數,且 <IgnoreUnresolvedVariables>
的值為「true」,Edge 會擲回錯誤。
<Template>
(<AssignVariable>
的子項)
指定訊息範本。郵件範本可讓您在政策執行時執行變數字串替換作業,並將常值字串與以半形大括號括住的變數名稱合併。此外,訊息範本也支援逸出和大小寫轉換等函式。
使用 ref
屬性指定流程變數,其中變數的值是訊息範本。舉例來說,您可以在開發人員應用程式上將訊息範本儲存為自訂屬性。當 Edge 驗證 API 金鑰或安全權杖 (透過額外政策) 後識別出開發人員應用程式時,<AssignVariable>
元素可以使用應用程式自訂屬性的訊息範本,該範本可做為安全政策的流程變數。以下範例假設訊息範本位於開發人員應用程式的 message_template
客戶屬性中,該應用程式會發出 API 呼叫,且 VerifyAPIKey 政策已用於驗證應用程式的 API 金鑰:
<AssignVariable ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串 |
父項元素 |
<AssignVariable>
|
子元素 | 無 |
<Template>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <AssignVariable> <Template>message_template</Template> or <Template ref='template_variable'></Template> </AssignVariable> </AssignMessage>
範例 1
以下範例使用訊息範本語法,將兩個環境變數與中間的字串常值 (連字號) 串連在一起:
<AssignMessage name='template-1'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Value>BADDBEEF</Value> <Template>{system.uuid}-{messageid}</Template> </AssignVariable> </AssignMessage>
範例 2
以下範例會指定流程變數,其中變數值是預先定義的訊息範本。如要在執行階段插入預先定義的範本,而不必修改政策,請使用這個選項:
<AssignMessage name='template-2'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Value>BADDBEEF</Value> <Template ref='my_template_variable'/> </AssignVariable> </AssignMessage>
範例 3
以下範例會指定流程變數和文字值。在這種情況下,如果參照的變數不是空值,系統會將該值做為範本。如果參照的值為空值,則會使用文字值 (本例中為 {system.uuid}-{messageid}
) 做為範本。這個模式可用於提供「覆寫」值,在某些情況下,您會想以動態設定的值覆寫預設範本 (文字部分)。舉例來說,條件陳述式可能會從鍵/值對應中擷取值,並將參照的變數設為該值:
<AssignMessage name='template-2'> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignVariable> <Name>my_destination_variable</Name> <Value>BADDBEEF</Value> <Template ref='my_variable'>{system.uuid}-{messageid}</Template> </AssignVariable> </AssignMessage>
<Value>
(<AssignVariable>
的子項)
定義以 <AssignVariable>
設定的目的地流程變數值。系統一律會將值解讀為字串常值,即使將值括在方括號 ("{}") 中,也無法使用流程變數做為值。如要使用流程變數,請改用 <Ref>
。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串 |
父項元素 |
<AssignVariable>
|
子元素 | 無 |
與 <Ref>
元素搭配使用時,<Value>
會做為預設 (或備用) 值。如果未指定 <Ref>
、無法解析或為空值,則會使用 <Value>
的值。
<Value>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <AssignVariable> <Name>variable_name</Name> <Value>variable_value</Value> </AssignVariable> </AssignMessage>
範例 1
以下範例會將目的地流程變數 myvar
的值設為字面值「42」:
<AssignMessage name="assignvariable-1"> <AssignVariable> <Name>myvar</Name> <Value>42</Value> </AssignVariable> </AssignMessage>
範例 2
以下範例會將流程變數 request.header.user-agent
的值指派給流程變數 myvar
,並將查詢參數 country
的值指派給 Country
變數:
<AssignMessage name="assignvariable-2"> <AssignVariable> <Name>myvar</Name> <Ref>request.header.user-agent</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>Country</Name> <Ref>request.queryparam.country</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> </AssignMessage>
如果任一指派作業失敗,<AssignVariable>
會改為將「ErrorOnCopy」值指派給目的地流程變數。
<Copy>
將 source
屬性指定的訊息值複製到 <AssignTo>
元素指定的訊息。如果您未指定 <AssignTo>
的目標,這項政策會將值複製到要求或回應,視政策在流程中的執行位置而定。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串 |
父項元素 |
<AssignMessage>
|
子元素 |
<FormParams> <Headers> <Path> <Payload> <QueryParams> <ReasonPhrase> <StatusCode> <Verb> <Version> |
<Copy>
元素使用下列語法:
語法
<AssignMessage
continueOnError="[false|true]"
enabled="[true|false]"
name="policy_name" >
<Copy source="[request|response]">
<!-- Can also be an empty array (<FormParams/>) -->
<FormParams>
<FormParam name="formparam_name">formparam_value</FormParam>
...
</FormParams>
<!-- Can also be an empty array (<Headers/>) -->
<Headers>
<Header name="header_name">header_value</Header>
...
</Headers>
<Path>[false|true]</Path>
<Payload>[false|true]</Payload>
<!-- Can also be an empty array (<QueryParams/>) -->
<QueryParams>
<QueryParam name="queryparam_name">queryparam_value</QueryParam>
...
</QueryParams>
<ReasonPhrase>[false|true]</ReasonPhrase>
<StatusCode>[false|true]</StatusCode>
<Verb>[false|true]</Verb>
<Version>[false|true]</Version>
</Copy>
<!-- Used as the destination for the <Copy>
values -->
<AssignTo createNew="[true|false]" transport="http"
type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>
範例 1
以下範例會將標頭、三個表單參數、路徑和所有查詢參數從要求複製到新的自訂要求:
<AssignMessage continueOnError="false" enabled="true" name="copy-1"> <Copy source="request"> <Headers> <Header name="Header_Name_1">Header value 1</Header> </Headers> <FormParams> <FormParam name="Form_Param_Name_1">Form param value 1</FormParam> <FormParam name="Form_Param_Name_2">Form param value 1</FormParam> <FormParam name="Form_Param_Name_3">Form param value 1</FormParam> </FormParams> <Payload>false</Payload> <Path>true</Path> <QueryParams/> <ReasonPhrase>false</ReasonPhrase> <StatusCode>false</StatusCode> <Verb>false</Verb> <Version>false</Version> </Copy> <AssignTo createNew="true" transport="http" type="request"/> </AssignMessage>
<Copy>
元素的屬性如下:
屬性 | 說明 | 是否必要? | 類型 |
---|---|---|---|
來源 |
指定副本的來源物件。
|
選用 | 字串 |
<FormParams>
(<Copy>
的子項)
從 <Copy>
元素的 source
屬性指定的請求中,將表單參數複製到 <AssignTo>
元素指定的請求。這個元素不會影響回應。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <FormParam> 元素陣列或空陣列 |
父項元素 |
<Copy>
|
子元素 |
<FormParam> |
<FormParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <!-- Can also be an empty array (<FormParams/>) --> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> </Copy> </AssignMessage>
範例 1
以下範例會將要求中的單一表單參數複製到自訂要求「MyCustomRequest」:
<AssignMessage name="copy-formparams-1"> <Copy source="request"> <FormParams> <FormParam name="paramName">Form param value 1</FormParam> </FormParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
範例 2
以下範例會將所有表單參數複製到自訂要求「MyCustomRequest」:
<AssignMessage name="copy-formparams-2"> <Copy source="request"> <FormParams/> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
範例 3
以下範例會將三個表單參數複製到自訂要求「MyCustomRequest」:
<AssignMessage name="copy-formparams-3"> <Copy source="request"> <FormParams> <FormParam name="paramName1"/> <FormParam name="paramName2"/> <FormParam name="paramName3"/> </FormParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
示例 4
如果有多個表單參數的名稱相同,請使用下列語法:
<AssignMessage name="copy-formparams-4"> <Copy source="request"> <FormParams> <FormParam name="f1"/> <FormParam name="f2"/> <FormParam name="f3.2"/> </FormParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
這個範例會複製「f1」、「f2」和「f3」的第二個值。如果「f3」只有一個值,系統就不會複製。
只有在符合下列條件時,才能使用 <FormParams>
:
- HTTP 動詞:POST
- 訊息類型:回覆
- 下列其中一項 (或兩項):
- 表單資料:設為某個值,或「」(空字串)。舉例來說,使用
curl
時,請在要求中加入-d ""
。 Content-Length
標頭:設為 0 (如果原始要求中沒有資料,否則為目前的長度)。舉例來說,您可以在要求中加入curl
,然後新增-H "Content-Length: 0"
。
- 表單資料:設為某個值,或「」(空字串)。舉例來說,使用
當您複製 <FormParams>
時,<Copy>
會在將訊息傳送至目標服務前,將訊息的 Content-Type
設為「application/x-www-form-urlencoded」。
<Headers>
(<Copy>
的子項)
將 <Copy>
元素 source
屬性指定的 HTTP 標頭,複製到 <AssignTo>
元素指定的要求或回應訊息。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <Header> 元素陣列或空陣列 |
父項元素 |
<Copy>
|
子元素 |
<Header> |
<Headers>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <!-- Can also be an empty array (<Headers/>) --> <Headers> <Header name="header_name">header_value</Header> ... </Headers> </Copy> </AssignMessage>
範例 1
以下範例會將要求中的 user-agent
標頭複製到新的自訂要求物件:
<AssignMessage name="copy-headers-1"> <Copy source="request"> <Headers> <Header name="user-agent"/> </Headers> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
範例 2
如要複製所有標頭,請使用空白的 <Headers>
元素,如下列範例所示:
<AssignMessage name="copy-headers-2"> <Copy source="request"> <Headers/> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
範例 3
如果有多個同名標頭,請使用下列語法:
<AssignMessage name="copy-headers-3"> <Copy source="request"> <Headers> <Header name="h1"/> <Header name="h2"/> <Header name="h3.2"/> </Headers> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
這個範例會複製「h1」、「h2」和「h3」的第二個值。如果「h3」只有一個值,系統就不會複製。
<Path>
(<Copy>
的子項)
決定是否應將路徑從來源要求複製到目的地要求。這個元素不會影響回覆。
如果設為「true」,這項政策會將 <Copy>
元素 source
屬性指定的路徑,從要求訊息複製到 <AssignTo>
元素指定的要求訊息。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<Copy>
|
子元素 | 無 |
<Path>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <Path>[false|true]</Path> </Copy> </AssignMessage>
範例 1
以下範例指出 AssignMessage 政策應將路徑從來源要求複製到新的自訂要求物件:
<AssignMessage name="copy-path-1"> <Copy source="request"> <Path>true</Path> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
只有在符合下列條件時,才能使用 <Path>
:
- 訊息類型:要求
<Payload>
(<Copy>
的子項)
決定是否要將酬載從來源複製到目的地。 來源和目的地可以是要求或回應。
如果為「true」,這項政策會將酬載從 <Copy>
元素的 source
屬性指定的訊息複製到 <AssignTo>
元素指定的訊息。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<Copy>
|
子元素 | 無 |
<Payload>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <Payload>[false|true]</Payload> </Copy> </AssignMessage>
範例 1
以下範例將 <Payload>
設為「true」,因此要求酬載會從要求複製到回應:
<AssignMessage name="copy-payload-1"> <Copy source="request"> <Payload>true</Payload> </Copy> <AssignTo createNew="true" transport="http" type="response"/> </AssignMessage>
<QueryParams>
(<Copy>
的子項)
將 <Copy>
元素 source
屬性指定的請求中的查詢字串參數複製到 <AssignTo>
元素指定的請求。這個元素不會影響回覆。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <QueryParam> 元素陣列或空陣列 |
父項元素 |
<QueryParam>
|
子元素 | 無 |
<QueryParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <!-- Can also be an empty array (<QueryParams/>) --> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> </Copy> </AssignMessage>
範例 1
以下範例會將要求中的「my_param」查詢參數複製到新的自訂要求物件:
<AssignMessage name="copy-queryparams-1"> <Copy source="request"> <QueryParams> <QueryParam name="my_param"/> </QueryParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
範例 2
以下範例會將要求中的所有查詢參數複製到新的自訂要求物件:
<AssignMessage name="copy-queryparams-2"> <Copy source="request"> <QueryParams/> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
範例 3
如果有多個同名的查詢參數,請使用下列語法:
<AssignMessage name="copy-queryparams-3"> <Copy source="request"> <QueryParams> <QueryParam name="qp1"/> <QueryParam name="qp2"/> <QueryParam name="qp3.2"/> </QueryParams> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
這個範例會複製「qp1」、「qp2」和「qp3」的第二個值。如果「qp3」只有一個值,就不會複製。
只有在符合下列條件時,才能使用 <QueryParams>
:
- HTTP 動詞:GET
- 訊息類型:要求
<ReasonPhrase>
(<Copy>
的子項)
決定是否應將原因片語從來源回應複製到目的地回應。這個元素不會對要求造成任何影響。
如果為「true」,這項政策會將 <Copy>
元素 source
屬性指定的 ReasonPhrase
從回應 複製到 <AssignTo>
元素指定的回應 中。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<Copy>
|
子元素 | 無 |
<ReasonPhrase>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <ReasonPhrase>[false|true]</ReasonPhrase> </Copy> </AssignMessage>
範例 1
下列範例將 <ReasonPhrase>
設為「true」,導致 <Copy>
將預設回應中的原因片語複製到自訂回應物件:
<AssignMessage name="copy-reasonphrase-1"> <Copy source="response"> <ReasonPhrase>true</ReasonPhrase> </Copy> <AssignTo createNew="trie" transport="http" type="response">MyCustomResponse</AssignTo> </AssignMessage>
只有在符合下列條件時,才能使用 <ReasonPhrase>
:
- 訊息類型:回覆
<StatusCode>
(<Copy>
的子項)
決定是否要將狀態碼從來源回應複製到目的地回應。這個元素不會對要求造成任何影響。
如果為「true」,這項政策會將 <Copy>
元素 source
屬性指定的 來源回應訊息狀態碼,複製到 <AssignTo>
元素指定的回應訊息。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<Copy>
|
子元素 | 無 |
<StatusCode>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <StatusCode>[false|true]</StatusCode> </Copy> </AssignMessage>
範例 1
下列範例會將 <StatusCode>
設為「true」,將狀態碼從預設回應物件複製到新的自訂回應物件:
<AssignMessage name="copy-statuscode-1"> <Copy source="response"> <StatusCode>true</StatusCode> </Copy> <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo> </AssignMessage>
只有在符合下列條件時,才能使用 <StatusCode>
:
- 訊息類型:回覆
<StatusCode>
的常見用途是確保 Proxy 回應與從目標收到的回應具有相同狀態,前提是 <AssignTo>
的 createNew
屬性設為「true」。
<Verb>
(<Copy>
的子項)
決定是否要將 HTTP 動詞從來源要求複製到目的地要求。這個元素不會影響回覆。
如果設為「true」,系統會將 <Copy>
元素 source
屬性中找到的動詞複製到 <AssignTo>
元素中指定的要求。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<Copy>
|
子元素 | 無 |
<Verb>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <Verb>[false|true]</Verb> </Copy> </AssignMessage>
範例 1
以下範例將 <Verb>
設為「true」,將預設要求中的動詞複製到新的自訂要求:
<AssignMessage name="copy-verb-1"> <Copy source="request"> <Verb>true</Verb> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
只有在符合下列條件時,才能使用 <Verb>
:
- 訊息類型:要求
<Version>
(<Copy>
的子項)
決定是否要將 HTTP 版本從來源要求複製到目的地要求。這個元素不會影響回覆。
如果為「true」,則會將 <Copy>
元素 source
屬性中的 HTTP 版本複製到 <AssignTo>
元素指定的物件。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<Copy>
|
子元素 | 無 |
<Version>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Copy source="[request|response]"> <Version>[false|true]</Version> </Copy> </AssignMessage>
範例 1
以下範例會在要求中將 <Version>
設為「true」,將預設要求物件中的版本複製到新的自訂要求物件:
<AssignMessage name="copy-version-1"> <Copy source="request"> <Version>true</Version> </Copy> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
只有在符合下列條件時,才能使用 <Version>
:
- 訊息類型:要求
<DisplayName>
除了 name
屬性之外,您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。
<DisplayName>
元素適用於所有政策。
預設值 | 不適用 |
是否必要? | 選用設定。如果省略 <DisplayName> ,系統會使用政策的 name 屬性值 |
類型 | 字串 |
上層元素 | <PolicyElement> |
子元素 | 無 |
<DisplayName>
元素使用以下語法:
語法
<PolicyElement> <DisplayName>policy_display_name</DisplayName> ... </PolicyElement>
範例
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
<DisplayName>
元素沒有屬性或子項元素。
<IgnoreUnresolvedVariables>
判斷遇到無法解析的變數時,是否停止處理。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<AssignMessage>
|
子元素 | 無 |
設為 true
可忽略未解析的變數並繼續處理;否則請設為 false
。預設值為 false
。
將 <IgnoreUnresolvedVariables>
設為 true
與將 <AssignMessage>
的 continueOnError
設為 true
不同,因為前者專門用於設定及取得變數值。如果將 continueOnError
設為 true
,Edge 會忽略所有錯誤,而不只是使用變數時遇到的錯誤。
<IgnoreUnresolvedVariables>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables> </AssignMessage>
範例 1
以下範例會將 <IgnoreUnresolvedVariables>
設為「true」:
<AssignMessage name="ignoreunresolvedvariables"> <Copy source="response"> ... <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </Copy> </AssignMessage>
<Remove>
從訊息中移除標頭、查詢參數、表單參數和/或訊息酬載。訊息可以是要求或回覆。使用 <AssignTo>
元素指定 <Remove>
要處理的訊息。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 複雜型別 |
父項元素 |
<AssignMessage>
|
子元素 |
<FormParams> <Headers> <Payload> <QueryParams> |
<Remove>
的常見用途是從傳入的要求物件中刪除含有私密資訊的查詢參數,避免將該參數傳遞至後端伺服器。
<Remove>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Remove> <!-- Can also be an empty array (<FormParams/>) --> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> <!-- Can also be an empty array (<Headers/>) --> <Headers> <Header name="header_name">header_value</Header> ... </Headers> <Payload>[false|true]</Payload> <!-- Can also be an empty array (<QueryParams/>) --> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> </Remove> </AssignMessage>
範例 1
以下範例會從回應中移除郵件內文:
<AssignMessage continueOnError="false" enabled="true" name="remove-1"> <DisplayName>remove-1</DisplayName> <Remove> <Payload>true</Payload> </Remove> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
在回應流程中,這項政策會移除回應主體,只將 HTTP 標頭傳回給用戶端。
範例 2
以下範例會從傳入的要求中移除所有表單參數和查詢參數:
<AssignMessage continueOnError="false" enabled="true" name="remove-2"> <Remove> <!-- Empty (<FormParams/>) removes all form parameters --> <FormParams/> <QueryParams> <QueryParam name="qp1"/> </QueryParams> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
<FormParams>
(<Remove>
的子項)
從要求中移除指定的表單參數。這個元素不會影響回應。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <FormParam> 元素陣列或空陣列 |
父項元素 |
<Remove>
|
子元素 |
<FormParam> |
<FormParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Remove> <!-- Can also be an empty array (<FormParams/>) --> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> </Remove> </AssignMessage>
範例 1
以下範例會從要求中移除三個表單參數:
<AssignMessage name="remove-formparams-1"> <Remove> <FormParams> <FormParam name="form_param_1"/> <FormParam name="form_param_2"/> <FormParam name="form_param_3"/> </FormParams> </Remove> <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/> </AssignMessage>
範例 2
以下範例會從要求中移除所有表單參數:
<AssignMessage name="remove-formparams-2"> <Remove> <FormParams/> </Remove> <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/> </AssignMessage>
範例 3
如果有多個表單參數的名稱相同,請使用下列語法:
<AssignMessage name="remove-formparams-3"> <Remove> <FormParams> <FormParam name="f1"/> <FormParam name="f2"/> <FormParam name="f3.2"/> </FormParams> </Remove> <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/> </AssignMessage>
這個範例會移除「f1」、「f2」和「f3」的第二個值。如果「f3」只有一個值,就不會移除。
只有在符合下列條件時,才能使用 <FormParams>
:
- 訊息類型:要求
Content-Type
:「application/x-www-form-urlencoded」
<Headers>
(<Remove>
的子項)
從要求或回應中移除指定 HTTP 標頭,由 <AssignTo>
元素指定。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <Header> 元素陣列或空陣列 |
父項元素 |
<Remove>
|
子元素 |
<Header> |
<Headers>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Remove> <!-- Can also be an empty array (<Headers/>) --> <Headers> <Header name="header_name">header_value</Header> ... </Headers> </Remove> </AssignMessage>
範例 1
以下範例會從要求中移除 user-agent
標頭:
<AssignMessage name="remove-headers-1"> <Remove> <Headers> <Header name="user-agent"/> </Headers> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
範例 2
以下範例會從要求中移除所有標頭:
<AssignMessage name="remove-headers-2"> <Remove> <Headers/> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
範例 3
如果有多個同名標頭,請使用下列語法:
<AssignMessage name="remove-headers-3"> <Remove> <Headers> <Header name="h1"/> <Header name="h2"/> <Header name="h3.2"/> </Headers> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
這個範例會從要求中移除「h1」、「h2」和「h3」的第二個值。如果「h3」只有一個值,則不會移除。
<Payload>
(<Remove>
的子項)
決定 <Remove>
是否要刪除要求或回應中的酬載,這由 <AssignTo>
元素指定。設為「true」可清除酬載,否則為「false」。預設值為「false」。
預設值 | 否 |
必填與否 | 選用 |
類型 | 布林值 |
父項元素 |
<Remove>
|
子元素 | 無 |
<Payload>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Remove> <Payload>[false|true]</Payload> </Remove> </AssignMessage>
範例 1
以下範例將 <Payload>
設為「true」,以便清除要求酬載:
<AssignMessage name="remove-payload-1"> <Remove> <Payload>true</Payload> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
<QueryParams>
(<Remove>
的子項)
從要求中移除指定的查詢參數。這個元素不會影響回應。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <QueryParam> 元素陣列或空陣列 |
父項元素 |
<Remove>
|
子元素 |
<QueryParam> |
<QueryParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Remove> <!-- Can also be an empty array (<QueryParams/>) --> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> </Remove> </AssignMessage>
範例 1
以下範例會從要求中移除單一查詢參數:
<AssignMessage name="remove-queryparams-1"> <Remove> <QueryParams> <QueryParam name="qp1"/> </QueryParams> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
範例 2
以下範例會從要求中移除所有查詢參數:
<AssignMessage name="remove-queryparams-2"> <Remove> <QueryParams/> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
範例 3
如果有多個同名的查詢參數,請使用下列語法:
<AssignMessage name="remove-queryparams-3"> <Remove> <QueryParams> <QueryParam name="qp1"/> <QueryParam name="qp2"/> <QueryParam name="qp3.2"/> </QueryParams> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
這個範例會從要求中移除「qp1」、「qp2」和「qp3」的第二個值。如果「qp3」只有一個值,則不會移除。
示例 4
以下範例會從要求中移除 apikey
查詢參數:
<AssignMessage name="remove-query-param"> <Remove> <QueryParams> <QueryParam name="apikey"/> </QueryParams> </Remove> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
只有在符合下列條件時,才能使用 <QueryParams>
:
- HTTP 動詞:GET
- 訊息類型:要求
<Set>
在要求或回應訊息中設定資訊,由 <AssignTo>
元素指定。<Set>
覆寫原始郵件中已有的標頭或參數。如要建立新的標頭或參數,請改用 <Add>
元素。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 複雜型別 |
父項元素 |
<AssignMessage>
|
子元素 |
<FormParams> <Headers> <Payload> <Path> <QueryParams> <ReasonPhrase> <StatusCode> <Verb> <Version> |
<Set>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> <Headers> <Header name="header_name">header_value</Header> ... </Headers> <Path>path</Path> <Payload contentType="content_type" variablePrefix="prefix" variableSuffix="suffix">new_payload</Payload> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase> <StatusCode>HTTP_status_code or {variable}</StatusCode> <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb> <Version>[1.0|1.1|{variable}]</Verb> </Set> </AssignMessage>
範例 1
以下範例顯示 <Set>
元素:
<AssignMessage continueOnError="false" enabled="true" name="set-1"> <Set> <FormParams> <FormParam name="myparam">{request.header.myparam}</FormParam> </FormParams> <Headers> <Header name="user-agent">{request.header.user-agent}</Header> </Headers> <QueryParams> <QueryParam name="name">{request.header.name}</QueryParam> <QueryParam name="address">{request.header.address}</QueryParam> </QueryParams> <!-- <Verb>GET</Verb> --> <Payload contentType="text/plain">42</Payload> <Path/> <ReasonPhrase>Bad request</ReasonPhrase> <StatusCode>400</StatusCode> <Verb>POST</Verb> <Verb>{my_variable}</Verb> <Version>1.1</Version> </Set> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
<FormParams>
(<Set>
的子項)
覆寫要求中現有的表單參數,並以您透過這個元素指定的新值取代。這個元素不會影響回覆。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <FormParam> 元素陣列 |
父項元素 |
<Set>
|
子元素 |
<FormParam> |
<FormParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <FormParams> <FormParam name="formparam_name">formparam_value</FormParam> ... </FormParams> </Set> </AssignMessage>
範例 1
以下範例會在新自訂要求中,將名為「myparam」的表單參數設為 request.header.myparam
變數的值:
<AssignMessage name="set-formparams-1"> <Set> <FormParams> <FormParam name="myparam">{request.header.myparam}</FormParam> </FormParams> </Set> <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo> </AssignMessage>
只有在符合下列條件時,才能使用 <FormParams>
:
- HTTP 動詞:POST
- 訊息類型:要求
如果您在政策 (<Add><FormParams/></Add>
) 中定義空白表單參數,政策不會新增任何表單參數。這與省略 <FormParams>
的效果相同。
<Set>
會將訊息的 Content-Type
變更為「application/x-www-form-urlencoded」,然後再傳送至目標端點。
<Headers>
(<Set>
的子項)
覆寫要求或回應中現有的 HTTP 標頭,由 <AssignTo>
元素指定。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <Header> 元素陣列 |
父項元素 |
<Set>
|
子元素 |
<Header> |
<Headers>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <Headers> <Header name="header_name">header_value</Header> ... </Headers> </Set> </AssignMessage>
範例 1
以下範例會將 user-agent
標頭設為 request.header.user-agent
變數的值:
<AssignMessage name="set-headers-1"> <Set> <Headers> <Header name="user-agent">{request.header.user-agent}</Header> </Headers> </Set> <AssignTo createNew="true" transport="http" type="response"/> </AssignMessage>
如果在政策中定義空白標頭 (<Add><Headers/></Add>
),政策就不會新增任何標頭。這與省略 <Headers>
的效果相同。
<Path>
(<Set>
的子項)
<Payload>
(<Set>
的子項)
定義要求或回應的訊息主體,由 <AssignTo>
元素指定。酬載可以是任何有效的內容類型,例如純文字、JSON 或 XML。
預設值 | 空字串 |
必填與否 | 選用 |
類型 | 字串 |
父項元素 |
<Set>
|
子元素 | 無 |
<Payload>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <Payload contentType="content_type" variablePrefix="prefix" variableSuffix="suffix">new_payload</Payload> </Set> </AssignMessage>
範例 1
以下範例會設定純文字酬載:
<AssignMessage name="set-payload-1"> <Set> <Payload contentType="text/plain">42</Payload> </Set> </AssignMessage>
範例 2
以下範例會設定 JSON 酬載:
<AssignMessage name="set-payload-2"> <Set> <Payload contentType="application/json"> {"name":"foo", "type":"bar"} </Payload> </Set> </AssignMessage>
範例 3
以下範例會將變數名稱加上大括號,將變數值插入酬載:
<AssignMessage name="set-payload-3"> <Set> <Payload contentType="application/json"> {"name":"foo", "type":"{variable_name}"} </Payload> </Set> </AssignMessage>
在舊版 Apigee Edge 中 (例如 16.08.17 雲端版本之前),您無法使用大括號表示 JSON 酬載中的變數參照。在這些版本中,您需要使用 variablePrefix
和 variableSuffix
屬性指定分隔符號,並使用這些屬性包裝變數名稱,如下所示:
<AssignMessage name="set-payload-3b"> <Set> <Payload contentType="application/json" variablePrefix="@" variableSuffix="#"> {"name":"foo", "type":"@variable_name#"} </Payload> </Set> </AssignMessage>
這個舊語法仍可使用。
示例 4
系統會將 <Payload>
的內容視為訊息範本。也就是說,AssignMessage 政策會在執行階段,將以大括號括住的變數,替換成所參照變數的值。
以下範例使用大括號語法,將部分酬載設為變數值:
<AssignMessage name="set-payload-4"> <Set> <Payload contentType="text/xml"> <root> <e1>sunday</e1> <e2>funday</e2> <e3>{var1}</e3> </root> </Payload> </Set> </AssignMessage>
下表說明 <Payload>
的屬性:
屬性 | 說明 | 存在必要性 | 類型 |
---|---|---|---|
contentType |
如已指定, |
選用 | 字串 |
variablePrefix |
(選用) 指定流程變數的前置分隔符。預設為「{"」。詳情請參閱流程變數參考資料。 | 選用 | Char |
variableSuffix |
視需要指定流程變數的尾端分隔符。預設為「}」。詳情請參閱流程變數參考資料。 | 選用 | Char |
<QueryParams>
(<Set>
的子項)
以新值覆寫要求中現有的查詢參數。這個元素不會對回覆造成影響。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | <QueryParam> 元素陣列 |
父項元素 |
<Set>
|
子元素 |
<QueryParam> |
<QueryParams>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <QueryParams> <QueryParam name="queryparam_name">queryparam_value</QueryParam> ... </QueryParams> </Set> </AssignMessage>
範例 1
以下範例會將「address」查詢參數設為 request.header.address
變數的值:
<AssignMessage continueOnError="false" enabled="true" name="set-queryparams-1"> <Set> <QueryParams> <QueryParam name="address">{request.header.address}</QueryParam> </QueryParams> </Set> </AssignMessage>
只有在符合下列條件時,才能使用 <QueryParams>
:
- HTTP 動詞:GET
- 訊息類型:要求
如果在政策中定義空白查詢參數 (<Set><QueryParams/></Set>
),政策就不會設定任何查詢參數。這與省略 <QueryParams>
的效果相同。
<ReasonPhrase>
(<Set>
的子項)
在回應中設定原因片語。這通常會與 <StatusCode>
搭配使用,以進行偵錯。這個元素不會對要求造成任何影響。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串 |
父項元素 |
<Set>
|
子元素 | 無 |
<ReasonPhrase>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase> </Set> </AssignMessage>
範例 1
以下範例定義了簡單的原因片語:
<AssignMessage name="set-reasonphrase-1"> <Set> <ReasonPhrase>Bad medicine</ReasonPhrase> </Set> <AssignTo createNew="true" transport="http" type="response"/> </AssignMessage>
範例 2
系統會將 <ReasonPhrase>
的內容視為訊息範本。也就是說,系統會在執行階段將大括號括住的變數名稱,替換為參照變數的值,如下例所示:
<AssignMessage name="set-reasonphrase-2"> <Set> <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase> </Set> <AssignTo createNew="true" transport="http" type="response"/> </AssignMessage>
只有在符合下列條件時,才能使用 <ReasonPhrase>
:
- 訊息類型:回覆
<StatusCode>
(<Set>
的子項)
在回應中設定狀態碼。這個元素不會對要求造成任何影響。
預設值 | 「200」(當 <AssignTo> 的 createNew 屬性設為「true」時) |
必填與否 | 選用 |
類型 | 字串或 variable |
父項元素 |
<Set>
|
子元素 | 無 |
<StatusCode>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <StatusCode>HTTP_status_code or {variable}</StatusCode> </Set> </AssignMessage>
範例 1
以下範例會設定簡單的狀態碼:
<AssignMessage name="set-statuscode-1"> <Set> <StatusCode>404</StatusCode> </Set> <AssignTo createNew="true" transport="http" type="response"/> </AssignMessage>
範例 2
系統會將 <StatusCode>
的內容視為訊息範本。也就是說,以大括號括住的變數名稱會在執行階段替換為參照變數的值,如下例所示:
<AssignMessage name="set-statuscode-2"> <Set> <StatusCode>{calloutresponse.status.code}</StatusCode> </Set> <AssignTo createNew="true" transport="http" type="response"/> </AssignMessage>
只有在符合下列條件時,才能使用 <StatusCode>
:
- 訊息類型:回覆
<Verb>
(<Set>
的子項)
設定要求中的 HTTP 動詞。這個元素不會影響回覆。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串或 variable |
父項元素 |
<Set>
|
子元素 | 無 |
<Verb>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb> </Set> </AssignMessage>
範例 1
以下範例會在要求中設定簡單的動詞:
<AssignMessage name="set-verb-1"> <Set> <Verb>POST</Verb> </Set> <AssignTo createNew="true" transport="http" type="request"/> </AssignMessage>
範例 2
系統會將 <Verb>
的內容視為訊息範本。也就是說,系統會在執行階段將以大括號括住的變數名稱,替換為所參照變數的值。
以下範例使用變數填入動詞:
<AssignMessage name="set-verb-2"> <Set> <Verb>{my_variable}</Verb> </Set> <AssignTo createNew="true" transport="http" type="request"/> </AssignMessage>
只有在符合下列條件時,才能使用 <Verb>
:
- 訊息類型:要求
<Version>
(<Set>
的子項)
設定要求中的 HTTP 版本。這個元素不會影響回覆。
預設值 | 不適用 |
必填與否 | 選用 |
類型 | 字串或 variable |
父項元素 |
<Set>
|
子元素 | 無 |
<Version>
元素使用下列語法:
語法
<AssignMessage continueOnError="[false|true]" enabled="[true|false]" name="policy_name" > <Set> <Version>[1.0|1.1|{variable}]</Verb> </Set> </AssignMessage>
範例 1
以下範例會將版本號碼設為「1.1」:
<AssignMessage name="set-version-1"> <Set> <Version>1.1</Version> </Set> <AssignTo createNew="true" transport="http" type="request"/> </AssignMessage>
範例 2
以下範例使用大括號中的變數設定版本號碼:
<AssignMessage name="set-version-2"> <Set> <Version>{my_version}</Version> </Set> <AssignTo createNew="true" transport="http" type="request"/> </AssignMessage>
系統會將 <Version>
的內容視為訊息範本。也就是說,系統會在執行階段將以大括號括住的變數名稱,替換為參照變數的值。
只有在符合下列條件時,才能使用 <Version>
:
- 訊息類型:要求
建立自訂要求訊息
您可以使用 AssignMessage 政策建立自訂要求訊息。建立自訂要求後,您可以透過下列方式使用:
- 在其他政策中存取其變數
- 傳遞至外部服務
如要建立自訂要求訊息,請在 AssignMessage 政策中使用 <AssignTo>
元素。將 createNew
設為「true」,並在元素主體中指定新訊息的名稱,如下例所示:
<AssignMessage name="assignto-2"> <AssignTo createNew="true" transport="http" type="request"/> </AssignMessage>
根據預設,Edge 不會對自訂要求訊息執行任何操作。建立後,Edge 會繼續使用原始要求完成流程。如要使用自訂要求,請在 Proxy 中加入 ServiceCallout 政策等政策,將自訂要求傳遞至外部服務。
下列範例會建立自訂要求訊息:
範例 1
以下範例會使用「指派訊息」建立自訂要求物件:
<AssignMessage name="AssignMessage-3"> <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo> <Copy> <Headers> <Header name="user-agent"/> </Headers> </Copy> <Set> <QueryParams> <QueryParam name="address">{request.queryparam.addy}</QueryParam> </QueryParams> <Verb>GET</Verb> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
這個範例:
- 建立名為「MyCustomRequest」的新要求訊息物件。
- 在 MyCustomRequest 上,這項政策:
- 將傳入要求中的
user-agent
HTTP 標頭值複製到新訊息。由於<Copy>
使用user-agent
流程變數的絕對參照,因此不必為<Copy>
指定source
屬性。 - 將自訂訊息的
address
查詢參數設為傳入要求addy
查詢參數的值。 - 將 HTTP 動詞設為
GET
。
- 將傳入要求中的
- 將
<IgnoreUnresolvedVariables>
設為「false」。如果<IgnoreUnresolvedVariables>
為「false」,且政策嘗試新增的變數不存在,Edge 會停止 API 流程中的處理作業。
範例 2
以下是另一個範例,說明如何使用 AssignMessage 建立自訂要求物件:
<AssignMessage name="AssignMessage-2"> <AssignTo createNew="true" type="request">partner.request</AssignTo> <Set> <Verb>POST</Verb> <Payload contentType="text/xml"> <request><operation>105</operation></request> </Payload> </Set> </AssignMessage>
這個範例會建立名為「partner.request」的新自訂要求。然後在新要求中設定 <Verb>
和 <Payload>
。
您可以在流程中稍後發生的其他 AssignMessage 政策中,存取自訂要求訊息。以下範例會取得自訂要求訊息的 user-agent
標頭值:
<AssignMessage name="custom-request-1-access"> <DisplayName>custom-request-1-access</DisplayName> <AssignTo createNew="false" type="request"></AssignTo> <Set> <Headers> <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header> </Headers> </Set> </AssignMessage>
影片
如要進一步瞭解 AssignMessage 政策,請觀看下列影片。
影片 | 說明 |
---|---|
為什麼要指派訊息政策? | 瞭解使用 AssignMessage 政策修改 API 要求或回應的好處,不必修改後端程式碼。 |
使用 AssignMessage 政策複製 API 元素 | 從 API 要求或回應複製元素,然後使用 AssignMessage 政策建構新的要求或回應物件。 |
使用 AssignMessage 政策移除 API 元素 | 使用 AssignMessage 政策移除 API 元素並修改 API,再將其傳送至目標後端。 |
使用 AssignMessage 政策新增及設定 API 元素 | 使用 AssignMessage 政策新增查詢參數、標頭、表單參數或酬載,藉此變更 API 要求或回應。 |
使用 AssignMessage 政策建立自訂變數 | 使用 AssignMessage 政策設定自訂流程變數,並在 API Proxy 中的其他政策運用這些變數。 |
使用 AssignMessage 政策建立新的要求或回應物件 | 在 API 執行階段使用 AssignMessage 政策,建立新的 API 要求或回應物件。 |
使用 AssignMessage 政策建立模擬 API | 在回應流程中新增 AssignMessage 政策,建立簡單的模擬 REST API。 |
使用 AssignMessage 政策設定或修改酬載 | 在 API 執行階段,使用 AssignMessage 政策設定 SOAP 酬載,將 REST 要求轉換為 SOAP 要求。 |
錯誤代碼
本節說明在這項政策觸發錯誤時,所傳回的錯誤代碼和錯誤訊息,以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊,以便瞭解您是否要擬定錯誤規則, 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤程式碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
steps.assignmessage.SetVariableFailed |
500 | 這項政策無法設定變數。請參閱錯誤字串,瞭解 未解析的變數。 | |
steps.assignmessage.VariableOfNonMsgType |
500 |
如果 訊息類型變數代表整個 HTTP 要求和回應。內建 Edge
流程變數 |
build |
steps.assignmessage.UnresolvedVariable |
500 |
如果「指派訊息」政策中指定的變數出現以下情況,就會發生這個錯誤:
|
build |
部署錯誤
當您部署含有這項政策的 Proxy 時,可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidIndex |
如果指定訊息的 <Copy> 和/或 <Remove> 元素中指定的索引
當政策為 0 或負數時,API Proxy 的部署作業就會失敗。
|
build |
InvalidVariableName |
如果 <AssignVariable> 元素中子元素 <Name> 為空白或未指定,
那麼 API Proxy 部署作業就會失敗,因為沒有有效的變數名稱
系統會指派一個值必須提供有效的變數名稱。
|
build |
InvalidPayload |
政策中指定的酬載無效。 |
錯誤變數
當這項政策在執行階段觸發錯誤時,即可設定這些變數。如需更多資訊 見你什麼 需要瞭解政策錯誤
錯誤回應範例
{ "fault":{ "detail":{ "errorcode":"steps.assignmessage.VariableOfNonMsgType" }, "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message" } }
錯誤規則範例
<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Assign Message Faults"> <Step> <Name>AM-CustomNonMessageTypeErrorResponse</Name> <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition> </Step> <Step> <Name>AM-CustomSetVariableErrorResponse</Name> <Condition>(fault.name = "SetVariableFailed")</Condition> </Step> <Condition>(assignmessage.failed = true) </Condition> </FaultRule>
結構定義
每個政策類型都由 XML 架構 (.xsd
) 定義。如需參考,請前往 GitHub 查看政策架構。
相關主題
AssignMessage 政策的運作範例可在 API 平台範例中取得。
如需如何覆寫 ProxyEndpoint 中 target.url
的進階範例,請參閱這篇 Apigee 社群文章。
如要查看 ServiceCallout 政策中的「設定路徑」實際運作情形,請參閱 Apigee GitHub 範例中的實作範例。只要複製存放區,然後按照該主題中的指示操作即可。這個範例會使用 AssignMessage 政策設定要求路徑,然後使用 Service Callout 政策向外部服務提出要求。