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

AssignMessage 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

AssignMessage 政策可以在 API Proxy Flow 中變更現有的要求或回應訊息，或是建立新的要求或回應訊息。這項政策可讓您對這些郵件執行下列動作：

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

您也可以使用 AssignMessage 設定任意內容變數，與可能套用至郵件的任何上述作業無關。

使用 AssignMessage 時，您可以新增、變更或移除要求或回應的屬性。或者，您也可以使用 AssignMessage 建立自訂要求或回應訊息，並將其傳遞至替代目標，詳情請參閱「建立自訂要求訊息」。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

用途

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

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

影片

如要進一步瞭解 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 要求。

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

<Add>、<Copy>、<Set> 和 <Remove> 元素的排列順序非常重要。政策會按照動作在政策設定中的顯示順序執行。如要移除所有標頭，請設定特定標頭，並在 <Set> 元素前加入 <Remove> 元素。

`<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>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>

  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</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>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>

  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <Authentication>
      <HeaderName>HEADER_NAME</HeaderName>
      <!-- Use either GoogleAccessToken or GoogleIDToken  -->
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
      </GoogleAccessToken>

    ----- or -----
      <GoogleIDToken>
        <Audience ref='FLOW_VARIABLE_NAME>TARGET_URL</Scope>
      </GoogleAccessToken>
    </Authentication>
    <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>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>

</AssignMessage>

預設政策

以下範例顯示在 Apigee 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/>
    <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>

在 Apigee UI 中插入新的 AssignMessage 政策時，範本會包含所有可能作業的存根。通常，您會選取要透過這項政策執行的作業，並移除其餘子元素。舉例來說，如要執行複製作業，請使用 <Copy> 元素，並從政策中移除 <Add>、<Remove> 和其他子元素，讓政策更容易閱讀。

這個元素包含下列所有政策都適用的屬性：

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

下表提供 <AssignMessage> 子元素的高階說明：

子元素	是否必要	說明
常見作業
`<Add>`	選用	將資訊新增至 `<AssignTo>` 元素指定的訊息物件。 `<Add>` 會在郵件中新增原始郵件沒有的標頭或參數。請注意，`<Set>` 也提供這項功能。如要覆寫現有標頭或參數，請使用 `<Set>` 元素。
`<Copy>`	選用	將 `source` 屬性指定的訊息資訊複製到 `<AssignTo>` 元素指定的訊息物件。
`<Remove>`	選用	從 `<AssignTo>` 元素中指定的訊息變數刪除指定元素。
`<Set>`	選用	取代要求或回應中現有屬性的值，由 `<AssignTo>` 元素指定。 `<Set>` 會覆寫原始郵件中已有的標頭或參數，如果沒有，則會新增。
其他子元素
`<AssignTo>`	選用	指定 AssignMessage 政策要處理的訊息。這可以是標準要求或回應，也可以是新的自訂訊息。
`<AssignVariable>`	選用	為流程變數指派值。如果變數不存在，`<AssignVariable>` 會建立該變數。
`<IgnoreUnresolvedVariables>`	選用	判斷遇到無法解析的變數時，是否停止處理。

後續章節將說明這些子元素。

範例

下列範例說明如何使用 AssignMessage 政策：

1：新增標頭

以下範例會使用 <Add> 元素，在要求中新增標頭：

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

2：移除酬載

以下範例會使用 <Remove> 元素，從回應中刪除酬載：

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

3：修改回覆

以下範例會修改現有的回應物件，並在其中加入標頭：

<AssignMessage name="AM-modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

這個範例不會建立新訊息。而是透過新增 HTTP 標頭來修改現有回應訊息。

由於這個範例在 <AssignTo> 元素中將 response 指定為變數名稱，因此這項政策會修改原本使用目標伺服器傳回資料設定的回應物件。

這項政策新增至回應訊息的 HTTP 標頭，是衍生自 LookupCache 政策填入的變數。因此，由這項「指派訊息」政策修改的回應訊息會包含 HTTP 標頭，指出結果是否從快取中提取。在回應中設定標頭有助於偵錯和排解問題。

4：設定動態內容

您可以使用 AssignMessage 將動態內容嵌入回應和要求訊息的酬載中。

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

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

<AssignMessage name="AM-set-dynamic-content">
  <AssignTo>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="AM-set-payload">
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
     "user-agent": "@request.header.user-agent#"
  }
  </Payload>
</AssignMessage>

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

您也可以使用大括號插入變數。

5：移除查詢參數

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

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

使用 VerifyAPIKey 政策進行使用者驗證時，最佳做法是從要求訊息中移除 apikey 查詢參數。這麼做是為了避免將機密金鑰資訊傳遞至後端目標。

6：設定/取得變數

以下範例使用三項 AssignMessage 政策：

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

<!-- Policy #1: Set variables in the request -->
<AssignMessage name="AM-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>
</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 -

回應主體應如下所示：


  42
  
    test
    gopher

7：取得 ServiceCallout 回應標頭

在下列範例中，假設 API Proxy 要求中有 ServiceCallout 政策，且呼叫回應包含多個同名標頭 (Set-Cookie)。假設服務呼叫的回應變數是預設的 calloutResponse，下列政策會取得第二個 Set-Cookie 標頭值。

<AssignMessage name="AM-Payload-from-SC-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

{calloutResponse.header.Set-Cookie.values}

8：儲存及移除表單參數、標頭、查詢參數

如要使用 <Remove> 刪除標頭、查詢參數或表單參數，但稍後仍想在政策流程中存取這些值，可以使用 <AssignVariable> 儲存這些值。

<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-StoreAndRemove">
  <DisplayName>AM-StoreAndRemove</DisplayName>
  <AssignVariable>
    <Name>var_grant_type</Name>
    <Ref>request.formparam.grant_type</Ref>
  </AssignVariable>
  <Remove>
    <Headers/>
    <FormParams/>
    <Payload/>
  </Remove>
  <Set>
    <Headers>
      <Header name="Content-Type">application/x-www-form-urlencoded</Header>
      <Header name="Accept">application/json</Header>
      <Header name="Grant-Type">{var_grant_type}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

注意：使用「指派訊息」政策中的 <Remove> 剝除表單參數、標頭和查詢參數後，除非這些值儲存在變數中 (如本範例所述)，否則政策流程完成後就無法存取這些值。

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

子元素參照

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

`<Add>`

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

<Add> 元素會在郵件中新增原始郵件沒有的屬性。請注意，<Set> 也提供這項功能。如要變更現有屬性的值，請使用 <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

下列範例會從初始要求取得三個查詢字串參數的值，並將這些值設為目標端點要求的表單參數，藉此修改要求訊息，最後移除所有原始查詢字串參數：

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 2

以下範例使用 <Headers> 元素，將 partner-id 標頭新增至傳送至目標端點的要求：

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

本範例在要求前置流程中使用 <Add>。如果您在「偵錯總覽」等工具中查看結果，對 https://example-target.com/get 的要求會變成 https://example-target.com/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 name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 2

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

<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>

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

範例 3

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

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

這個範例會從原始要求取得查詢字串參數，並以不同名稱將這些參數新增為表單參數。然後移除原始查詢參數。Apigee 會將修改過的要求傳送至目標端點。

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

username=nick&zip_code=90210&default_language=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> 後，Apigee 會將要求的 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

以下範例會在要求訊息中新增 partner-id 標頭，並將 verifyapikey.VAK-1.developer.app.partner-id 流程變數的值指派給該標頭。

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</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 name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

HTTP 動詞：GET、POST、PATCH、DELETE
訊息類型：要求

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

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

`<AssignTo>`

決定 AssignMessage 政策要處理的物件。選項如下：

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

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

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

如未指定 <AssignTo>，或指定 <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

以下範例在 <AssignTo> 的文字中未指定任何訊息。這表示政策會對 request 或 response 訊息採取行動，具體取決於政策的執行位置。

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

如果您指定 createNew="false"，但未明確提供訊息名稱，<AssignTo> 的其他屬性就無關緊要。在這種情況下，您可能會希望完全省略 <AssignTo> 元素。

範例 2

以下範例會建立新的要求物件，覆寫現有物件：

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

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

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

範例 3

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

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

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

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

下表說明 <AssignTo> 的屬性：

屬性說明是否必要類型

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

createNew

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

如果是 true，政策會建立 type 指定型別的新變數 (request 或 response)。如果未指定新變數的名稱，政策會根據 type 的值建立新的要求或回應物件。

如果 false，政策會透過下列其中一種方式回應：

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

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

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

選用

布林值

transport

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

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

選用

字串

type

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

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

選用

字串

`<AssignVariable>`

將值指派給目的地流程變數 (例如值是由 AssignMessage 政策設定的變數)。如果流程變數不存在，<AssignVariable> 會建立該變數。您可以在 AssignMessage 政策中使用多個 AssignVariable 元素。系統會按照政策設定中的顯示順序執行這些動作。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<AssignMessage>`
子元素	`<Name>` (必要) `<PropertySetRef>` `<Ref>` `<ResourceURL>` `<Template>` `<Value>`

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

