本頁面由 Cloud Translation API 翻譯而成。

AssignMessage 政策

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

在 API Proxy 流程中，AssignMessage 政策會變更或建立新的要求和回應訊息。這項政策可讓您對這些訊息執行下列動作：

新增表單參數、標頭或查詢參數至郵件
複製一則訊息中的現有屬性
移除訊息中的標頭、查詢參數、表單參數和/或訊息酬載
設定訊息中現有屬性的值

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

用途

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

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

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

`<AssignMessage>` 元素

定義 AssignMessage 政策。

預設值	請參閱下方的「Default Policy」分頁
是否必要？	必填
類型	複雜物件
上層元素	n/a
子元素	`<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 指定為「response」，因此這個政策會修改目標伺服器傳回的回應物件。

這個政策在回應訊息中新增的 HTTP 標頭，是從 LookupCache 政策填入的變數衍生而來。因此，由這項指派訊息政策修改的回應訊息會包含 HTTP 標頭，指出結果是否已從快取中提取。在回應中設定標頭可方便進行偵錯和疑難排解。

4：設定動態內容

您可以使用指派訊息，在回應和要求訊息的酬載中嵌入動態內容。

如要在 XML 酬載中嵌入 Edge 流程變數，請以大括號括住指定的變數，例如：{prefix.name}。

以下範例會將 user-agent HTTP 標頭流程變數的值嵌入名為 User-agent 的 XML 元素中：

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

針對 JSON 酬載，您可以使用 variablePrefix 和 variableSuffix 屬性搭配分隔符號字元插入變數，如以下範例所示：

<AssignMessage name="set-payload">
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
     "user-agent": "@request.header.user-agent#"
  }
  </Payload>
</AssignMessage>

如需流程變數的完整清單，請參閱「流程變數參考資料」。

自雲端版本 16.08.17 起，您也可以使用大括號插入變數。

5：移除查詢參數

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

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

使用 VerifyAPIKey 政策驗證使用者時，最佳做法是在要求訊息中移除 apikey 查詢參數。這麼做可避免將敏感的鍵資訊傳遞至後端目標。

6：設定/取得變數

以下範例使用三個指派訊息政策：

在要求中建立三個流程變數，並使用靜態值
在要求流程中，透過第二個政策動態取得流程變數
在回應的酬載中設定

<!-- Policy #1: Set variables in the request -->
<AssignMessage continueOnError="false" enabled="true" name="set-variables">
    <!-- Create a variable named myAppSecret -->
    <AssignVariable>
        <Name>myAppSecret</Name>
        <Value>42</Value>
    </AssignVariable>
    <!-- Create a variable named config.environment -->
    <AssignVariable>
        <Name>config.environment</Name>
        <Value>test</Value>
    </AssignVariable>
    <!-- Create a variable named config.protocol -->
    <AssignVariable>
        <Name>config.protocol</Name>
        <Value>gopher</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

在第一個政策中，<AssignVariable> 元素會在要求中建立及設定三個變數。每個 <Name> 元素都會指定變數名稱，而 <Value> 則會指定值。

第二個政策會使用 <AssignVariable> 元素讀取值，並建立三個新變數：

<!-- Policy #2: Get variables from the request -->
<AssignMessage continueOnError="false" enabled="true" name="get-variables">
  <AssignTo createNew="false" transport="http" type="request"/>
  <!-- Get the value of myAppSecret and create a new variable, secret -->
  <AssignVariable>
    <Name>secret</Name>
    <Ref>myAppSecret</Ref>
    <Value>0</Value>
  </AssignVariable>
  <!-- Get the value of config.environment and create a new variable, environment -->
  <AssignVariable>
    <Name>environment</Name>
    <Ref>config.environment</Ref>
    <Value>default</Value>
  </AssignVariable>
  <!-- Get the value of config.protocol and create a new variable, protocol -->
  <AssignVariable>
    <Name>protocol</Name>
    <Ref>config.protocol</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

在第二個政策中，<Ref> 元素會參照來源變數，而 <Name> 元素會指定新變數的名稱。如果無法存取 <Ref> 元素參照的變數，您可以使用 <Value> 元素指定的值。

如要試用這組政策：

將政策 #1 和 #2 新增至要求流程。請務必將政策 #1 放在政策 #2 的前面。
在「回應」流程中新增第三個政策。

第三個政策會使用 <Set> 元素，將變數新增至回應。以下範例會在 Edge 傳回給用戶端的回應中建構 XML 酬載：

<!-- Policy #3: Add variables to the response -->
<AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
  <DisplayName>put-em-in-the-payload</DisplayName>
  <Set>
    <Payload contentType="application/xml">
      <wrapper>
        <secret>{secret}</secret>
        <config>
          <environment>{environment}</environment>
          <protocol>{protocol}</protocol>
        </config>
      </wrapper>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

請注意，如要存取 <Set> 中的流程變數，語法必須以大括號包裝。

請務必將 <Payload> 元素的 contentType 屬性設為「application/xml」。

傳送要求至 API Proxy，例如：

curl -vL https://ahamilton-eval-test.apigee.net/myproxy

您可以選擇透過 xmllint 等公用程式管道傳送結果，以便以格式正確的結構顯示 XML：

curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -

回應主體應如下所示：

<wrapper>
  <secret>42</secret>
  <config>
    <environment>test</environment>
    <protocol>gopher</protocol>
  </config>
</wrapper>

7：取得服務快訊回應標頭

在下列範例中，假設 API 代理要求包含 ServiceCallout 政策，且說明文字回應包含多個同名標頭 (Set-Cookie)。假設 ServiceCallout 的回應變數為預設 calloutResponse，則下列政策會取得第二個 Set-Cookie 標頭值。

<AssignMessage continueOnError="false" enabled="true" name="get-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

如要列出「所有」標頭值，請改用下列變數：

{calloutResponse.header.Set-Cookie.values}

此參考資料中的每個子元素都有其他範例。如需更多範例，請參閱 GitHub 上的 AssignMessage 範例。

子元素參照

本節將說明 <AssignMessage> 的子元素。

`<Add>`

在要求或回應中新增資訊，這由 <AssignTo> 元素指定。

<Add> 元素會在郵件中新增原始郵件中不存在的新屬性。如要變更現有屬性的值，請使用 <Set> 元素。

預設值	不適用
是否必要？	選用
類型	複雜類型
上層元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<QueryParams>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

範例 1

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

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

範例 2

以下範例使用 <Headers> 元素，將 User-Agent 標頭新增至目標端點要求：

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

範例 3

以下範例使用 <QueryParams> 元素，在要求中新增單一查詢參數，並為該參數指定靜態值：

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

本範例會在要求前置流程中使用 <Add>。如果您在工具 (例如追蹤工具) 中查看結果，對「http://httpbin.org/get」的請求會變成「http://httpbin.org/get?myParam=42」。

<Add> 的子項元素支援動態字串替換功能，也就是訊息範本。

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

將新的表單參數新增至要求訊息。這個元素對回應訊息沒有影響。

預設值	不適用
是否必要？	選用
類型	`<FormParam>` 元素陣列
上層元素	`<Add>`
子元素	`<FormParam>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
  </Add>
