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

ExtractVariables 政策
透過集合功能整理內容你可以依據偏好儲存及分類內容。

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

ExtractVariables 政策會從要求或回應中擷取內容，並將變數的值設為該內容。您可以擷取訊息的任何部分，包括標頭、URI 路徑、JSON/XML 酬載、表單參數和查詢參數。這項政策會將文字模式套用至郵件內容，並在找到相符項目時，設定含有指定郵件內容的變數。

雖然您經常使用 ExtractVariables 從要求或回應訊息中擷取資訊，但也可以用來從其他來源擷取資訊，包括由 AccessEntity 政策、XML 物件或 JSON 物件建立的實體。

擷取指定的訊息內容後，您可以在處理要求和回應時，參照其他政策中的變數。

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

影片

請觀看下列影片，進一步瞭解「ExtractVariables」政策。

影片	說明
從 XML 酬載中擷取變數	使用「擷取變數」政策，從 XML 酬載中擷取變數。
從 JSON 酬載擷取變數	使用「擷取變數」政策，從 JSON 酬載中擷取變數。
從參數中擷取變數	從查詢、標頭、表單或 URI 參數等參數中擷取變數。
從多值參數擷取變數	從多值參數中擷取變數。

範例

以下政策程式碼範例說明如何從下列類型的構件中擷取變數：

URI

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

請參考上述政策程式碼範例。<URIPath> 元素會告知 ExtractVariables 政策從 URI 路徑中擷取資訊。<Pattern> 元素會指定要套用至 URI 路徑的模式。系統會將模式視為簡單的範本，其中的尖括號代表 URI 路徑的不同部分。

要設定的變數名稱取決於 <VariablePrefix> 元素中指定的值，以及 <Pattern> 元素中大括號 {} 內的值。這兩個值會透過中間的點連接，例如變數名稱 urirequest.id。如果沒有 <VariablePrefix> 元素，變數名稱就是以大括號包圍的值。

請考慮使用上述政策程式碼範例搭配下列傳入要求：

GET http://example.com/svc1/accounts/12797282

假設 API Proxy 的 basepath 為 /svc1。當 Apigee 將上述 ExtractVariables 政策程式碼套用至此傳入要求時，會將變數 urirequest.id 設為 12797282。Apigee 執行政策後，處理流程中的後續政策或程式碼可以參照名為 urirequest.id 的變數，取得字串值 12797282。

舉例來說，下列 AssignMessage 政策會將該變數的值嵌入新要求訊息的酬載：

<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload">
  <DisplayName>AssignPayload</DisplayName>
    <Set>
      <Payload contentType="text/xml">
        <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI>
      </Payload>
    </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
</AssignMessage>

查詢參數

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

請考慮使用上述政策程式碼範例搭配下列傳入要求：

GET http://example.com/accounts/12797282?code=DBN88271

當 Apigee 將上述 ExtractVariables 政策程式碼套用至此傳入要求時，會將變數 queryinfo.dbncode 設為 88271。Apigee 執行政策後，處理流程中的後續政策或程式碼可以參照名為 queryinfo.dbncode 的變數，取得字串值 88271。

您現在可以在 Proxy 中存取變數 queryinfo.dbncode。舉例來說，下列 AssignMessage 政策會將訊息複製到要求的酬載：

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

多個參數

<ExtractVariables name="ExtractVariables-2">
  <DisplayName>Extract a value from a query parameter</DisplayName>
  <Source>request</Source>
  <QueryParam name="w">
    <Pattern ignoreCase="true">{firstWeather}</Pattern>
  </QueryParam>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondWeather}</Pattern>
  </QueryParam>
  <VariablePrefix>queryinfo</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

假設您的 API 設計允許您指定多個同名的查詢參數。您可以使用「擷取變數」政策，擷取查詢參數的多個例項值。如要在政策中參照同名的查詢參數，請使用索引，其中第一個查詢參數例項沒有索引，第二個例項的索引為 2，第三個例項的索引為 3，以此類推。

請考慮使用上述政策程式碼範例搭配下列傳入要求：

GET http://example.com/weather?w=Boston&w=Chicago

當 Apigee 將上述 ExtractVariables 政策程式碼套用至此傳入要求時，會將變數 queryinfo.firstWeather 設為 Boston，並將變數 queryInfo.secondWeather 設為 Chicago。

