您正在查看 Apigee Edge 說明文件。
參閱 Apigee X 說明文件。 資訊
意義
在 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
指定為「回應」,因此這項政策會修改目標伺服器傳回的回應物件。
透過這項政策新增至回應訊息的 HTTP 標頭,衍生自 LookupCache 政策填入的變數。因此,由這個指派訊息政策修改的回應訊息包含 HTTP 標頭,指出結果是否已從快取中提取。在回應中設定標頭,有助於進行偵錯和疑難排解。
4:設定動態內容
您可以使用 Assign Message,在回應和要求訊息的酬載中嵌入動態內容。
如要在 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>
如需流程變數的完整清單,請參閱流程變數參考資料。
自 Cloud 版本 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。請務必在政策 #2「之前」將政策 1 設為第 1 組。
- 在 Response 流程中新增第三個政策。
- 第三個政策會使用
<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 要求中含有 服務呼叫政策,且呼叫回應包含多個相同名稱 (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>
元素。
預設值 | n/a |
是否必填? | 選用 |
類型 | 複雜類型 |
父項元素 |
<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://http://httpbin.org/get」的要求會變為「http://httpbin.org/get?myParam=42」。
<Add>
的子元素支援動態字串替代,也稱為訊息範本。
<FormParams>
(<Add>
的子項)
在要求訊息中新增表單參數。這個元素不會影響回應訊息。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
元素指定的指定要求或回應。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
的子項)
在要求中新增查詢參數。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
)。您只能處理要求中的查詢參數和表單參數。
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串 |
父項元素 |
<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>
) 會針對這個新的要求物件採取行動。
稍後您可以在流程中的其他政策中存取新要求物件,或是使用 Service callout 政策,將新的要求物件傳送至外部服務。
範例 3
以下範例會建立一個名為「MyRequestObject」的新要求物件:
<AssignMessage name="assignto-2"> <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo> </AssignMessage>
當您建立新的要求或回應物件時,AssignMessage 政策的其他元素 (例如 <Add>
、<Set>
和 <Set>
) 會針對這個新的要求物件採取行動。
稍後您可以在流程中的其他政策中存取新要求物件,或是使用 Service callout 政策,將新的要求物件傳送至外部服務。
下表說明 <AssignTo>
的屬性:
屬性 | 說明 | 必填與否 | 類型 |
---|---|---|---|
createNew |
決定這項政策在指派值時是否要建立新訊息。 如果設為「true」,政策就會建立 如果設為「false」,政策會以下列其中一種方式回應:
如未指定
|
選用 | 布林值 |
transport |
指定要求或回應訊息類型的傳輸類型。 預設值為「http」(唯一支援的值)。 |
選用 | 字串 |
type |
當 createNew 為「true」時,指定新訊息的類型。有效值為「request」或「response」。預設值為「request」。如果省略這項屬性,Edge 會根據這項政策在流程中的執行位置,建立要求或回應。 |
選用 | 字串 |
<AssignVariable>
指派值給目的地流程變數 (例如:值由 AssignMessage 政策設定的變數值)。如果流程變數不存在,則 <AssignVariable>
會建立該變數。
預設值 | n/a |
是否必填? | 選用 |
類型 | 複雜類型 |
父項元素 |
<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>
元素指定來源變數。如果無法存取 <Ref>
參照的變數,Edge 會使用 <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>
中指定的變數不存在,政策會使用該名稱建立一個變數。
預設值 | n/a |
是否必填? | 必要 |
類型 | 字串 |
父項元素 |
<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>
元素。
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串 |
父項元素 |
<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 Proxy 發出要求省略「w」查詢參數:
http://myCO.com/v1/weather/forecastrss
...而且 API Proxy 仍傳回有效的結果。
與使用 <Value>
時不同,<Ref>
的值必須是資料流變數,例如 request
、response
或 target
物件的屬性。這個值也可以是您建立的自訂流程變數。
如果您指定的資料流變數與 <Ref>
值不存在,且 <IgnoreUnresolvedVariables>
的值為「true」,Edge 會擲回錯誤。
<Template>
(<AssignVariable>
的子項)
指定訊息範本。訊息範本可讓您在政策執行時執行變數字串替代,並且可以將文字字串與以大括號括住的變數名稱結合使用。此外,訊息範本也支援 函式,例如逸出和大小寫轉換。
使用 ref
屬性指定資料流變數,其中變數的值為訊息範本。舉例來說,您可以將訊息範本儲存為開發人員應用程式中的自訂屬性。當 Edge 在透過額外政策驗證 API 金鑰或安全性權杖後識別出開發人員應用程式時,<AssignVariable>
元素可以使用應用程式自訂屬性的訊息範本,該範本可做為安全性政策的資料流變數。以下範例假設在發出 API 呼叫的開發人員應用程式中,名為 message_template
的客戶屬性提供此訊息範本,其中 VerifyAPIKey 政策用於驗證應用程式的 API 金鑰:
<AssignVariable ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串 |
父項元素 |
<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>
。
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串 |
父項元素 |
<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>
指定目標,這項政策會根據這項政策的執行流程中的位置,將值複製到要求或回應。
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串 |
父項元素 |
<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>
元素指定的要求。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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
屬性指定的要求或回應訊息「從」複製到 <AssignTo>
元素指定的要求或回應訊息。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
元素指定的要求訊息。
預設值 | false |
是否必填? | 選用 |
類型 | 布林值 |
父項元素 |
<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>
元素指定的訊息。
預設值 | false |
是否必填? | 選用 |
類型 | 布林值 |
父項元素 |
<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>
元素指定的要求。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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
屬性指定的回應「從」複製到 <AssignTo>
元素指定的回應「從」ReasonPhrase
。
預設值 | false |
是否必填? | 選用 |
類型 | 布林值 |
父項元素 |
<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>
元素指定的回應訊息。
預設值 | false |
是否必填? | 選用 |
類型 | 布林值 |
父項元素 |
<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>
的常見用途是,當 <AssignTo>
的 createNew
屬性設為「true」時,確保 Proxy 回應的狀態與目標收到的回應相同。
<Verb>
(<Copy>
的子項)
決定 HTTP 動詞是否從來源要求複製到目的地要求。這個元素對回應沒有影響。
如果設為「true」,系統會將 <Copy>
元素的 source
屬性中找到的動詞複製到 <AssignTo>
元素中指定的要求。
預設值 | false |
是否必填? | 選用 |
類型 | 布林值 |
父項元素 |
<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>
元素指定的物件。
預設值 | false |
是否必填? | 選用 |
類型 | 布林值 |
父項元素 |
<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>
在管理 UI Proxy 編輯器中,除了 name
屬性,可用以其他自然更自然的名稱為政策加上標籤。
<DisplayName>
元素適用於所有政策。
預設值 | n/a |
是否必填? | 選用設定。如果省略 <DisplayName> ,則會使用政策的 name 屬性值 |
類型 | 字串 |
父項元素 | <PolicyElement> |
子元素 | 無 |
<DisplayName>
元素使用下列語法:
語法
<PolicyElement> <DisplayName>policy_display_name</DisplayName> ... </PolicyElement>
範例
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
<DisplayName>
元素沒有屬性或子元素。
<IgnoreUnresolvedVariables>
判斷遇到未解析的變數時,是否要停止處理。
預設值 | false |
是否必填? | 選用 |
類型 | 布林值 |
父項元素 |
<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>
要對哪些訊息採取行動。
預設值 | n/a |
是否必填? | 選用 |
類型 | 複雜類型 |
父項元素 |
<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>
的子項)
從要求中移除指定的表單參數。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
的子項)
從 <AssignTo>
元素指定的要求或回應中移除指定的 HTTP 標頭。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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」。
預設值 | 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>
的子項)
從要求中移除指定的查詢參數。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
元素。
預設值 | n/a |
是否必填? | 選用 |
類型 | 複雜類型 |
父項元素 |
<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>
的子項)
覆寫要求中的現有表單參數,並以您為此元素指定的新值取代這些參數。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
的子項)
覆寫要求或回應中由 <AssignTo>
元素指定的現有 HTTP 標頭。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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 中 (例如 Cloud 版本 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 |
視需要指定流程變數的前置分隔符號。預設值為「{」。詳情請參閱流程變數參考資料。 | 選用 | 圖表 |
variableSuffix |
視需要指定流程變數的結尾分隔符號。預設值為「"}」。詳情請參閱流程變數參考資料。 | 選用 | 圖表 |
<QueryParams>
(<Set>
的子項)
使用新值覆寫要求中的現有查詢參數。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | <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>
搭配使用來偵錯。這個元素不會影響要求。
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串 |
父項元素 |
<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 動詞。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串或 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 版本。這個元素對回應沒有影響。
預設值 | n/a |
是否必填? | 選用 |
類型 | 字串或 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 中新增服務呼叫政策等政策,以便將自訂要求傳送至外部服務。
下列範例可建立自訂要求訊息:
範例 1
以下範例使用「Assign Message」建立自訂要求物件:
<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
流程變數的絕對參照,因此不需要將source
屬性指定為<Copy>
。 - 將自訂訊息的
address
查詢參數設為傳入要求的addy
查詢參數值。 - 將 HTTP 動詞設為
GET
。
- 將傳入要求中的
- 將
<IgnoreUnresolvedVariables>
設為「false」。當<IgnoreUnresolvedVariables>
為「false」時,如果政策嘗試新增的變數不存在,Edge 就會停止在 API 流程中處理。
範例 2
以下是另一個範例,說明如何使用「Assign Message」建立自訂要求物件:
<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>
您可以在流程中稍後發生的另一個 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 政策將 REST 要求轉換為 SOAP 要求。 |
錯誤代碼
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
steps.assignmessage.SetVariableFailed |
500 | 這項政策無法設定變數。請參閱未解析變數名稱的錯誤字串。 | |
steps.assignmessage.VariableOfNonMsgType |
500 |
如果 訊息類型變數代表整個 HTTP 要求和回應。內建 Edge 流程變數 |
build |
steps.assignmessage.UnresolvedVariable |
500 |
如果 Assign Message 政策中指定的變數符合下列任一條件,就會發生這個錯誤:
|
build |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidIndex |
如果 Assign Message 政策的 <Copy> 和/或 <Remove> 元素中指定的索引為 0 或負數,API Proxy 部署就會失敗。
|
build |
InvalidVariableName |
如果子項元素 <Name> 為空白,或是在 <AssignVariable> 元素中未指定,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 社群文章。
如要查看服務呼叫政策中的「設定路徑」應用實例,請參閱 Apigee GitHub 範例中的透過範例學習。只要複製存放區,並按照主題中的指示操作。這個範例使用 AssignMessage 政策來設定要求路徑,然後使用服務呼叫政策向外部服務發出要求。