</AssignMessage>

範例 1

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

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"></AssignTo>
</AssignMessage>

範例 2

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

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-2">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
</AssignMessage>

請注意，這個範例並未使用 <AssignTo> 指定目標。這項政策只會在要求中加入參數。

範例 3

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

<AssignMessage continueOnError="false" enabled="true" name="add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="name">{request.queryparam.name}</FormParam>
      <FormParam name="zip">{request.queryparam.zipCode}</FormParam>
      <FormParam name="lang">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <AssignTo transport="http" type="request"/>
</AssignMessage>

這個範例會從原始要求取得查詢字串參數，並將這些參數新增為表單參數，傳送至目標端點的要求。

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

%7Busername%7D=nick&%7Bzip_code%7D=90210&%7Bdefault_language%7D=en

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

HTTP 動詞：POST
訊息類型：要求
下列其中一項 (或兩者皆是)：
- 表單資料：設為某個值，或設為 "" (空白字串)。例如，使用 curl 時，請將 -d "" 新增至要求。
- Content-Length 標頭：設為 0 (如果原始要求中沒有資料，則設為目前長度，以位元組為單位)。舉例來說，您可以使用 curl 在要求中加入 -H "Content-Length: 0"。

例如：

curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
  https://ahamilton-eval-test.apigee.net/am-test

新增 <FormParams> 後，Edge 會先將要求的 Content-Type 標頭設為「application/x-www-form-urlencoded」，再將訊息傳送至目標服務。

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

將新的標頭新增至指定要求或回應 (由 <AssignTo> 元素指定)。

預設值	不適用
是否必要？	選用
類型	`<Header>` 元素陣列
上層元素	`<Add>`
子元素	`<Header>`

<Headers> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>

範例 1

以下範例會將 user-agent 標頭新增至要求訊息，並將 request.user.agent 流程變數的值指派給該標頭。

<AssignMessage continueOnError="false" enabled="true" name="add-headers-1">
  <Add>
    <Headers>
      <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

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

預設值	不適用
是否必要？	選用
類型	`<QueryParam>` 元素陣列
上層元素	`<Add>`
子元素	`<QueryParam>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

範例 1

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

<AssignMessage continueOnError="false" enabled="true" name="add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

HTTP 動詞：GET
訊息類型：要求

此外，您只能在 <AssignTo> 元素的 type 屬性為要求訊息時，設定查詢參數。將這些屬性設為回應不會產生任何影響。

如果您在政策 (<Add><QueryParams/></Add>) 中定義空白的查詢參數陣列，政策就不會新增任何查詢參數。這與省略 <QueryParams> 相同。

`<AssignTo>`

判斷 AssignMessage 政策要對哪個物件運作。可採用的選項包括：

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

請注意，在某些情況下，您無法變更 AssignMessage 政策作用的物件。舉例來說，您無法使用 <Add> 或 <Set> 在回應中新增或變更查詢參數 (<QueryParams>) 或表單參數 (<FormParams>)。您只能在要求中操作查詢參數和表單參數。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<AssignMessage>`
子元素	無

如果您未指定 <AssignTo>，政策會對預設要求或回應採取動作，這取決於政策執行的位置。如果政策是在要求流程中執行，就會影響要求訊息。如果在回應流程中執行，則政策預設會影響回應。

<AssignTo> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>

範例 1

以下範例指定目標為原始要求，該要求會傳送至目標端點：

<AssignMessage name="assignto-1">
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

由於 createNew 已設為「false」(預設值)，因此本例不會建立新要求。這項政策中的所有作業都會影響原始要求。

範例 2

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

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

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

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

範例 3

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

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"&gt;MyRequestObject&lt;/AssignTo>
</AssignMessage>

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

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

下表說明 <AssignTo> 的屬性：

屬性說明必填與否類型

屬性	說明	必填與否	類型
`createNew`	決定這項政策在指派值時是否會建立新訊息。如果設為「true」，政策就會建立 `type` 指定類型 (「request」或「response」) 的新變數。如果您未指定新變數的名稱，政策會根據 `type` 的值建立新的要求或回應物件。注意：建立新的要求或回應物件時，系統會刪除現有的請求或回應物件，並以新物件取代，這表示物件中的所有資訊都會遺失。如果為「false」，政策會以下列其中一種方式回應：如果 `<AssignTo>` 可以將變數名稱解析為要求或回應，就會繼續處理。舉例來說，如果政策位於要求流程中，變數就是要求物件。如果政策位於回應中，變數就是回應物件。如果無法解析 `<AssignTo>`，或解析為非訊息類型，則政策會擲回錯誤。如果未指定 `createNew`，政策會以下列其中一種方式回應：如果 `<AssignTo>` 解析為訊息，則處理作業會進入下一個步驟。如果無法解析 `<AssignTo>`，或解析為非訊息類型，系統會建立 `type` 中指定類型的新變數。	選用	布林值
`transport`	指定要求或回應訊息類型的傳輸類型。預設值為「http」(唯一支援的值)。	選用	字串
`type`	當 `createNew` 為「true」時，指定新訊息的類型。有效值為「request」或「response」。預設值為「request」。如果您省略這個屬性，Edge 會根據這項政策在流程中執行的位置，建立要求或回應。	選用	字串