您現在可以在 Proxy 中存取變數 queryinfo.firstWeather 和 queryinfo.secondWeather。舉例來說，下列 AssignMessage 政策會將訊息複製到要求的酬載：

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
      <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

標頭

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

假設您的 API 使用 OAuth 2.0 不記名憑證。請考慮使用上述政策範例程式碼，搭配含有 OAuth 2.0 權杖的請求，該權杖包含以下標頭：Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

假設您是 API 設計者，且想在快取查詢中使用符記值 (而非整個標頭) 做為索引鍵。您可以使用上述的 ExtractVariables 政策程式碼來擷取符記。

當 Apigee 將上述 ExtractVariables 政策程式碼套用至此標頭時，會將變數 clientrequest.oauthtoken 設為 TU08xptfFfeM7aS0xHqlxTgEAdAM。

您現在可以在 Proxy 中存取變數 clientrequest.oauthtoken。舉例來說，下列 AssignMessage 政策會將訊息複製到要求的酬載：

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetHeader</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

JSON

<ExtractVariables name="ExtractVariables-3">
  <Source>response</Source>
  <JSONPayload>
    <Variable name="latitude" type="float">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude" type="float">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
  <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

請參考下列 JSON 回應酬載：

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

當 Apigee 將上述 ExtractVariables 政策程式碼套用至此 JSON 訊息時，會設定兩個變數：geocoderesponse.latitude 和 geocoderesponse.longitude。兩個變數都使用相同的變數前置字元 geocoderesponse。這些變數的後置字串由 <Variable> 元素的 name 屬性明確指定。

變數 geocoderesponse.latitude 會取得 37.42291810 的值。變數 geocoderesponse.longitude 會取得 -122.08542120 的值。

您現在可以在 Proxy 中存取變數 geocoderesponse.latitude。舉例來說，下列 AssignMessage 政策會將訊息複製到回應中名為 latitude 的標頭：

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

XML

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>

請參考下列 XML 回應酬載：

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</Directions>

當 Apigee 將上述 ExtractVariables 政策程式碼套用至此 XML 訊息時，會設定三個變數：

directionsresponse.travelmode：取得 DRIVING 的值
directionsresponse.duration：取得 19 的值
directionsresponse.timeunit：取得 minutes 的值

所有變數都使用相同的變數前置字串 directionsresponse。這些變數的後置字串由 <Variable> 元素的 name 屬性明確指定。

您現在可以在 Proxy 中存取變數 directionresponse.travelmode。舉例來說，下列 AssignMessage 政策會將其複製到回應中名為 tmode 的標頭：

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

注意： 設定 Content-Type：從 XML 訊息 (包括 SOAP) 中擷取變數時，變數擷取作業僅會在訊息標頭 (或 SOAP 標頭) 中設定 Content-Type 時運作，例如 application/xml。

關於「ExtractVariables」政策

API 開發人員會建構 API Proxy，這些 Proxy 的行為會根據訊息內容而有所不同，包括標頭、URI 路徑、酬載和查詢參數。代理程式通常會擷取這類內容的部分內容，用於條件陳述式。請使用「ExtractVariables」政策執行這項操作。

定義「ExtractVariables」政策時，您可以選擇：

要設定的變數名稱
變數來源
要擷取及設定的變數數量

執行時，政策會將文字模式套用至內容，並在找到相符項目後，將內容設為指定變數的值。其他政策和程式碼可以使用這些變數來啟用動態行為，或將業務資料傳送至 Apigee API Analytics。

範圍

使用 ExtractVariables 政策設定的變數具有全域範圍。也就是說，在 ExtractVariables 政策定義新變數後，您可以在流程的任何階段 (在 ExtractVariables 政策「後」執行) 透過任何政策或程式碼存取該變數。包括：

PreFlow：ProxyEndpoint 和 TargetEndpoint (要求和回應)
PostFlow：ProxyEndpoint 和 TargetEndpoint (要求和回應)
PostClientFlow：ProxyEndpoint (僅限回應，使用MessageLogging 政策)
錯誤流程

提示：如果您沒有在偵錯工具中看到新擷取的變數，請嘗試移除您新增的 <VariablePrefix> 元素。詳情請參閱這篇文章，瞭解如何擷取在追蹤記錄中未顯示的變數。

關於比對和變數建立

「ExtractVariables」政策會從要求或回應中擷取資訊，並將該資訊寫入變數。針對每種可擷取的資訊類型 (例如 URI 路徑或 XML 資料)，您都必須指定要比對的模式，以及用於儲存擷取資訊的變數名稱。