字串常值：使用 <Value> 子項元素，為目的地流程變數指定字串常值。
流程變數：使用 <Ref> 子項元素，為目的地流程變數指定現有流程變數的值。如需可用做來源的流程變數完整清單，請參閱流程變數參考資料。
屬性集：使用 <PropertySetRef> 子項元素，從屬性集名稱/鍵值組擷取值，並將其儲存在流程變數中。可讓您動態存取屬性集。
資源網址：使用 <ResourceURL> 子元素指定文字資源的網址，類型為 XSL、XSD、WSDL、JavaScript 或 OpenAPI 規格。這會將資源內容指派給具名的流程變數。
訊息範本：使用 <Template> 子項元素，為目的地流程變數指定訊息範本。

這些子元素的優先順序為：ResourceURL、Template、Ref、Value、PropertySetRef。

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

使用 <Ref> 元素指定來源變數。如果 <Ref> 參照的變數無法存取，Apigee 會使用 <Value> 元素指定的值。如果您定義 <Template>，系統會優先採用該元素，而非 <Ref> 和 <Value> 同層級元素。

範例 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>

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

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

範例 3

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

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

範例 4

下列範例使用 <AssignVariable> 停用預設行為，也就是將路徑尾碼從 Proxy 要求傳播至目標要求：