createNew

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

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

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

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

如果未指定 createNew，政策會以下列其中一種方式回應：

如果 <AssignTo> 解析為訊息，則處理作業會進入下一個步驟。
如果無法解析 <AssignTo>，或解析為非訊息類型，系統會建立 type 中指定類型的新變數。

選用

布林值

transport

指定要求或回應訊息類型的傳輸類型。

預設值為「http」(唯一支援的值)。

選用

字串

type

當 createNew 為「true」時，指定新訊息的類型。有效值為「request」或「response」。

預設值為「request」。如果您省略這個屬性，Edge 會根據這項政策在流程中執行的位置，建立要求或回應。

選用

字串

`<AssignVariable>`

為目的地資料流變數指派值 (例如值由 AssignMessage 政策設定的變數)。如果流程變數不存在，<AssignVariable> 會建立該變數。

預設值	不適用
是否必要？	選用
類型	複雜類型
上層元素	`<AssignMessage>`
子元素	`<Name>` (必填) `<Ref>` `<Template>` `<Value>`

您指派給目的地流程變數的值可以是下列任一項：

文字字串：使用 <Value> 子元素，為目的地資料流變數指定文字字串值。
資料流變數：使用 <Ref> 子元素，為目標資料流變數指定現有資料流變數的值。如需可用做為來源的流程變數完整清單，請參閱流程變數參考資料。
訊息範本：使用 <Template> 子元素，為目的地流程變數指定訊息範本。

<AssignVariable> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

使用 <Ref> 元素指定來源變數。如果無法存取 <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> 中沒有同名的變數，政策會建立同名的變數。

預設值	不適用
是否必要？	必填
類型	字串
上層元素	`<AssignVariable>`
子元素	無

<Name> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
  </AssignVariable>
</AssignMessage>

範例 1

以下範例會將目的地變數指定為 myvar，並將其設為文字值「42」：

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

如果 myvar 不存在，<AssignVariable> 會建立這個物件。

`<Ref>` (`<AssignVariable>` 的子項)

將指派作業的來源指定為流程變數。流程變數可以是預先定義的流程變數之一 (如「流程變數參考資料」所列)，或是您建立的自訂流程變數。

<Ref> 的值一律會解讀為流程變數，您無法將常值字串指定為值。如要指派文字字串值，請改用 <Value> 元素。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<AssignVariable>`
子元素	無

使用 <Ref> 指定流程變數時，請省略通常用來參照流程變數的括號「{}」。例如，如要將新變數的值設為 client.host 流程變數的值，請執行以下指令：

Do this (no brackets):
  <Ref>client.host</Ref>

Do NOT do this (brackets):
  <Ref>{client.host}</Ref>

如要為目的地資料流變數定義預設值，請使用 <Value> 搭配 <Ref>。如果 <Ref> 指定的流程變數不存在、無法讀取或為空值，Edge 會改為將 <Value> 的值指派給目的地流程變數。

<Ref> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
  </AssignVariable>
</AssignMessage>

範例 1

以下範例會將流程變數 request.header.user-agent 的值指派給目的地流程變數 myvar，並將查詢參數 country 的值指派給 Country 變數：

<AssignMessage name="assignvariable-4">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

在這個範例中，Edge 並未為任何指派指定預設值 (或備用值)。

範例 2

以下範例會將流程變數 request.header.user-agent 的值指派給目的地流程變數 myvar，並將查詢參數 country 的值指派給 Country 變數：

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

在本例中，如果 request.header.user-agent 流程變數或 Country 查詢參數的值為空值、無法讀取或格式不正確，Edge 會將「ErrorOnCopy」值指派給新變數。

範例 3

<AssignVariable> 的常見用途是設定查詢參數、標頭或其他可透過要求傳入的值的預設值。舉例來說，您建立的氣象 API Proxy 要求會採用名為「w」的單一查詢參數。這個參數包含您要查詢天氣的城市 ID。要求網址的格式如下：

http://myCO.com/v1/weather/forecastrss?w=city_ID

如要為「w」定義預設值，請建立類似下列的「AssignMessage」政策：

<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3">
  <AssignTo createNew="false" transport="http" type="request"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>request.queryparam.w</Name>
    <Ref>request.queryparam.w</Ref>
    <Value>12797282</Value>
  </AssignVariable>
</AssignMessage>

在這個範例中，<AssignVariable> 會取得 request.queryparam.w 的值，並將其指派給自身。如果資料流變數為空值，表示「w」查詢參數未包含在要求中，則本例會使用 <Value> 元素的預設值。因此，您可以向這個 API 代理提出要求，省略「w」查詢參數：

http://myCO.com/v1/weather/forecastrss

...並讓 API Proxy 傳回有效結果。

與使用 <Value> 時不同，<Ref> 的值必須是資料流變數，例如 request、response 或 target 物件的屬性。這個值也可以是您建立的自訂流程變數。

如果您指定的流程變數不存在於 <Ref> 的值中，且 <IgnoreUnresolvedVariables> 的值為「true」，Edge 就會擲回錯誤。

`<Template>` (`<AssignVariable>` 的子項)

指定訊息範本。訊息範本可讓您在政策執行時執行變數字串替換作業，並可將常值字串與以大括號包圍的變數名稱結合。此外，訊息範本支援函式，例如轉義和大小寫轉換。

使用 ref 屬性指定資料流變數，其中變數的值為訊息範本。舉例來說，您可以將訊息範本儲存為開發人員應用程式上的自訂屬性。當 Edge 驗證 API 金鑰或安全性權杖 (透過額外政策) 後，即可識別開發人員應用程式，而 <AssignVariable> 元素可使用應用程式自訂屬性的訊息範本，該屬性可做為安全性政策的流程變數。以下範例假設在進行 API 呼叫的開發人員應用程式中，訊息範本可在名為 message_template 的客戶屬性中使用，且 VerifyAPIKey 政策已用於驗證應用程式的 API 金鑰：

<AssignVariable ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<AssignVariable>`
子元素	無