不過，模式比對的運作方式取決於擷取來源。以下各節將說明您可以擷取的兩種基本資訊類別。

比對 URI 路徑、查詢參數、標頭、表單參數和變數

從 URI 路徑、查詢參數、標頭、表單參數和變數中擷取資訊時，您可以使用 <Pattern> 標記指定一或多個要比對的模式。舉例來說，以下政策示例顯示 URI 路徑的單一比對模式：

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

在這個範例中，urirequest.pathSeg 變數會設為 proxy.pathsuffix 在 /a/ 後方顯示的任何內容。舉例來說，假設 API Proxy 的基本路徑為 /basepath/v1。傳入 http://myCo.com/basepath/v1/a/b 的要求，變數會設為 b。

指定多個模式

您可以指定多個比對模式，對應至 <Pattern> 標記，其中：

系統會測試所有模式是否相符。
如果沒有任何模式相符，政策就不會執行任何動作，也不會建立變數。
如果有多個模式相符，系統會使用路徑區段最長的模式進行擷取。
如果兩個比對模式具有相同的最長路徑區段，系統會使用政策中首先指定的模式進行擷取。

在下一個範例中，您會建立包含三個 URI 路徑比對模式的政策：

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

假設 API Proxy 的 basepath 為 /basepath/v1，API Proxy 的內送要求網址會是以下形式：

http://myCo.com/basepath/v1/a/b

在這個範例中，第一個模式會比對 URI，而 urirequest.pathSeg 變數會設為 b。

如果要求網址為：

http://myCo.com/basepath/v1/a/b/c/d

...則第三個模式會比對成功，並將 urirequest.pathSeg 變數設為 d。

指定含有多個變數的模式

您可以在比對模式中指定多個變數。例如，您可以指定包含兩個變數的比對模式：

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

再次假設 API Proxy 的基準路徑為 /basepath/v1，針對傳入要求的網址：

http://myCo.com/basepath/v1/a/b/c/d

...將 urirequest.pathSeg1 變數設為 b，並將 urirequest.pathSeg2 變數設為 d。

比對模式中的多個例項

當項目有多個同名實例時，您也可以比對模式。舉例來說，您可以提出包含多個查詢參數或多個同名標頭的要求。以下要求包含兩個名為「w」的查詢參數：

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

如要在「擷取變數」政策中參照這些查詢參數，請使用索引，其中查詢參數的第一個例項沒有索引，第二個例項的索引為 2，第三個例項的索引為 3，以此類推。例如，下列政策會擷取要求中名為「w」的第二個查詢參數值：

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondW}</Pattern>
  </QueryParam>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

urirequest.secondW 變數設為「2」。如果要求中省略第二個查詢參數，urirequest.secondW 變數就會為空白。在要求中使用索引，以便在有相同名稱的多個項目時進行分類。

在模式中使用特殊字元

比對 URI 路徑時，您可以在模式中使用「*」和「**」萬用字元，其中：

「*」可比對路徑的任一片段
「**」會比對路徑的多個片段

例如，您可以為 <URIPath> 元素指定模式，如下所示：

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

第一個模式會比對含有路徑後置字串 (URI 路徑中 basepath 後面的部分) 的要求，例如「/a/b/c」、「/a/foo/bar」等。第二個模式會比對「/a/」後面的任意路徑區段，例如「/a/foo/bar/baz/c」、「/a/b/c」和「/a/foo/bar」。

指定查詢參數、標頭和表單參數的模式時，「*」字元會指定比對任意數量的字元。舉例來說，比對標頭時，請指定模式如下：

*;charset={encoding}

這個模式會比對「text/xml;charset=UTF-16」和「application/xml;charset=ASCII」的值。