<AssignMessage name='AM-PathSuffixFalse'>
  <AssignVariable>
    <Name>target.copy.pathsuffix</Name>
    <Value>false</Value>
  </AssignVariable>
</AssignMessage>

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

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

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

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<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> 會建立該檔案。

注意：ratelimit 這個名稱已保留，詳情請參閱 Apigee 社群的「Quota Policy Throws NullPointerException」。

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

這個元素可讓您動態擷取屬性集名稱/鍵值組合的值。如要瞭解屬性組合，請參閱「使用屬性組合」。

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

屬性集包含名稱/鍵值組。例如：propset1.id=12345，其中 propset1 是屬性集的名稱，id 是鍵，而 12345 是鍵的值。

PropertySetRef 子項元素可讓您動態選取屬性集名稱和/或鍵。假設您在資源集檔案中有 200 個轉送規則。您可以按照下列方式存取屬性集規則，其中 routingrules 是屬性集名稱，而 rule1、rule2、rulen 則是鍵：

propertyset.routingrules.rule1
propertyset.routingrules.rule2
propertyset.routingrules.rulen

如要在 API Proxy 流程中存取這些屬性，您必須在設計階段選取所需規則。不過，假設規則名稱來自要求標頭或酬載。選取規則的方法之一，是使用 JavaScript 政策，並搭配下列程式碼：