<Template> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
  </AssignVariable>
</AssignMessage>

範例 1

以下範例使用訊息範本語法，將兩個內容變數連結在一起，並在兩者之間加上字串文字 (連字號)：

<AssignMessage name='template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

範例 2

以下範例會指定流程變數，其中變數的值是預先定義的訊息範本。如果您想在執行階段插入預先定義的範本，而無須修改政策，請使用這個選項：

<AssignMessage name='template-2'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>

  </AssignVariable>
</AssignMessage>

範例 3

以下範例會指定流程變數和文字值。在這種情況下，如果參照的變數非空值，系統會使用該值做為範本。如果參照的值為空值，則會使用文字值 (在本例中為 {system.uuid}-{messageid}) 做為範本。這個模式可用於提供「覆寫」值，在某些情況下，您可能會想使用動態設定的值覆寫預設範本 (文字部分)。舉例來說，條件式陳述式可能會從鍵/值對應表中擷取值，並將參照的變數設為該值：

<AssignMessage name='template-2'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

`<Value>` (`<AssignVariable>` 的子項)

定義使用 <AssignVariable> 設定的目的地流程變數值。系統一律會將值解讀為文字字串；即使您將值括入方括號 (「{}」) 中，也無法使用流程變數做為值。如要使用流程變數，請改用 <Ref>。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<AssignVariable>`
子元素	無

與 <Ref> 元素搭配使用時，<Value> 會做為預設 (或備用) 值。如果未指定 <Ref>、無法解析或為空值，則會使用 <Value> 的值。

<Value> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

範例 1

以下範例會將目標流程變數 myvar 的值設為文字值「42」：

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

範例 2

以下範例會將流程變數 request.header.user-agent 的值指派給流程變數 myvar，並將查詢參數 country 的值指派給 Country 變數：

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

如果任一指派失敗，<AssignVariable> 會改為將「ErrorOnCopy」值指派給目的地流程變數。

`<Copy>`

將從由 source 屬性指定的訊息，複製至由 <AssignTo> 元素指定的訊息。如果您未使用 <AssignTo> 指定目標，則這項政策會將值複製到要求或回應，具體取決於這項政策在流程中執行的位置。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Path>` `<Payload>` `<QueryParams>` `<ReasonPhrase>` `<StatusCode>` `<Verb>` `<Version>`

<Copy> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
    <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>
  <!-- Used as the destination for the <Copy> values -->
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>

範例 1

以下範例會將標頭、三個表單參數、路徑和所有查詢參數從要求複製至新的自訂要求：

<AssignMessage continueOnError="false" enabled="true" name="copy-1">
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1">Header value 1</Header>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_2">Form param value 1</FormParam>
      <FormParam name="Form_Param_Name_3">Form param value 1</FormParam>
    </FormParams>
    <Payload>false</Payload>
    <Path>true</Path>
    <QueryParams/>
    <ReasonPhrase>false</ReasonPhrase>
    <StatusCode>false</StatusCode>
    <Verb>false</Verb>
    <Version>false</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

<Copy> 元素的屬性如下：

屬性說明必填與否類型

來源

屬性	說明	必填與否	類型
來源	指定複本的來源物件。如果未指定 `source`，系統會將其視為簡單訊息。舉例來說，如果政策位於要求流程中，來源就會預設為 `request` 物件。如果政策位於回應流程中，則預設為 `response` 物件。如果省略 `source`，您可以使用流程變數的絕對參照做為複製作業的來源。例如，將值指定為 `{request.header.user-agent}`。如果無法解析來源變數，或解析為非訊息類型，`<Copy>` 就會無法回應。	選用	字串

指定複本的來源物件。

如果未指定 source，系統會將其視為簡單訊息。舉例來說，如果政策位於要求流程中，來源就會預設為 request 物件。如果政策位於回應流程中，則預設為 response 物件。如果省略 source，您可以使用流程變數的絕對參照做為複製作業的來源。例如，將值指定為 {request.header.user-agent}。
如果無法解析來源變數，或解析為非訊息類型，<Copy> 就會無法回應。

選用

字串

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

將表單參數從 <Copy> 元素的 source 屬性 複製到 <AssignTo> 元素指定的要求。這個元素不會對回應產生任何影響。