如果傳遞至 ExtractVariables 政策的值包含特殊字元 (例如「{」)，請使用「%」字元來逸出這些字元。以下範例會逸出模式中的「{」和「}」字元，因為這些字元會用於查詢參數的值中做為文字字元：

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

在這個範例中，模式會比對值「{user} Steve」，但不會比對值「user Steve」。

比對 JSON 和 XML

從 JSON 和 XML 擷取資料時，您可以在政策中指定一或多個 <Variable> 標記。<Variable> 標記會指定儲存擷取資訊的目的地變數名稱，以及擷取資訊的 JsonPath (JSON) 或 XPATH (XML)。

系統會評估政策中的所有 <Variable> 標記，讓您從單一政策填入多個變數。如果 <Variable> 標記在 JSON 或 XML 中評估為無效欄位，系統就不會建立對應的變數。

以下範例顯示 ExtractVariables 政策，可從回應的 JSON 主體填入兩個變數：

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

在多個位置寫入相同變數

請謹慎選擇要設定的變數名稱。政策會依序從第一個擷取模式執行到最後一個。如果政策從多個位置將值寫入相同的變數，則政策中最後一次寫入的值會決定變數的值。(這可能就是您想要的結果。)

舉例來說，您想擷取可在查詢參數或標頭中傳遞的符記值，如下所示：

<!-- If token only in query param, the query param determines the value. 
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>
 
<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

控管未找到相符項目時的處理方式

如果模式不相符，系統就不會建立對應的變數。因此，如果其他政策參照變數，可能會導致錯誤。

其中一個做法是在參照變數的政策中將 <IgnoreUnresolvedVariables> 設為 true，藉此將任何無法解析的變數視為空字串 (空值)：

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

元素參照

元素參考資料說明瞭 ExtractVariables 政策的元素和屬性。

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName> 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>/test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

<ExtractVariables> 屬性

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

下表說明所有政策父項元素的共同屬性：

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

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，系統會使用政策的 `name` 屬性值。
存在必要性	選用
類型	字串

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。

存在必要性選用

類型字串

<Source> 元素

(選用) 指定要剖析的變數。<Source> 的值預設為 message。message 值會依據情境而有所不同。在要求流程中，message 會解析為要求訊息。在回應流程中，message 會解析為回應訊息。

雖然您通常會使用這項政策從要求或回應訊息中擷取資訊，但也可以用來從任何變數中擷取資訊。舉例來說，您可以使用這項功能從 AccessEntity 政策建立的實體、ServiceCallout 政策傳回的資料，或從 XML 或 JSON 物件中擷取資訊。

如果無法解析 <Source>，或解析為非訊息類型，政策就會無法回應。

<Source clearPayload="true|false">request</Source>

預設值：	訊息
外觀狀態：	選用
類型：	字串

屬性

屬性說明預設存在必要性類型

屬性	說明	預設	存在必要性	類型
`clearPayload`	如果您想在從 `<Source>` 中擷取資料後清除其中指定的酬載，請將此屬性設為 true。只有在執行 ExtractVariables 後，來源訊息並非必要時，才使用 `<clearPayload>` 選項。將其設為 true 可釋出訊息使用的記憶體。	false	選用	布林值

clearPayload

如果您想在從 <Source> 中擷取資料後清除其中指定的酬載，請將此屬性設為 true。

只有在執行 ExtractVariables 後，來源訊息並非必要時，才使用 <clearPayload> 選項。將其設為 true 可釋出訊息使用的記憶體。

false

選用

布林值

<VariablePrefix> 元素

(選用) 如要建立完整的變數名稱，請在 <Pattern> 元素或 <Variable> 元素中，將 <VariablePrefix>、一個點號和您在 {大括號} 中定義的名稱連結在一起。例如：myprefix.id、myprefix.dbncode 或 myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

舉例來說，假設名稱的值為「user」。

如果未指定 <VariablePrefix>，系統會將擷取的值指派給名為 user 的變數。
如果 <VariablePrefix> 指定為 myprefix，系統會將擷取的值指派給名為 myprefix.user 的變數。

預設值：	不適用
外觀狀態：	選用
類型：	字串

<IgnoreUnresolvedVariables> 元素

(選用) 將其設為 true，即可將任何無法解析的變數視為空字串 (空值)。如果您希望政策在任何參照變數無法解析時擲回錯誤，請將其設為 false。

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

預設值：	否
外觀狀態：	選用
類型：	布林值

<URIPath> 元素

(選用，但請參閱下表中的「狀態」列，瞭解詳情)。從 request 來源訊息的 proxy.pathsuffix 擷取值。套用至模式的路徑為 proxy.pathsuffix，不包含 API Proxy 的 basepath。如果來源訊息解析為 response 的訊息類型，則此元素不會執行任何操作。

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

您可以使用多個 <Pattern> 元素：

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>

預設值：	不適用
外觀狀態：	(非必要) 不過，您必須至少加入下列其中一個屬性：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
ignoreCase	指定在比對模式時忽略大小寫。	false	選用	布林值

<QueryParam> 元素

(選用，但請參閱下表中的「狀態」列，瞭解詳情)。從 request 來源訊息的指定查詢參數中擷取值。如果來源訊息解析為 response 的訊息類型，則此元素不會執行任何操作。

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

如果多個查詢參數具有相同名稱，請使用索引參照參數：

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>

預設值：	不適用
外觀狀態：	(非必要) 不過，您必須至少加入下列其中一個屬性：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
名稱	指定查詢參數的名稱。如果多個查詢參數具有相同名稱，請使用索引參照，其中查詢參數的第一個例項沒有索引，第二個例項位於索引 2，第三個例項位於索引 3 等等。	不適用	必填	字串

<Header> 元素

(選用，但請參閱下表中的「狀態」列，瞭解詳情)。從指定 request 或 response 訊息的指定 HTTP 標頭擷取值。如果有多個標頭具有相同的名稱，其值會儲存在陣列中。

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

如果有多個標頭具有相同名稱，請使用索引參照陣列中的個別標頭：

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

或者，您也可以使用下列指令列出陣列中的所有標頭：

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>

預設值：	不適用
外觀狀態：	(非必要) 不過，您必須至少加入下列其中一個屬性：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
名稱	指定要從中擷取值的標頭名稱。如果有多個標頭具有相同名稱，請使用索引參照，其中標頭的第一個例項沒有索引、第二個例項的索引為 2，第三個例項的索引為 3 等等。請使用 `.values` 取得陣列中的所有標頭。	不適用	必填	字串

<FormParam> 元素

(選用，但請參閱下表中的「狀態」列，瞭解詳情)。從指定 request 或 response 訊息的指定表單參數中擷取值。只有在指定訊息的 Content-Type 標頭為 application/x-www-form-urlencoded 時，才能擷取表單參數。

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>

預設值：	不適用
外觀狀態：	(非必要) 不過，您必須至少加入下列其中一個屬性：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
名稱	您要從中擷取值的表單參數名稱。	不適用	必填	字串

<Variable> 元素

(選用，但請參閱下表中的「狀態」列，瞭解詳情)。指定要從中擷取值的變數名稱。

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

如要從變數中擷取兩個值，請按照下列步驟操作：

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>

預設值：	不適用
外觀狀態：	(非必要) 不過，您必須至少加入下列其中一個屬性：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
名稱	要擷取值的變數名稱。	不適用	必填	字串

<JSONPayload> 元素

(選用，但請參閱下表中的「狀態」列，瞭解詳情)。指定要從中擷取變數值的 JSON 格式訊息。只有在訊息的 Content-Type 標頭為 application/json 時，才會執行 JSON 擷取作業。

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>

預設值：	不適用
外觀狀態：	(非必要) 不過，您必須至少加入下列其中一個屬性：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

<JSONPayload>/<Variable> 元素

(JSONPayload 元素中必填項目)。指定指派擷取值的變數。您可以在 <JSONPayload> 元素中加入多個 <Variable> 標記，為多個變數填入資料。

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>

預設值：	不適用
外觀狀態：	這是 JSONPayload 元素中必要的屬性。
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
名稱	指定要將擷取的值指派給哪個變數。	名稱	必填	字串
類型	指定變數值的資料類型。	不適用	選用	字串。可用的選項如下：字串布林值整數 long 浮點數雙精度值 nodeset (傳回 JSON 片段)

說明

預設

存在必要性

類型

名稱

指定要將擷取的值指派給哪個變數。

名稱

必填

字串

類型

指定變數值的資料類型。

不適用

選用

字串。可用的選項如下：

字串
布林值
整數
long
浮點數
雙精度值
nodeset (傳回 JSON 片段)

<JSONPayload>/<Variable>/<JSONPath> 元素

(JSONPayload:Variable 元素中必填)。指定用於從 JSON 格式訊息中擷取值的 JSON 路徑。

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

<Variable name="name">
  <JSONPath>$.rss.channel.title</JSONPath>
</Variable>

預設值：	不適用
外觀狀態：	必填
類型：	字串

<XMLPayload> 元素

(選用，但請參閱下表中的「狀態」列，瞭解詳情)。指定 XML 格式訊息，系統會從中擷取變數的值。只有在郵件 Content-Type 標頭為 text/xml、application/xml 或 application/*+xml 時，系統才會擷取 XML 酬載。

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
    <Namespace prefix="apigee">http://www.apigee.com</Namespace>
    <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
    <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>

預設值：	不適用
外觀狀態：	(非必要) 不過，您必須至少加入下列其中一個屬性：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
`stopPayloadProcessing`	將其設為 `true`，即可在填入一個變數後停止 XPath 評估。也就是說，政策只會填入單一變數。	false	選用	布林值

<XMLPayload>/<Namespaces> 元素

(選用) 指定在 XPath 評估中要使用的命名空間。如果您在 XPath 運算式中使用命名空間，則必須在此宣告命名空間，如以下範例所示。

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

如果您未在 XPath 運算式中使用命名空間，可以省略或註解 <Namespaces> 元素，如以下範例所示：

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>

預設值：	不適用
外觀狀態：	選用
類型：	字串

屬性

屬性	說明	預設	存在必要性	類型
`prefix`	命名空間前置字串。	不適用	必填	字串

<XMLPayload>/<Variable> 元素

(選用) 指定要指派擷取值的變數。

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

預設值：	不適用
外觀狀態：	選用
類型：	不適用

屬性

屬性	說明	預設	存在必要性	類型
名稱	指定要將擷取的值指派給哪個變數。	名稱	必填	字串
類型	指定變數值的資料類型。	布林值	選用	字串。可用的選項如下：字串布林值整數 long 浮點數雙精度值 nodeset (傳回 XML 片段)

說明

預設

存在必要性

類型

名稱

指定要將擷取的值指派給哪個變數。

名稱

必填

字串

類型

指定變數值的資料類型。

布林值

選用

字串。可用的選項如下：

字串
布林值
整數
long
浮點數
雙精度值
nodeset (傳回 XML 片段)

<XMLPayload>/<Variable>/<XPath> 元素

(必須在 XMLPayload:Variable 元素中使用)。指定為變數定義的 XPath。僅支援 XPath 1.0 運算式。

<XPath> 元素不支援訊息範本。

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

命名空間範例。如果您在 XPath 運算式中使用命名空間，則必須在政策的 <XMLPayload><Namespaces> 部分宣告命名空間。

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>

預設值：	不適用
外觀狀態：	必填
類型：	字串

注意：Apigee 不支援在 XPath 運算式中使用 parent、ancestor、following 和 preceding。如要取得相同的配對結果，請嘗試使用明確的節點名稱比對或索引。例如：

<XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
會取得 foo_attribute 的值。
<XPath>/Attributes/Attribute[4]/Value</XPath>
會取得第 4 個屬性的值。

錯誤參考資料

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

執行階段錯誤

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

錯誤代碼	HTTP 狀態	原因	修正
`steps.extractvariables.ExecutionFailed`	`500`	發生這個錯誤的原因如下：輸入酬載 (JSON、XML) 為空白。傳遞至政策的輸入內容 (JSON、XML 等) 無效或格式錯誤。
`steps.extractvariables.ImmutableVariable`	`500`	政策中使用的變數是不可變動的。政策無法設定這個變數。	不適用
`steps.extractvariables.InvalidJSONPath`	`500`	如果在政策的 `JSONPath` 元素中使用無效的 JSON 路徑，就會發生這個錯誤。舉例來說，如果 JSON 酬載沒有 `Name` 物件，但您在政策中將 `Name` 指定為路徑，就會發生這個錯誤。
`steps.extractvariables.JsonPathParsingFailure`	`500`	當政策無法剖析 JSON 路徑，並從 `Source` 元素中指定的流程變數中擷取資料時，就會發生這項錯誤。通常，如果 `Source` 元素中指定的流程變數不存在於目前流程中，就會發生這種情況。
`steps.extractvariables.SetVariableFailed`	`500`	如果政策無法將值設為變數，就會發生這項錯誤。一般來說，如果您嘗試將值指派給多個變數，且這些變數的名稱以同一個字詞開頭，且採用以點分隔的巢狀格式，就會發生此錯誤。
`steps.extractvariables.SourceMessageNotAvailable`	`500`	如果政策的 `Source` 元素中指定的 message 變數為下列任一情況，就會發生這個錯誤：超出範圍 (無法在執行政策的特定流程中使用)，或無法解析 (未定義)
`steps.extractvariables.UnableToCast`	`500`	如果政策無法將擷取的值轉換為變數，就會發生此錯誤。通常，如果您嘗試將某個資料類型的值設為另一個資料類型的變數，就會發生這種情況。

部署錯誤

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

錯誤名稱	原因	修正
`NothingToExtract`	如果政策沒有任何 `URIPath`、`QueryParam`、`Header`、`FormParam`、`XMLPayload` 或 `JSONPayload` 元素，則由於沒有任何可擷取的內容，因此 API Proxy 的部署作業會失敗。
`NONEmptyPrefixMappedToEmptyURI`	如果政策在 `XMLPayload` 元素下的 `Namespace` 元素中定義了前置字串，但未定義 URI，就會發生這個錯誤。
`DuplicatePrefix`	如果政策在 `XMLPayload` 元素下的 `Namespace` 元素中定義了相同的前置字串，就會發生這個錯誤。
`NoXPathsToEvaluate`	如果政策的 `XMLPayload` 元素中沒有 `XPath` 元素，API 代理程式會因這項錯誤而無法部署。如要從 XML 酬載中擷取變數，請務必指定 `XPath` 子元素。
`EmptyXPathExpression`	如果政策在 `XMLPayload` 元素中包含空白的 `XPath` 運算式，API Proxy 的部署作業就會失敗。
`NoJSONPathsToEvaluate`	如果政策的 `JSONPayload` 元素中沒有 `JSONPath` 元素，API 代理程式會因這項錯誤而無法部署。
`EmptyJSONPathExpression`	如果政策在 `XMLPayload` 元素中包含空白的 `XPath` 運算式，API Proxy 的部署作業就會失敗。
`MissingName`	如果政策在任何需要 `name` 屬性的政策元素 (例如 `QueryParam`、`Header`、`FormParam` 或 `Variable`) 中，都沒有 `name` 屬性，則 API 代理程式會部署失敗。
`PatternWithoutVariable`	如果政策在 `Pattern` 元素中未指定變數，API 代理程式就會部署失敗。`Pattern` 元素需要變數名稱，用於儲存擷取的資料。
`CannotBeConvertedToNodeset`	如果政策含有 `XPath` 運算式，其中 `Variable` 類型定義為 nodeset，但運算式無法轉換為 nodeset，則 API Proxy 的部署作業會失敗。
`JSONPathCompilationFailed`	政策無法編譯指定的 JSON 路徑。	不適用
`InstantiationFailed`	無法將政策例項化。	不適用
`XPathCompilationFailed`	如果 `XPath` 元素中使用的前置字串或值並非政策中宣告的任何命名空間的一部分，則 API 代理程式會無法部署。
`InvalidPattern`	如果 `Pattern` 元素定義在政策中的任何元素 (例如 `URIPath`、`QueryParam`、`Header`、`FormParam`、`XMLPayload` 或 `JSONPayload`) 中無效，則 API 代理程式的部署作業會失敗。如果 `Pattern` 元素未包含變數，則視為無效。如要進一步瞭解模式比對，請參閱「關於比對和變數建立」。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統就會設定這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

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

錯誤回應範例

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

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

錯誤規則範例

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

ExtractVariables 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

結果

影片

範例

URI

查詢參數

多個參數

標頭

JSON

XML

關於「ExtractVariables」政策

範圍

關於比對和變數建立

比對 URI 路徑、查詢參數、標頭、表單參數和變數

指定多個模式

指定含有多個變數的模式

比對模式中的多個例項

在模式中使用特殊字元

比對 JSON 和 XML

在多個位置寫入相同變數

控管未找到相符項目時的處理方式

元素參照

<ExtractVariables> 屬性

<DisplayName> 元素

<Source> 元素

屬性

<VariablePrefix> 元素

<IgnoreUnresolvedVariables> 元素

<URIPath> 元素

屬性

<QueryParam> 元素

屬性

<Header> 元素

屬性

<FormParam> 元素

屬性

<Variable> 元素

屬性

<JSONPayload> 元素

<JSONPayload>/<Variable> 元素

屬性

<JSONPayload>/<Variable>/<JSONPath> 元素

<XMLPayload> 元素

屬性

<XMLPayload>/<Namespaces> 元素

屬性

<XMLPayload>/<Variable> 元素

屬性

<XMLPayload>/<Variable>/<XPath> 元素

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

ExtractVariables 政策
透過集合功能整理內容你可以依據偏好儲存及分類內容。