context.getVariables("propertyset.routingrules." + ruleName); //assuming ruleName was populated earlier.

另一方面，AssignMessage PropertySetRef 功能可讓您動態選取屬性鍵，不必導入 JavaScript。

您可以在 <PropertySetRef> 元素中混用流程變數和字串常值。詳情請參閱範例。

注意： 使用這項功能時，請勿使用 propertyset 前置字元參照屬性集，例如：propertyset.PROPNAME.KEY。系統會假設前置字元為 propertyset。

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
  </AssignVariable>
</AssignMessage>

範例 1

這個範例會將屬性集金鑰的值指派給流程變數。在本例中，屬性集名稱是從 propset_name 標頭取得，鍵是在 propset_key 標頭中提供，而指派給鍵的值會儲存在 flow_variable 變數中。

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.{request.header.propset_key}</PropertySetRef>
  </AssignVariable>
</AssignMessage>

您可以在 <PropertySetRef> 元素中，任意組合使用流程變數和字串常值。

範例 2

這個範例會使用固定鍵名 (字串常值)，將屬性集鍵中的值指派給流程變數。在本例中，屬性集名稱是從標頭 propset_name 取得，鍵是字串常值 key1，而指派給鍵的值會儲存在變數 flow_variable 中。

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.key1</PropertySetRef>
  </AssignVariable>
</AssignMessage>

您可以在 <PropertySetRef> 元素中，任意組合使用流程變數和字串常值。

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

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

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

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

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

  DO specify the variable name without brackets:
  <Ref>client.host</Ref>

  DO NOT use brackets:
  <Ref>{client.host}</Ref>

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

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

範例 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 查詢參數的值為空值、無法讀取或格式錯誤，Apigee 會將 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 傳回有效結果。

<Ref> 的值必須是流程變數，例如 request、response 或 target 物件的屬性，或是自訂流程變數的名稱。

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

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

指定文字資源的網址，做為變數指派的來源。Apigee 會載入 <Name> 中指定的流程變數，以及參照資源的內容。資源可以是 XSD、XSL、WSDL、JavaScript、Property Set 或 OpenAPI Spec 類型。

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

如果 <ResourceURL> 指定的資源不存在，則：如果 <IgnoreUnresolvedVariables> 的值為 true，Apigee 會將值 null 指派給目的地流程變數；如果 <IgnoreUnresolvedVariables> 的值為 false，Apigee 會擲回錯誤。

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
  </AssignVariable>
</AssignMessage>

文字值會採用字串值，並解譯為訊息範本。以下皆為有效值：

jsc://my-js-file.js
wsdl://{variable-goes-here}
{variable-goes-here}

範例 1

下列範例會將載入 jsc 資料夾中 Proxy 的 JSON 資源值，指派給流程變數 assigned-variable：

<AssignMessage name='AM-From-ResourceURL-Proxy-JSC'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>jsc://settings.json</ResourceURL>
  </AssignVariable>
</AssignMessage>

範例 2

以下範例會將載入 oas 資料夾中 Proxy 的 OpenAPI 規格資源值，指派給流程變數 assigned-variable，然後將該值設為回應內容中的 Payload：

<AssignMessage name='AM-Response'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>oas://Fulfillment.yaml</ResourceURL>
  </AssignVariable>
  <Set>
    <Payload contentType='application/yaml'>{assigned-variable}</Payload>
  </Set>
</AssignMessage>

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

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

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

<Template 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='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

範例 2

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

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

範例 3

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