預設值	不適用
是否必要？	選用
類型	`<FormParam>` 元素陣列或空陣列
上層元素	`<Copy>`
子元素	`<FormParam>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

範例 1

以下範例會將單一表單參數從要求複製到自訂要求「MyCustomRequest」：

<AssignMessage name="copy-formparams-1">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName">Form param value 1</FormParam>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 2

以下範例會將所有表單參數複製到自訂要求「MyCustomRequest」：

<AssignMessage name="copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 3

以下範例會將三個表單參數複製到自訂要求「MyCustomRequest」：

<AssignMessage name="copy-formparams-3">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName1"/>
      <FormParam name="paramName2"/>
      <FormParam name="paramName3"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

示例 4

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

<AssignMessage name="copy-formparams-4">
  <Copy source="request">
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

這個範例會複製「f1」、「f2」和「f3」的第二個值。如果「f3」只有一個值，則不會複製。

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

HTTP 動詞：POST
訊息類型：回應
下列其中一項 (或兩者皆是)：
- 表單資料：設為某個值，或設為 "" (空白字串)。例如，使用 curl 時，請將 -d "" 新增至要求。
- Content-Length 標頭：設為 0 (如果原始要求中沒有資料，否則為目前長度)。舉例來說，如果使用 curl，請在要求中加入 -H "Content-Length: 0"。

複製 <FormParams> 時，<Copy> 會先將訊息的 Content-Type 設為「application/x-www-form-urlencoded」，再將訊息傳送至目標服務。

`<Headers>` (`<Copy>` 的子項)

將 <Copy> 元素的 source 屬性指定的要求或回應訊息，複製至 <AssignTo> 元素指定的要求或回應訊息。

預設值	不適用
是否必要？	選用
類型	`<Header>` 元素陣列或空陣列
上層元素	`<Copy>`
子元素	`<Header>`

<Headers> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

範例 1

以下範例會將要求中的 user-agent 標頭複製到新的自訂要求物件：

<AssignMessage name="copy-headers-1">
  <Copy source="request">
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 2

如要複製所有標頭，請使用空白的 <Headers> 元素，如以下範例所示：

<AssignMessage name="copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="copy-headers-3">
  <Copy source="request">
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

這個範例會複製「h1」、「h2」和「h3」的第二個值。如果「h3」只有一個值，則不會複製。

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

判斷是否應將路徑從來源要求複製到目的地要求。這個元素不會對回應造成任何影響。

如果設為「true」，這項政策會將路徑從 <Copy> 元素的 source 屬性指定的要求訊息，複製到 <AssignTo> 元素指定的要求訊息。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<Copy>`
子元素	無

<Path> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

範例 1

以下範例指出 AssignMessage 政策應將路徑從來源要求複製到新的自訂要求物件：

<AssignMessage name="copy-path-1">
  <Copy source="request">
    <Path>true</Path>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

訊息類型：要求

`<Payload>` (`<Copy>` 的子項)

判斷是否應將酬載從來源複製到目的地。來源和目的地可以是要求或回應。

如果為「true」，這項政策會將 <Copy> 元素的 source 屬性指定的訊息從複製到 <AssignTo> 元素指定的訊息。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<Copy>`
子元素	無

<Payload> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

範例 1

以下範例將 <Payload> 設為「true」，以便將要求酬載從要求複製到回應：

<AssignMessage name="copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

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

將查詢字串參數從 <Copy> 元素的 source 屬性複製到 <AssignTo> 元素指定的要求。這個元素不會對回應造成任何影響。

預設值	不適用
是否必要？	選用
類型	`<QueryParam>` 元素陣列或空陣列
上層元素	`<QueryParam>`
子元素	無

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>

範例 1

以下範例會將要求中的「my_param」查詢參數複製到新的自訂要求物件中：

<AssignMessage name="copy-queryparams-1">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="my_param"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 2

以下範例會將要求中的所有查詢參數複製到新的自訂要求物件中：

<AssignMessage name="copy-queryparams-2">
  <Copy source="request">
    <QueryParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="copy-queryparams-3">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

這個範例會複製「qp1」、「qp2」和「qp3」的第二個值。如果「qp3」只有一個值，則不會複製。

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

HTTP 動詞：GET
訊息類型：要求

`<ReasonPhrase>` (`<Copy>` 的子項)

判斷是否應將原因字詞從來源回應複製到目的地回應。這個元素不會對要求造成任何影響。

如果設為「true」，這項政策會將 ReasonPhrase 從 <Copy> 元素的 source 屬性指定的回應複製到 <AssignTo> 元素指定的回應。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<Copy>`
子元素	無

<ReasonPhrase> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <ReasonPhrase>[false|true]</ReasonPhrase>
  </Copy>
</AssignMessage>

範例 1

以下範例將 <ReasonPhrase> 設為「true」，導致 <Copy> 從預設回應複製原因詞組至自訂回應物件：

<AssignMessage name="copy-reasonphrase-1">
  <Copy source="response">
    <ReasonPhrase>true</ReasonPhrase>
  </Copy>
  <AssignTo createNew="trie" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

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

訊息類型：回應

`<StatusCode>` (`<Copy>` 的子項)

決定是否要將狀態碼從來源回應複製到目的地回應。這個元素不會對要求造成任何影響。

如果為「true」，這項政策會將狀態碼從 <Copy> 元素的 source 屬性指定的回應訊息複製至 <AssignTo> 元素指定的回應訊息。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<Copy>`
子元素	無

<StatusCode> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>

範例 1

以下範例將 <StatusCode> 設為「true」，從預設回應物件複製狀態碼至新的自訂回應物件：

<AssignMessage name="copy-statuscode-1">
  <Copy source="response">
    <StatusCode>true</StatusCode>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

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

訊息類型：回應

<StatusCode> 的常見用途是確保代理伺服器回應的狀態與 <AssignTo> 的 createNew 屬性設為「true」時，從目標收到的回應相同。

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

決定是否要將 HTTP 動詞從來源要求複製到目的地要求。這個元素不會對回應造成任何影響。

如果設為「true」，系統會將 <Copy> 元素 source 屬性中找到的動詞複製到 <AssignTo> 元素中指定的要求。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<Copy>`
子元素	無

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>

範例 1

以下範例將 <Verb> 設為「true」，從預設要求複製動詞至新的自訂要求：

<AssignMessage name="copy-verb-1">
  <Copy source="request">
    <Verb>true</Verb>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

訊息類型：要求

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

決定是否要將 HTTP 版本從來源要求複製到目的地要求。這個元素不會對回應造成影響。

如果為「true」，系統會將 <Copy> 元素 source 屬性中找到的 HTTP 版本複製到 <AssignTo> 元素指定的物件。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<Copy>`
子元素	無

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>

範例 1

以下範例會將 <Version> 設為要求的「true」，從預設要求物件複製版本至新的自訂要求物件：

<AssignMessage name="copy-version-1">
  <Copy source="request">
    <Version>true</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

訊息類型：要求

`<DisplayName>`

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱，為政策加上標籤。

<DisplayName> 元素適用於所有政策。

預設值	不適用
是否必要？	選用設定。如果省略 `<DisplayName>`，系統會使用政策的 `name` 屬性值
類型	字串
上層元素	<`PolicyElement`>
子元素	無

<DisplayName> 元素使用以下語法：

語法

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

範例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 元素沒有屬性或子項元素。

`<IgnoreUnresolvedVariables>`

判斷遇到未解析的變數時是否停止處理。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<AssignMessage>`
子元素	無

