AssignMessage 政策

您正在查看 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 必要

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

或者,您也可以使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中,以不同的自然語言名稱來標示政策。

continueOnError false 選填 如果設為「false」,當政策失敗時會傳回錯誤。多數政策預期的行為如下。如果設為「true」,則在政策失敗後,仍會繼續執行流程。
enabled true 選填 設為「true」即可強制執行政策。將政策設為「false」,即可「關閉」政策。即使政策已附加至流程,系統也不會強制執行這項政策。
async   false 已淘汰 這項屬性已淘汰。

下表提供 <AssignMessage> 子項元素的概略說明:

子元素 必填與否 說明
常見作業
<Add> 選用 將資訊新增至 <AssignTo> 元素指定的訊息物件。

<Add> 會將原始訊息中沒有的標頭或參數新增至郵件。如要覆寫現有的標頭或參數,請使用 <Set> 元素。

<Copy> 選用 source 屬性指定訊息的「寄件者」資訊複製到 <AssignTo> 元素指定的訊息物件中。
<Remove> 選用 <AssignTo> 元素中指定的訊息變數刪除指定元素。
<Set> 選用 替換要求或回應中由 <AssignTo> 元素指定的現有屬性值。

<Set> 會覆寫原始訊息中「已存在」的標頭或參數。如要新增標頭或參數,請使用 <Add> 元素。

其他子元素
<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 酬載,您可以使用含有分隔符號字元的 variablePrefixvariableSuffix 屬性插入變數,如以下範例所示:

<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:設定/取得變數

以下範例使用三個「指派郵件」政策:

  1. 以靜態值在要求中建立三個流程變數
  2. 在要求流程的第二項政策中,以動態方式取得流程變數
  3. 將其設為回應的酬載
<!-- 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. 在要求流程中新增政策 1 和 #2。請務必在政策 #2「之前」將政策 1 設為第 1 組。
  2. Response 流程中新增第三個政策。
  3. 第三個政策會使用 <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」。

  4. 傳送要求至 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 政策要在哪個物件中運作。可採用的選項包括:

  • 要求訊息:API Proxy 收到的 request
  • 回應訊息:目標伺服器傳回的 response
  • 自訂訊息:自訂要求或回應物件

請注意,在某些情況下,您無法變更針對 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"&gt;MyRequestObject&lt;/AssignTo>
</AssignMessage>

當您建立新的要求或回應物件時,AssignMessage 政策的其他元素 (例如 <Add><Set><Set>) 會針對這個新的要求物件採取行動。

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

下表說明 <AssignTo> 的屬性:

屬性 說明 必填與否 類型
createNew

決定這項政策在指派值時是否要建立新訊息。

如果設為「true」,政策就會建立 type 指定類型 (「要求」或「回應」) 的新變數。如果未指定新變數的名稱,政策會根據 type 的值建立新的要求或回應物件。

如果設為「false」,政策會以下列其中一種方式回應:

  • 如果 <AssignTo> 可以將變數名稱解析為要求或回應,就會繼續處理。舉例來說,如果政策位於要求流程中,變數就是要求物件。如果政策出現在回應中,變數就是回應物件。
  • 如果 <AssignTo> 無法解析,或解析為非訊息類型,政策就會擲回錯誤。

如未指定 createNew,政策會以下列其中一種方式回應:

  • 如果 <AssignTo> 解析訊息,系統會繼續執行下一個步驟。
  • 如果 <AssignTo> 無法解析,或解析為非訊息類型,則會建立 type 中指定的新類型變數。
選用 布林值
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」值指派給目的地流程變數。

如果 myvarCountry 流程變數不存在,<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> 的值必須是資料流變數,例如 requestresponsetarget 物件的屬性。這個值也可以是您建立的自訂流程變數。

如果您指定的資料流變數與 <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> 元素的屬性如下:

屬性 說明 必填與否 類型
來源

指定副本的來源物件。

  • 如未指定 source,則會視為簡單訊息。舉例來說,如果政策位於要求流程中,來源就會預設為 request 物件。如果政策出現在回應流程中,則預設為 response 物件。如果省略 source,可以使用流程變數的絕對參照做為複製來源。例如,將值指定為 {request.header.user-agent}
  • 如果來源變數無法解析,或解析為非訊息類型,<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 酬載中的變數參照。在這些版本中,您必須使用 variablePrefixvariableSuffix 屬性來指定分隔符號字元,並使用這些屬性將變數名稱納入包裝,如下所示:

<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

如果有指定,系統會將 contentType 的值指派給 Content-Type HTTP 標頭。

選用 字串
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>

本範例會建立新的自訂要求「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 政策將 REST 要求轉換為 SOAP 要求。

錯誤代碼

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼 HTTP 狀態 原因 修正
steps.assignmessage.SetVariableFailed 500 這項政策無法設定變數。請參閱未解析變數名稱的錯誤字串。
steps.assignmessage.VariableOfNonMsgType 500

如果 <Copy> 元素中的 source 屬性設為不屬於 message 類型的變數,就會發生這個錯誤。

訊息類型變數代表整個 HTTP 要求和回應。內建 Edge 流程變數 requestresponsemessage 屬於訊息類型。如要進一步瞭解訊息變數,請參閱「變數參考資料」。

steps.assignmessage.UnresolvedVariable 500

如果 Assign Message 政策中指定的變數符合下列任一條件,就會發生這個錯誤:

  • 超出範圍 (不適用於執行政策的特定流程)
  • 無法解析 (未定義)

部署錯誤

若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。

錯誤名稱 原因 修正
InvalidIndex 如果 Assign Message 政策的 <Copy> 和/或 <Remove> 元素中指定的索引為 0 或負數,API Proxy 部署就會失敗。
InvalidVariableName 如果子項元素 <Name> 為空白,或是在 <AssignVariable> 元素中未指定,API Proxy 的部署就會失敗,因為沒有可指派值的有效變數名稱。必須提供有效的變數名稱。
InvalidPayload 政策中指定的酬載無效。

錯誤變數

當這項政策在執行階段觸發錯誤時,系統會設定這些變數。詳情請參閱「政策錯誤須知」。

Variables 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 fault.name Matches "UnresolvedVariable"
assignmessage.policy_name.failed policy_name 是擲回錯誤的政策使用者指定的名稱。 assignmessage.AM-SetResponse.failed = true

錯誤回應範例

{  
   "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 政策來設定要求路徑,然後使用服務呼叫政策向外部服務發出要求。