<AssignMessage name='AV-template-with-fallback'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <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>` `<StatusCode>` `<Verb>` `<Version>`

如果您在 <Copy> 元素下方未指定任何子元素，系統會複製指定來源訊息的所有部分。

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
    <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</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>
    <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

以下範例會將 request 訊息中的標頭、三個表單參數、路徑和所有查詢參數，複製到名為 newRequest 的新自訂要求：

<AssignMessage name="AM-copy-1">
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1"/>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1"/>
      <FormParam name="Form_Param_Name_2"/>
      <FormParam name="Form_Param_Name_3"/>
    </FormParams>
    <Path>true</Path>
    <QueryParams/>
  </Copy>
</AssignMessage>

由於沒有 <Payload> 和 <Verb> 等元素，因此政策不會複製郵件的這些部分。

範例 2

下例會先移除現有 response 訊息中的所有內容，然後將名為 secondResponse 的其他訊息中的所有值複製到 response 訊息中：

<AssignMessage name='AM-Copy-Response'>
  <AssignTo>response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>

<Copy> 元素具有單一屬性：

屬性說明是否必要類型

來源

屬性	說明	是否必要	類型
來源	指定副本的來源物件。如未指定 `source`，則預設為 `message`，這會根據政策執行的流程而採用不同的值。如果政策在要求流程中執行，則 `message` 變數會參照 `request` 物件。如果政策在回應流程中執行，則 `message` 變數會參照 `response` 物件。如果 `source` 屬性中指定的變數無法解析，或解析為非訊息類型，`<Copy>` 就不會生效。請確認您為 `source` 指定的值與目的地訊息不同，無論是預設目的地訊息，還是使用 `<AssignTo>` 明確指定目的地。如果 `source` 與目的地訊息相同，`<Copy>` 就不會有任何作用。	選用	字串

指定副本的來源物件。

如未指定 source，則預設為 message，這會根據政策執行的流程而採用不同的值。如果政策在要求流程中執行，則 message 變數會參照 request 物件。如果政策在回應流程中執行，則 message 變數會參照 response 物件。
如果 source 屬性中指定的變數無法解析，或解析為非訊息類型，<Copy> 就不會生效。
請確認您為 source 指定的值與目的地訊息不同，無論是預設目的地訊息，還是使用 <AssignTo> 明確指定目的地。如果 source 與目的地訊息相同，<Copy> 就不會有任何作用。

選用

字串

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

從 <Copy> 元素的 source 屬性指定的請求中，將表單參數複製到 <AssignTo> 元素指定的請求。這個元素不會影響回應。

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-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="AM-copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="AM-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="AM-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 只有一個值，則不會複製。

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

來源和目的地的訊息類型皆為要求
來源和目的地的 HTTP 動詞都是 POST 或 PUT
來源訊息的 Content-Type 標頭設為 application/x-www-form-urlencoded。

複製 <FormParams> 時，<Copy> 會將目的地訊息 (由 <AssignTo> 元素指定) 中的 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="VARIABLE_NAME">
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-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="AM-copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="AM-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="VARIABLE_NAME">
    <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>

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

來源和目的地的訊息類型皆為要求

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

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

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- 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 只有一個值，則不會複製。

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

HTTP 動詞：GET、PUT、POST、PATCH、DELETE
來源和目的地的訊息類型皆為要求

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

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

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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 回應狀態碼設為與目標收到的值不同的值。

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

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

如果 true，則會將 <Copy> 元素 source 屬性中的動詞複製到 <AssignTo> 元素中指定的要求。

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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>

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

來源和目的地的訊息類型皆為要求

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

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

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <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>

只有在符合下列條件時，才能使用 <Copy>/<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，Apigee 會忽略所有錯誤，而不只是使用變數時遇到的錯誤。

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

語法

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

範例 1

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

<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

由於 <IgnoreUnresolvedVariables> 設為 true，如果未定義 possibly-defined-variable 變數，這項政策就不會擲回錯誤。

`<Remove>`

從訊息中移除標頭、查詢參數、表單參數和/或訊息酬載。空白的 <Remove> 標記會移除郵件中的所有內容。

受影響的訊息可以是要求或回覆。使用 <AssignTo> 元素指定 <Remove> 要處理的訊息。

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

範例 2

以下範例會從 request 物件中移除所有表單參數和查詢參數：

<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 3

以下範例會從訊息物件中移除所有內容：

<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>

通常只有在您要使用 <Set> 元素或 <Copy> 元素，將一些替代值設定到訊息中時，才會執行這項操作。

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

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 2

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

<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</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" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 2

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

<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

範例 1

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

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 2

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

<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 3

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

<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

HTTP 動詞：GET、POST、PATCH、DELETE
訊息類型：要求

`<Set>`

在要求或回應訊息中設定資訊，由 <AssignTo> 元素指定。<Set> 會覆寫原始郵件中已有的標頭、查詢或表單參數，或新增原始郵件中沒有的參數。

HTTP 訊息中的標頭、查詢和表單參數可能包含多個值。如要為標頭或參數新增其他值，請改用 <Add> 元素。

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

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

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

語法

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Authentication>
      <HeaderName>HEADER_NAME</HeaderName>
      <!-- Use either GoogleAccessToken or GoogleIDToken  -->
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
      </GoogleAccessToken>

    ----- or -----
      <GoogleIDToken>
        <Audience ref='FLOW_VARIABLE_NAME>TARGET_URL</Scope>
      </GoogleAccessToken>
    </Authentication>
    <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>
    <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

以下範例會設定特定標頭。在要求流程中附加這項政策時，上游系統會收到原始傳入要求中未包含的其他標頭。

<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 2

以下範例會覆寫回應的酬載和 Content-Type 標頭。

<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

產生 Google OAuth 2.0 存取權杖或 Google 簽發的 OpenID Connect ID 權杖，並將其設為 Authorization 標頭。當 Proxy 需要對 Google 服務和在特定 Google Cloud 產品 (例如 Cloud Functions 和 Cloud Run) 上執行的自訂服務進行已驗證的呼叫時，這項功能就非常實用。如要使用這個元素，請按照「使用 Google 驗證」一文所述的步驟進行設定及部署。設定完成後，這項政策會為您建立權杖，並將其新增至要求中的適當標頭。

子元素 GoogleAccessToken 和 GoogleIDToken 可讓您設定政策，產生 Google OAuth 或 OpenID Connect 權杖。您可以根據要呼叫的服務需求，選取其中一個子元素。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<Set>`
子元素	`<HeaderName>` `<GoogleAccessToken>` `<GoogleIdToken>`