將其設為 true 可略過未解析的變數並繼續處理；否則為 false。預設值為 false。

將 <IgnoreUnresolvedVariables> 設為 true 與將 <AssignMessage> 的 continueOnError 設為 true 不同，因為前者是用於設定及取得變數值。如果將 continueOnError 設為 true，Edge 會忽略所有錯誤，而非只忽略使用變數時發生的錯誤。

<IgnoreUnresolvedVariables> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</AssignMessage>

範例 1

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

<AssignMessage name="ignoreunresolvedvariables">
  <Copy source="response">
    ...
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  </Copy>
</AssignMessage>

`<Remove>`

從訊息中移除標頭、查詢參數、表單參數和/或訊息酬載。訊息可以是要求或回應。您可以使用 <AssignTo> 元素，指定 <Remove> 要處理的訊息。

預設值	不適用
是否必要？	選用
類型	複雜類型
上層元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Payload>` `<QueryParams>`

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

範例 1

以下範例會從回應中移除訊息主體：

<AssignMessage continueOnError="false" enabled="true" name="remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

在回應流程中，這項政策會移除回應主體，只將 HTTP 標頭傳回給用戶端。

範例 2

以下範例會從傳入要求中移除所有表單參數和查詢參數：

<AssignMessage continueOnError="false" enabled="true" name="remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

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

預設值	不適用
是否必要？	選用
類型	`<FormParam>` 元素陣列或空陣列
上層元素	`<Remove>`
子元素	`<FormParam>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

範例 2

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

<AssignMessage name="remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

範例 3

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

<AssignMessage name="remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="application/x-www-form-urlencoded"/>
</AssignMessage>

這個範例會移除「f1」、「f2」和「f3」的第二個值。如果「f3」只有一個值，則不會移除。

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

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

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

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

預設值	不適用
是否必要？	選用
類型	`<Header>` 元素陣列或空陣列
上層元素	`<Remove>`
子元素	`<Header>`

<Headers> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="remove-headers-1">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

範例 2

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

<AssignMessage name="remove-headers-2">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

範例 3

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

<AssignMessage name="remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

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

判斷 <Remove> 是否會刪除要求或回應中的酬載，這由 <AssignTo> 元素指定。設為「true」可清除酬載；否則設為「false」。預設值為「false」。

預設值	否
是否必要？	選用
類型	布林值
上層元素	`<Remove>`
子元素	無

<Payload> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

範例 1

以下範例將 <Payload> 設為「true」，以便清除要求酬載：

<AssignMessage name="remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

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

預設值	不適用
是否必要？	選用
類型	`<QueryParam>` 元素陣列或空陣列
上層元素	`<Remove>`
子元素	`<QueryParam>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

範例 2

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

<AssignMessage name="remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

範例 3

如果有多個查詢參數具有相同名稱，請使用以下語法：

<AssignMessage name="remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

示例 4

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

<AssignMessage name="remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

HTTP 動詞：GET
訊息類型：要求

`<Set>`

在要求或回應訊息中設定資訊，這些資訊由 <AssignTo> 元素指定。<Set> 會覆寫原始訊息中已存在的標頭或參數。如要建立新的標頭或參數，請改用 <Add> 元素。

預設值	不適用
是否必要？	選用
類型	複雜類型
上層元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Payload>` `<Path>` `<QueryParams>` `<ReasonPhrase>` `<StatusCode>` `<Verb>` `<Version>`

注意：<Set> 的子元素支援稱為「訊息模板」的動態字串替換功能。

<Set> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>path</Path>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

範例 1

以下範例顯示 <Set> 元素：

<AssignMessage continueOnError="false" enabled="true" name="set-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
    <QueryParams>
      <QueryParam name="name">{request.header.name}</QueryParam>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
    <!-- <Verb>GET</Verb> -->
    <Payload contentType="text/plain">42</Payload>
    <Path/>
    <ReasonPhrase>Bad request</ReasonPhrase>
    <StatusCode>400</StatusCode>
    <Verb>POST</Verb>
    <Verb>{my_variable}</Verb>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

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

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

