本頁面由 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 政策。

預設值	請參閱下方的「預設政策」分頁
必填與否	必填
類型	複雜物件
父項元素	不適用
子元素	`<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 Proxy 要求中有 ServiceCallout 政策，且呼叫回應包含多個同名標頭 (Set-Cookie)。假設服務呼叫的回應變數是預設的 calloutResponse，下列政策會取得第二個 Set-Cookie 標頭值。

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

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

{calloutResponse.header.Set-Cookie.values}

本參考資料中的每個子元素都有額外範例。如需更多範例，請參閱 GitHub 上的「AssignMessage 範例」。

子元素參照

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

`<Add>`

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

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

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

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

語法

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

範例 1

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

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

範例 2

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

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

範例 3

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

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

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

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

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

在要求訊息中新增表單參數。這個元素不會對回覆訊息造成影響。

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

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

語法

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

範例 1

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

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

範例 2

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

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

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

範例 3

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

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

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

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

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

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

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

例如：

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

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

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

為 <AssignTo> 元素指定的特定要求或回應新增標頭。

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

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

語法

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

範例 1

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

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

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

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

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

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

語法

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

範例 1

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

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

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

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

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

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

`<AssignTo>`

決定 AssignMessage 政策要處理的物件。可採用的選項包括：

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

createNew

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

如果設為「true」，政策就會建立 type 指定類型的新變數 (「要求」或「回應」)。如果未指定新變數的名稱，政策會根據 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> 元素指定來源變數。如果 Edge 無法存取 <Ref> 參照的變數，就會使用 <Value> 元素指定的值。如果定義 <Template>，系統會優先採用這個元素，而非其他子元素。

範例 1

以下範例會將新變數 myvar 的值設為字面值「42」：

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

範例 2

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

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

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

如果 myvar 或 Country 流程變數不存在，<AssignVariable> 會建立這些變數。

範例 3

以下範例使用 <Template> 子項元素，串連兩個內容變數，並在兩者之間加入字串常值 (連字號)：

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

<AssignVariable> 的常見用途是為查詢參數、標頭或其他可隨要求傳遞的值設定預設值。您可以使用 <Ref> 和 <Value> 子項元素組合來執行這項操作。詳情請參閱 <Ref> 的範例。

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

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

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

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

語法

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

範例 1

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

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

如果 myvar 不存在，<AssignVariable> 會建立該檔案。

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

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

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

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

使用 <Ref> 指定流程變數時，請省略通常用於參照流程變數的封閉式大括號「{}」。舉例來說，如要將新變數的值設為 client.host 流程變數的值，請執行下列操作：

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

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

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

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

語法

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

範例 1

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

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

在本範例中，Edge 並未指定任何指派作業的預設值 (或備用值)。

範例 2

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

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

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

範例 3

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

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

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

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

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

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

並讓 API Proxy 傳回有效結果。

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

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

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

指定訊息範本。郵件範本可讓您在政策執行時執行變數字串替換作業，並將常值字串與以半形大括號括住的變數名稱合併。此外，訊息範本也支援逸出和大小寫轉換等函式。

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

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

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

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

語法

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

範例 1

以下範例使用訊息範本語法，將兩個環境變數與中間的字串常值 (連字號) 串連在一起：

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

範例 2

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

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

  </AssignVariable>
</AssignMessage>

範例 3

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

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

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

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

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

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

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

語法

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

範例 1

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

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

範例 2

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

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

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

`<Copy>`

將 source 屬性指定的訊息值複製到 <AssignTo> 元素指定的訊息。如果您未指定 <AssignTo> 的目標，這項政策會將值複製到要求或回應，視政策在流程中的執行位置而定。

預設值	不適用
必填與否	選用
類型	字串
父項元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Path>` `<Payload>` `<QueryParams>` `<ReasonPhrase>` `<StatusCode>` `<Verb>` `<Version>`

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

語法

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

範例 1

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

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

<Copy> 元素的屬性如下：

屬性說明是否必要？類型

來源

屬性	說明	是否必要？	類型
來源	指定副本的來源物件。如未指定 `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 屬性指定的 HTTP 標頭，複製到 <AssignTo> 元素指定的要求或回應訊息。

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

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

語法

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

範例 1

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

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

範例 2

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

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

範例 3

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

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

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

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

決定是否應將路徑從來源要求複製到目的地要求。這個元素不會影響回覆。

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<Copy>`
子元素	無

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

語法

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

範例 1

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

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

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

訊息類型：要求

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

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

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<Copy>`
子元素	無

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

語法

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

範例 1

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

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

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

將 <Copy> 元素 source 屬性指定的請求中的查詢字串參數複製到 <AssignTo> 元素指定的請求。這個元素不會影響回覆。

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

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

語法

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

範例 1

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

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

範例 2

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

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

範例 3

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

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

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

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

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

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

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

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<Copy>`
子元素	無

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