Authentication 元素使用下列語法：

語法

<AssignMessage>
  ...
  <Set>
    <Authentication>
      <HeaderName>HEADER_NAME</HeaderName>
      --EITHER--
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
            ...
        </Scopes>
      <GoogleAccessToken>

      --OR--
      <GoogleIDToken>
        <Audience ref="FLOW_VARIABLE">TARGET_URL</Audience>
      </GoogleIDToken>

    </Authentication>
  </Set>
  ...
</AssignMessage>

使用存取權杖

以下範例顯示 GoogleAccessToken 元素：

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

使用 ID 權杖

以下範例顯示 GoogleIDToken 元素：

<Authentication>
  <GoogleIDToken>
    <Audience>https://httpserver0-bar.run.app</Audience>
  </GoogleIDToken>
</Authentication>

使用 HeaderName

以下範例顯示 HeaderName 元素：

  <Authentication>
    <HeaderName>Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>https://www.googleapis.com/auth/cloud-platform</Scopes>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

<HeaderName> (`<Authentication>` 的子項)

根據預設，如果存在驗證設定，Apigee 會產生不記名權杖，並將其插入傳送至目標系統的訊息中的 Authorization 標頭。HeaderName 元素可讓您指定其他標頭的名稱，用來保存該不記名權杖。如果存在 Authorization 標頭，則會保留不變，並一併傳送至要求。

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

HeaderName 元素使用下列語法：

語法

<AssignMessage>
...
  <Authentication>
    <HeaderName>HEADER_NAME</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</AssignMessage>

使用靜態字串

在本例中，系統預設會將產生的不記名權杖新增至名為 Authorization 的標頭，並傳送至目標系統。如果存在 Authorization 標頭，則會保留不變，並一併傳送至要求。