預設值	不適用
是否必要？	選用
類型	`<FormParam>` 元素陣列
上層元素	`<Set>`
子元素	`<FormParam>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>

範例 1

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

<AssignMessage name="set-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
    <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

HTTP 動詞：POST
訊息類型：要求

如果您在政策 (<Add><FormParams/></Add>) 中定義空白表單參數，政策就不會新增任何表單參數。這與省略 <FormParams> 相同。

<Set> 會將訊息的 Content-Type 變更為「application/x-www-form-url-encoded」，然後傳送至目標端點。

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

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

預設值	不適用
是否必要？	選用
類型	`<Header>` 元素陣列
上層元素	`<Set>`
子元素	`<Header>`

<Headers> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>

範例 1

以下範例會將 user-agent 標頭設為 request.header.user-agent 變數的值：

<AssignMessage name="set-headers-1">
  <Set>
    <Headers>
      <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

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

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

注意：

這個元素目前無法如預期覆寫/重寫 Proxy 的目標網址。(在服務摘要中設定路徑時，這項功能會有效，如以下「動手學習」範例所示)。

有時，您可能需要將訊息傳送至 API 代理程的 TargetEndpoint 中定義的網址以外的網址。如果您想重寫目標網址，請使用 <AssignVariable> 元素覆寫 TargetEndpoint 中的 target.url 變數。(Edge 會在 TargetEndpoint 中設定變數，因此您無法在 ProxyEndpoint 中覆寫 target.url)。

以下範例說明 AssignMessage 政策如何覆寫 target.url。再次將政策新增至 TargetEndpoint 要求。有了這項政策，Proxy 就會呼叫下方網址，而非在 TargetEndpoint 中定義的網址。

<AssignMessage name="Assign-Message-1">
...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>http://mocktarget.apigee.net/user?user=Dude</Value>
  </AssignVariable>
...

您也可以在 TargetEndpoint 中使用 JavaScript 政策來覆寫 target.url。

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

定義要求或回應的訊息主體，由 <AssignTo> 元素指定。酬載可以是任何有效的內容類型，例如純文字、JSON 或 XML。

預設值	空字串
是否必要？	選用
類型	字串
上層元素	`<Set>`
子元素	無

<Payload> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
  </Set>
</AssignMessage>

範例 1

以下範例會設定純文字酬載：

<AssignMessage name="set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>

範例 2

以下範例會設定 JSON 酬載：

<AssignMessage name="set-payload-2">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"bar"}
    </Payload>
  </Set>
</AssignMessage>

範例 3

以下範例會將變數名稱加上大括號，插入變數值至酬載：

<AssignMessage name="set-payload-3">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"{variable_name}"}
    </Payload>
  </Set>
</AssignMessage>

在舊版 Apigee Edge 中 (例如，雲端版本 16.08.17 之前)，您無法使用大括號來表示 JSON 酬載中的變數參照。在這些版本中，您需要使用 variablePrefix 和 variableSuffix 屬性指定分隔符字元，並使用這些字元包裝變數名稱，如下所示：

<AssignMessage name="set-payload-3b">
  <Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {"name":"foo", "type":"@variable_name#"}
    </Payload>
  </Set>
</AssignMessage>

這個舊版語法仍可正常運作。

示例 4

系統會將 <Payload> 的內容視為訊息範本。也就是說，AssignMessage 政策會在執行階段將包在大括號中的變數，替換為參照變數的值。

以下範例使用大括號語法，將酬載的一部分設為變數值：

<AssignMessage name="set-payload-4">
  <Set>
    <Payload contentType="text/xml">
      <root>
        <e1>sunday</e1>
        <e2>funday</e2>
        <e3>{var1}</e3>
      </root>
    </Payload>
  </Set>
</AssignMessage>

下表說明 <Payload> 的屬性：

屬性	說明	存在必要性	類型
`contentType`	如已指定，`contentType` 的值會指派至 `Content-Type` HTTP 標頭。	選用	字串
`variablePrefix`	可選指定流程變數的前置分隔符號。預設為「{"」。詳情請參閱流程變數參考資料。	選用	Char
`variableSuffix`	可選指定流程變數的結尾分隔符。預設值為「}」。詳情請參閱流程變數參考資料。	選用	Char

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

使用新值覆寫要求中的現有查詢參數。這個元素不會對回應產生任何影響。

預設值	不適用
是否必要？	選用
類型	`<QueryParam>` 元素陣列
上層元素	`<Set>`
子元素	`<QueryParam>`

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>

範例 1

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

<AssignMessage continueOnError="false" enabled="true" name="set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

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

HTTP 動詞：GET
訊息類型：要求

如果您在政策 (<Set><QueryParams/></Set>) 中定義空白的查詢參數，政策就不會設定任何查詢參數。這與省略 <QueryParams> 相同。

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

設定回應的理由短語。這通常是為了進行偵錯，並與 <StatusCode> 搭配使用。這個元素不會對要求造成任何影響。

預設值	不適用
是否必要？	選用
類型	字串
上層元素	`<Set>`
子元素	無

<ReasonPhrase> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
  </Set>
</AssignMessage>

範例 1

以下範例會定義簡單的原因短語：

<AssignMessage name="set-reasonphrase-1">
  <Set>
    <ReasonPhrase>Bad medicine</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

範例 2

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

<AssignMessage name="set-reasonphrase-2">
  <Set>
    <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

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

訊息類型：回應

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

在回應中設定狀態碼。這個元素不會對要求造成任何影響。

預設值	「200」(當 `<AssignTo>` 的 `createNew` 屬性設為「true」時)
是否必要？	選用
類型	字串或 `variable`
上層元素	`<Set>`
子元素	無

<StatusCode> 元素使用以下語法：

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
  </Set>
</AssignMessage>

範例 1

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

<AssignMessage name="set-statuscode-1">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

範例 2

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

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

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

訊息類型：回應

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

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

預設值	不適用
是否必要？	選用
類型	字串或 `variable`
上層元素	`<Set>`
子元素	無

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
  </Set>
</AssignMessage>

範例 1

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

<AssignMessage name="set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

範例 2

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

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

<AssignMessage name="set-verb-2">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

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

訊息類型：要求

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

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

預設值	不適用
是否必要？	選用
類型	字串或 `variable`
上層元素	`<Set>`
子元素	無

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

範例 1

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

<AssignMessage name="set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

範例 2

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

<AssignMessage name="set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

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

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

訊息類型：要求

建立自訂要求訊息

您可以使用「AssignMessage」政策建立自訂要求訊息。建立自訂要求後，您可以透過下列方式使用該要求：

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

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

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
</AssignMessage>

根據預設，Edge 不會對自訂要求訊息採取任何行動。建立後，Edge 會繼續透過原始要求完成流程。如要使用自訂要求，請在 Proxy 中新增政策 (例如 ServiceCallout 政策)，這樣 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

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

<AssignMessage name="AssignMessage-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <Set>
    <Verb>POST</Verb>
    <Payload contentType="text/xml">
      <request><operation>105</operation></request>
    </Payload>
  </Set>
</AssignMessage>

本範例會建立名為「partner.request」的新自訂要求。接著，在新要求中設定 <Verb> 和 <Payload>。

您可以在流程中稍後出現的另一個 AssignMessage 政策中存取自訂要求訊息。以下範例會取得自訂要求訊息的 user-agent 標頭值：

<AssignMessage name="custom-request-1-access">
  <DisplayName>custom-request-1-access</DisplayName>
  <AssignTo createNew="false" type="request"></AssignTo>
  <Set>
    <Headers>
      <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header>
    </Headers>
  </Set>
</AssignMessage>

影片

請觀看下列影片，進一步瞭解「指派訊息」政策。

影片	說明
為什麼要指派訊息政策？	瞭解使用 AssignMessage 政策修改 API 要求或回應的優點，無須修改後端程式碼。
使用 AssignMessage 政策複製 API 元素	從 API 要求或回應中複製元素，然後使用 AssignMessage 政策建立新的要求或回應物件。
使用 AssignMessage 政策移除 API 元素	使用 AssignMessage 政策，在 API 抵達目標後端之前移除 API 元素並修改 API。
使用 AssignMessage 政策新增及設定 API 元素	使用 AssignMessage 政策新增查詢參數、標頭、表單參數或酬載，藉此變更 API 要求或回應。
使用 AssignMessage 政策建立自訂變數	使用 AssignMessage 政策設定自訂流程變數，並在 API Proxy 中運用其他政策中的變數。
使用 AssignMessage 政策建立新的要求或回應物件	在 API 執行階段使用 AssignMessage 政策建立新的 API 要求或回應物件。
使用 AssignMessage 政策建立模擬 API	在回應流程中新增 AssignMessage 政策，建立簡單的模擬 REST API。
使用 AssignMessage 政策設定或修改酬載	在 API 執行階段使用 AssignMessage 政策設定 SOAP 酬載，將 REST 要求轉換為 SOAP 要求。

錯誤代碼

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

執行階段錯誤

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

錯誤代碼 HTTP 狀態原因修正

steps.assignmessage.SetVariableFailed 500 這項政策無法設定變數。請參閱錯誤字串，瞭解未解析變數的名稱。

錯誤代碼	HTTP 狀態	原因
`steps.assignmessage.SetVariableFailed`	500	這項政策無法設定變數。請參閱錯誤字串，瞭解未解析變數的名稱。
`steps.assignmessage.VariableOfNonMsgType`	500	如果 `<Copy>` 元素中的 `source` 屬性設為非 message 類型的變數，就會發生這個錯誤。訊息類型變數代表整個 HTTP 要求和回應。內建的 Edge 資料流變數 `request`、`response` 和 `message` 是訊息類型。如要進一步瞭解訊息變數，請參閱變數參考資料。
`steps.assignmessage.UnresolvedVariable`	500	如果在指派訊息政策中指定的變數為下列任一情況，就會發生這項錯誤：超出範圍 (在執行政策的特定流程中不可用) 或無法解析 (未定義)

steps.assignmessage.VariableOfNonMsgType

500

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

訊息類型變數代表整個 HTTP 要求和回應。內建的 Edge 資料流變數 request、response 和 message 是訊息類型。如要進一步瞭解訊息變數，請參閱變數參考資料。

steps.assignmessage.UnresolvedVariable

500

如果在指派訊息政策中指定的變數為下列任一情況，就會發生這項錯誤：

超出範圍 (在執行政策的特定流程中不可用)
無法解析 (未定義)

部署錯誤

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

錯誤名稱	原因	修正
`InvalidIndex`	如果指派訊息政策的 `<Copy>` 和/或 `<Remove>` 元素中指定的索引為 0 或負數，則 API Proxy 的部署作業會失敗。
`InvalidVariableName`	如果子元素 `<Name>` 為空白，或是未在 `<AssignVariable>` 元素中指定，則 API 代理程式無法部署，因為沒有有效的變數名稱可用來指派值。必須提供有效的變數名稱。
`InvalidPayload`	政策中指定的酬載無效。

錯誤變數

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

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

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

{  
   "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 政策

結果

用途

<AssignMessage> 元素

語法

預設政策

範例

1：新增標頭

2：移除酬載

3：修改回應

4：設定動態內容

5：移除查詢參數

6：設定/取得變數

7：取得服務快訊回應標頭

子元素參照

<Add>

語法

範例 1

範例 2

範例 3

<FormParams> (<Add> 的子項)

語法

範例 1

範例 2

範例 3

<Headers> (<Add> 的子項)

語法

範例 1

<QueryParams> (<Add> 的子項)

語法

範例 1

<AssignTo>

語法

範例 1

範例 2

範例 3

<AssignVariable>

語法

範例 1

範例 2

範例 3

<Name> (<AssignVariable> 的子項)

語法

範例 1

<Ref> (<AssignVariable> 的子項)

語法

範例 1

範例 2

範例 3

<Template> (<AssignVariable> 的子項)

語法

範例 1

範例 2

範例 3

<Value> (<AssignVariable> 的子項)

語法

範例 1

範例 2

<Copy>

語法

範例 1

<FormParams> (<Copy> 的子項)

語法

範例 1

範例 2

範例 3

示例 4

<Headers> (<Copy> 的子項)

語法

範例 1

範例 2

範例 3

<Path> (<Copy> 的子項)

語法

範例 1

<Payload> (<Copy> 的子項)

語法

範例 1

<QueryParams> (<Copy> 的子項)

語法

`<AssignMessage>` 元素

`<Add>`

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

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

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

`<AssignTo>`

`<AssignVariable>`

`<Name>` (`<AssignVariable>` 的子項)

`<Ref>` (`<AssignVariable>` 的子項)

`<Template>` (`<AssignVariable>` 的子項)

`<Value>` (`<AssignVariable>` 的子項)

`<Copy>`

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

`<Headers>` (`<Copy>` 的子項)

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

`<Payload>` (`<Copy>` 的子項)

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

`<ReasonPhrase>` (`<Copy>` 的子項)

`<StatusCode>` (`<Copy>` 的子項)

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

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

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<Remove>`

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

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

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

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

`<Set>`

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

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

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

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

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

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

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