AssignMessage 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

「AssignMessage」政策可變更現有的請求或回應訊息，或在 API 代理程式流程中建立新的請求或回應訊息。 這項政策可讓您對這些訊息執行下列動作：

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

您也可以使用 AssignMessage 設定任意內容變數，不受上述任何可能套用至訊息的作業影響。

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

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

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

<AssignMessage> 元素

定義 AssignMessage 政策。

預設值 請參閱下方的「Default Policy」分頁
是否必要？ 必填
類型 複雜物件
上層元素 N/A
子元素 <Add>
<AssignTo>
<AssignVariable>
<Copy>
<DisplayName>
<IgnoreUnresolvedVariables>
<Remove>
<Set>

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

語法

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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- All AssignMessage child elements are optional -->
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>

  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>

  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <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 政策時，範本會包含所有可能作業的 Stub。通常，您會選取要透過這項政策執行哪些作業，並移除其他子元素。舉例來說，如果您要執行複製作業，請使用 <Copy> 元素，並從政策中移除 <Add>、<Remove> 和其他子元素，讓政策更易讀。

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

屬性 預設 是否必要？ 說明
name 不適用 必要

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

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
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="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 政策：

  1. 在要求中建立三個流程變數，並使用靜態值
  2. 在要求流程中，以動態方式在第二個政策中取得流程變數
  3. 在回應的酬載中設定
<!-- 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. 將政策 #1 和 #2 新增至要求流程。請務必將政策 #1 放在政策 #2 的前面。
  2. 在「回應」流程中新增第三個政策。
  3. 第三個政策使用 <Set> 元素，將變數新增至回應。以下範例會在 Edge 傳回給用戶端的回應中建構 XML 酬載：
    <!-- Policy #3: Add variables to the response -->
<AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
  <DisplayName>put-em-in-the-payload</DisplayName>
  <Set>
    <Payload contentType="application/xml">
      <wrapper>
        <secret>{secret}</secret>
        <config>
          <environment>{environment}</environment>
          <protocol>{protocol}</protocol>
        </config>
      </wrapper>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

    請注意，如要在 <Set> 中存取流程變數，語法必須將這些變數放在大括號內。

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

  4. 傳送要求至 API Proxy，例如：
    curl -vL https://ahamilton-eval-test.apigee.net/myproxy

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

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

    回應主體應如下所示：

    
  42
  
    test
    gopher

7：取得 ServiceCallout 回應標頭

在下列範例中，假設 API 代理要求包含 ServiceCallout 政策，且說明文字回應包含多個同名標頭 (Set-Cookie)。假設 ServiceCallout 的回應變數為預設的 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>

此參考資料中的每個子元素都有其他範例。如需更多範例，請參閱 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

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

<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>。如果您在工具 (例如「Debug 總覽」) 中查看結果，對 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 會根據這項政策在流程中執行的位置，建立要求或回應。

 選用 字串

<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> 會建立這個物件。

<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> 元素中混合使用流程變數和字串常值。詳情請參閱下列示例。

<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 代理程式要求會使用名為 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、屬性集或 OpenAPI 規格。

預設值 不適用
是否必要？ 選用
類型 字串
上層元素 <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

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

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

範例 2

以下範例會將 OpenAPI 規格資源的值指派至流程變數 assigned-variable，該值已載入至 oas 資料夾中的 Proxy，然後將該值設為回應本文中的 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 createNew="false" transport="http" type="response">response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>

<Copy> 元素只有一個屬性：

屬性 說明 是否必要 類型
來源

指定複本的來源物件。

  • 如果未指定 source，則預設為 message，而 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="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> 的子項)

將 HTTP 標頭從 由 <Copy> 元素的 source 屬性指定的要求或回應訊息，複製至 由 <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="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="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>

只有在符合下列條件時，才能使用 <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 只有一個值，則不會複製。

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

  • HTTP 動詞：GET、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>

只有在來源和目的地訊息類型為 Response 時，才能使用 <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>

只有在符合下列條件時，才能使用 <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>

只有在符合下列條件時，才能使用 <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

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

<AssignMessage name="AM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </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 只有一個值，則不會移除。

範例 4

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

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

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

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

<Set>

在要求或回應訊息中設定資訊，這由 <AssignTo> 元素指定。<Set> 會覆寫原始訊息中已存在的標頭或查詢或表單參數，如果不存在，則會新增。

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

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

<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 權杖，以便對特定 Google Cloud 產品 (例如 Cloud Functions 和 Cloud Run) 執行的 Google 服務和自訂服務發出經過驗證的呼叫。如要使用這個元素，您必須按照「使用 Google 驗證」一文所述的步驟進行設定和部署作業。在適當的設定下，政策會為您建立驗證權杖，並將其新增至服務要求。

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

預設值 不適用
是否必要？ 選用
類型 複雜類型
上層元素 <Set>
子元素 <HeaderName>
<GoogleAccessToken>
<GoogleIdToken>

Authentication 元素使用以下語法：

語法

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

    --OR--
  <HeaderName>HEADER_NAME</HeaderName>
    <GoogleIDToken>
      <Audience ref="FLOW_VARIABLE" TARGET_URL</Audience>
    </GoogleIDToken>
  </Authentication>
</Set>

使用 GoogleAccessToken

以下範例顯示 GoogleAccessToken 元素：

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

使用 GoogleIDToken

以下範例顯示 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>
子元素 None

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>
子元素 None

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。

預設值 不適用
是否必要？ 必填
類型 字串
上層元素
子元素 None

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
  • 訊息類型：要求

如果您在政策 (<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

以下範例會將 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> 的子項)

<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 中 (例如，雲端版本 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 name="AM-set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

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

  • HTTP 動詞：GET、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>

只有在符合下列條件時，才能使用 <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>

只有在符合下列條件時，才能使用 <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> 的內容視為訊息範本。也就是說，在執行階段，以大括號包圍的變數名稱會替換為參照變數的值。

只有在符合下列條件時，才能使用 <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 訊息做為來源，從複製內容。
    • 將自訂訊息的 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

錯誤回應範例

{  
   "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 政策的 API 平台範例提供可用的範例。

如要進一步瞭解如何覆寫 ProxyEndpoint 中的 target.url，請參閱這篇 Apigee 社群文章。

如要查看 ServiceCallout 政策中設定路徑的實際運作情形，請參閱 Apigee GitHub 範例中的實作範例。只要複製存放區，然後按照該主題中的操作說明進行即可。這個範例會使用 AssignMessage 設定要求路徑，然後使用 ServiceCallout 政策向外部服務提出要求。