<Authentication>
  <HeaderName>Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

含變數參照

在本例中，系統預設會將產生的不記名權杖新增至名為 Authorization 的標頭，並傳送至目標系統。如果 my-variable 有值，系統會使用該值，而非預設字串。如果存在 Authorization 標頭，則會保留不變，並一併傳送至要求。

<Authentication>
  <HeaderName ref='my-variable'>Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scopes>https://www.googleapis.com/auth/cloud-platform</Scopes>
    </Scopes>
  >/GoogleAccessToken>
</Authentication>

<GoogleAccessToken> (`<Authentication>` 的子項)

產生 Google OAuth 2.0 權杖，以便向 Google 服務發出經過驗證的呼叫。Google OAuth 權杖可用於呼叫多種 Google 服務，例如 Cloud Logging 和 Secret Manager。

預設值	不適用
必填與否	必須提供 `GoogleAccessToken` 或 `GoogleIDToken` 子項元素。
類型	字串
父項元素	`<Authentication>`
子元素	`<Scopes>`

GoogleAccessToken 元素使用下列語法：

語法

<AssignMessage>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
    >/GoogleAccessToken>
  </Authentication>
  ...
</AssignMessage>

範例 1

以下範例顯示 GoogleAccessToken 元素：

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scopes>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

<Scopes> (`<GoogleAccessToken>` 的子項)

識別要納入 OAuth 2.0 存取權杖的範圍。詳情請參閱「 Google API 適用的 OAuth 2.0 範圍」。您可以在這個元素下新增一或多個 <Scope> 子項元素。

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

Scopes 元素使用下列語法：

  <Scopes>
    <Scope>SCOPE_1</Scope>
    <Scope>SCOPE_2</Scope>
    ...
  </Scopes>

<Scope> (`<Scopes>` 的子項)

指定有效的 Google API 範圍。詳情請參閱「 Google API 適用的 OAuth 2.0 範圍」。

預設值	不適用
必填與否	至少須輸入一個值。
類型	字串
父項元素	`<Scopes>`
子元素	無

Scope 元素使用下列語法：

  <Scope>SCOPE_1</Scope>

<GoogleIDToken> (`<GoogleAccessToken>` 的子項)

產生 Google 簽發的 OpenID Connect 權杖，以便向 Google 服務發出通過驗證的呼叫。

預設值	不適用
必填與否	必須提供 `GoogleAccessToken` 或 `GoogleIDToken` 子項元素。
類型	字串
父項元素	`<Authentication>`
子元素	`<Audience>`

GoogleIDToken 元素使用下列語法：

語法

<AssignMessage>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="FLOW_VARIABLE_NAME">TARGET_URL</Audience>
    </GoogleIDToken>
  </Authentication>
</AssignMessage>

範例 1

以下範例顯示 GoogleIDToken 元素：

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
  </GoogleIDToken>
</Authentication>

<Audience> (`<GoogleAccessToken>` 的子項)

產生的驗證權杖適用對象，例如權杖授予存取權的 API 或帳戶。

如果 Audience 的值為空白，或 ref 變數無法解析為有效值，且 useTargetUrl 為 true，則目標網址 (不含任何查詢參數) 會做為目標對象。根據預設，useTargetUrl 為 false。

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

Audience 元素使用下列語法：

  <Audience>TARGET_URL</Audience>

or:

  <Audience ref='FLOW_VARIABLE_NAME'/>

`<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="AM-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
訊息類型：要求

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

搭配使用 <Set> 和 <FormParams> 時，Apigee 會將訊息的 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

以下範例會將 x-ratelimit-remaining 標頭設為 ratelimit.Quota-1.available.count 變數的值：

<AssignMessage name="AM-Set-RateLimit-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

注意：

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

以下範例說明政策如何覆寫 target.url。將這項政策附加至 TargetEndpoint 要求後，Proxy 會呼叫下列網址，而非 TargetEndpoint 中定義的網址。

<AssignMessage name="AM-Override-Target-URL">
  ...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>https://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="AM-set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>

範例 2

以下範例會設定 JSON 酬載：

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

範例 3

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

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

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

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

這個舊語法仍可使用。

範例 4

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

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

<AssignMessage name="AM-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 name="AM-set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

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

HTTP 動詞：GET、PUT、POST、PATCH、DELETE
訊息類型：要求

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

`<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="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