語法

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

範例 1

下列範例將 <ReasonPhrase> 設為「true」，導致 <Copy> 將預設回應中的原因片語複製到自訂回應物件：

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

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

訊息類型：回覆

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

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

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<Copy>`
子元素	無

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

語法

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

範例 1

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

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

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

訊息類型：回覆

<StatusCode> 的常見用途是確保 Proxy 回應與從目標收到的回應具有相同狀態，前提是 <AssignTo> 的 createNew 屬性設為「true」。

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

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

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<Copy>`
子元素	無

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

語法

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

範例 1

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

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

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

訊息類型：要求

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

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

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<Copy>`
子元素	無

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

語法

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

範例 1

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

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

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

訊息類型：要求

`<DisplayName>`

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

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

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

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

語法

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

範例

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

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

`<IgnoreUnresolvedVariables>`

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<AssignMessage>`
子元素	無

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

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

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

語法

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

範例 1

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

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

`<Remove>`

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

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

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

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

語法

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

範例 1

以下範例會從回應中移除郵件內文：

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

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

範例 2

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

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

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

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

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

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

語法

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

範例 1

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

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

範例 2

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

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

範例 3

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

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

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

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

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

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

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

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

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

語法

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

範例 1

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

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

範例 2

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

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

範例 3

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

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

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

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

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

預設值	否
必填與否	選用
類型	布林值
父項元素	`<Remove>`
子元素	無

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

語法

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

範例 1

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

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

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

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

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

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

語法

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

範例 1

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

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

範例 2

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

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

範例 3

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

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

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

示例 4

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

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

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

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

`<Set>`

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

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<AssignMessage>`
子元素	`<FormParams>` `<Headers>` `<Payload>` `<Path>` `<QueryParams>` `<ReasonPhrase>` `<StatusCode>` `<Verb>` `<Version>`

注意：<Set> 的子元素支援動態字串替代功能，稱為「訊息範本」。

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

語法

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

範例 1

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

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

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

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

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

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

語法

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

範例 1

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

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

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

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

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

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

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

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

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

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

語法

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

範例 1

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

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

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

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

注意：

這個元素目前無法如預期運作，無法覆寫/重新編寫 Proxy 的目標網址。(但可用於在服務摘要中設定路徑，如下方「動手練習」範例所示)。

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

以下範例說明 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 政策等政策，將自訂要求傳遞至外部服務。

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

範例 1

以下範例會使用「指派訊息」建立自訂要求物件：

<AssignMessage name="AssignMessage-3">
  <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
  <Copy>
    <Headers>
     <Header name="user-agent"/>
    </Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.addy}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

這個範例：

建立名為「MyCustomRequest」的新要求訊息物件。
在 MyCustomRequest 上，這項政策：
- 將傳入要求中的 user-agent HTTP 標頭值複製到新訊息。由於 <Copy> 使用 user-agent 流程變數的絕對參照，因此不必為 <Copy> 指定 source 屬性。
- 將自訂訊息的 address 查詢參數設為傳入要求 addy 查詢參數的值。
- 將 HTTP 動詞設為 GET。
將 <IgnoreUnresolvedVariables> 設為「false」。如果 <IgnoreUnresolvedVariables> 為「false」，且政策嘗試新增的變數不存在，Edge 會停止 API 流程中的處理作業。

範例 2

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

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

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

您可以在流程中稍後發生的其他 AssignMessage 政策中，存取自訂要求訊息。以下範例會取得自訂要求訊息的 user-agent 標頭值：

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

影片

如要進一步瞭解 AssignMessage 政策，請觀看下列影片。

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

錯誤代碼

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則，處理錯誤詳情請參閱這篇文章瞭解政策錯誤和處理方式發生錯誤

執行階段錯誤

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

錯誤程式碼 HTTP 狀態原因修正

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

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

steps.assignmessage.VariableOfNonMsgType

500

如果 <Copy> 元素中的 source 屬性設為變數，就會發生這項錯誤但不屬於訊息類型。

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

steps.assignmessage.UnresolvedVariable

500

如果「指派訊息」政策中指定的變數出現以下情況，就會發生這個錯誤：

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

部署錯誤

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

錯誤名稱	原因	修正
`InvalidIndex`	如果指定訊息的 `<Copy>` 和/或 `<Remove>` 元素中指定的索引當政策為 0 或負數時，API Proxy 的部署作業就會失敗。
`InvalidVariableName`	如果 `<AssignVariable>` 元素中子元素 `<Name>` 為空白或未指定，那麼 API Proxy 部署作業就會失敗，因為沒有有效的變數名稱系統會指派一個值必須提供有效的變數名稱。
`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>` 的子項)