範例 2

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

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

只有在符合下列條件時，才能使用 <Set>/<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="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

範例 2

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

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

<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

只有在符合下列條件時，才能使用 <Set>/<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="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>

範例 2

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

<AssignMessage name="AM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

訊息類型：要求

建立自訂要求訊息

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

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

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

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

根據預設，Apigee 不會對自訂要求訊息執行任何操作。建立後，Apigee 會繼續透過原始要求完成流程。如要使用自訂要求，請將 ServiceCallout 政策等政策新增至 Proxy，並在該政策的設定中明確參照新建立的要求訊息。這樣您就能將自訂要求傳遞至外部服務端點。

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

範例 1

以下範例會使用 AssignMessage 建立自訂要求物件：

<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> 未指定 source 屬性，Apigee 會使用 request 訊息做為複製 from 的來源。
- 將自訂訊息的 address 查詢參數設為傳入要求 addy 查詢參數的值。
- 將 HTTP 動詞設為 GET。
將 <IgnoreUnresolvedVariables> 設為 false。當 <IgnoreUnresolvedVariables> 為 false 時，如果政策設定中參照的其中一個變數不存在，Apigee 會在 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 政策中，存取自訂訊息的各種屬性。以下範例會從具名的自訂回應中取得標頭值，並將其放入要求訊息的新標頭中：

<AssignMessage name="AM-Copy-Custom-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</AssignMessage>

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼 HTTP 狀態原因修正

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

steps.assignmessage.VariableOfNonMsgType

500

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

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

steps.assignmessage.UnresolvedVariable

500

如果 AssignMessage 政策中指定的變數為下列任一情況，就會發生此錯誤：

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

部署錯誤

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

錯誤名稱	原因	修正
`InvalidIndex`	如果 `AssignMessage` 政策的 `<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="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：取得 ServiceCallout 回應標頭

8：儲存及移除表單參數、標頭、查詢參數

子元素參照

<Add>

語法

範例 1

範例 2

範例 3

<FormParams> (<Add> 的子項)

語法

範例 1

範例 2

範例 3

<Headers> (<Add> 的子項)

語法

範例 1

<QueryParams> (<Add> 的子項)

語法

範例 1

<AssignTo>

語法

範例 1

範例 2

範例 3

<AssignVariable>

語法

範例 1

範例 2

範例 3

範例 4

<Name> (<AssignVariable> 的子項)

語法

範例 1

<PropertySetRef> (<AssignVariable> 的子項)

語法

範例 1

範例 2

<Ref> (<AssignVariable> 的子項)

語法

範例 1

範例 2

範例 3

<ResourceURL> (<AssignVariable> 的子項)

語法

範例 1

範例 2

<Template> (<AssignVariable> 的子項)

語法

範例 1

範例 2

範例 3

<Value> (<AssignVariable> 的子項)

語法

範例 1

範例 2

<Copy>

語法

範例 1

範例 2

<FormParams> (<Copy> 的子項)

語法

範例 1

範例 2

範例 3

範例 4

<Headers> (<Copy> 的子項)

AssignMessage 政策

`<AssignMessage>` 元素

`<Add>`

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

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

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

`<AssignTo>`

`<AssignVariable>`

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

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

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

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

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

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

`<Copy>`

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

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

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

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

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

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

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

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

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<Remove>`

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

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

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

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

`<Set>`

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

<HeaderName> (`<Authentication>` 的子項)

<GoogleAccessToken> (`<Authentication>` 的子項)

<Scopes> (`<GoogleAccessToken>` 的子項)