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

ExtractVariables 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

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

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

影片

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

影片	說明
從 XML 酬載擷取變數	使用「擷取變數」政策，從 XML 酬載擷取變數。
從 JSON 酬載擷取變數	使用「擷取變數」政策，從 JSON 酬載擷取變數。
從參數中擷取變數	從參數 (例如查詢、標頭、表單或 URI 參數) 擷取變數。
從多重值參數擷取變數	從多值參數中擷取變數。
從查詢參數中擷取變數 (傳統 Edge)	使用傳統版 Edge 使用者介面，從查詢參數中擷取變數。
從 XML 或 JSON 酬載中擷取變數 (傳統 Edge)	使用 Classic Edge UI 從 XML 或 JSON 酬載中擷取變數。

範例

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

GitHub

這些連結會指向可正常運作的 API Proxy 範例，您可以在 Edge 上部署及執行這些範例。這些範例使用 ExtractVariables，位於 GitHub 上的 Apigee api-platform-samples 存放區。README 說明在各種情況下如何使用 ExtractVariables，以及如何部署及執行每個範例。

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://org1-test.apigee.net/svc1/accounts/12797282

假設 API Proxy 的基本路徑為 /svc1。當 Apigee Edge 將上述 ExtractVariables 政策程式碼套用至這項傳入要求時，會將 urirequest.id 變數設為 12797282。Apigee Edge 執行政策後，處理流程中的後續政策或程式碼可以參照名為 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://org1-test.apigee.net/accounts/12797282?code=DBN88271

當 Apigee Edge 將上述 ExtractVariables 政策程式碼套用至這項傳入要求時，會將變數 queryinfo.dbncode 設為 88271。Apigee Edge 執行政策後，處理流程中的後續政策或程式碼可以參照名為 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 設計允許您指定多個同名的查詢參數。您可以使用這項政策，擷取查詢參數「w」多個執行個體的值。如要在 ExtractVariables 政策中參照這些查詢參數，請使用索引。查詢參數的第一個例項沒有索引，第二個例項的索引為 2，第三個例項的索引為 3，依此類推。

假設上述範例政策程式碼適用於下列傳入要求：

GET http://org1-test.apigee.net/weather?w=Boston&w=Chicago

當 Apigee Edge 將上述 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 v2.0 不記名憑證。請考慮上述範例政策程式碼，搭配使用含有這類標頭的 OAuth v2.0 權杖要求：Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

假設您是 API 設計人員，想要使用權杖值 (但不是整個標頭) 做為快取查詢中的金鑰。您可以使用上述 ExtractVariables 政策程式碼擷取代碼。

當 Apigee Edge 將上述 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>

<JSONPayload>$

請參考下列 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 Edge 將上述 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>

<XMLPayload>

請參考下列 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 Edge 將上述 ExtractVariables 政策程式碼套用至這個 XML 訊息時，會設定三個變數：directionsresponse.travelmode,、directionsresponse.duration 和 directionsresponse.timeunit。所有變數都使用相同的變數前置字元 directionsresponse。這些變數的後置字元是由 <Variable> 元素的 name 屬性明確指定。

變數 directionsresponse.travelmode 會取得 DRIVING 值。變數 directionsresponse.duration 會取得 19 值。變數 directionsresponse.timeunit 會取得 minutes 值。

您現在可以在 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，根據訊息內容 (包括標頭、URI 路徑、酬載和查詢參數) 採取不同行為。通常，Proxy 會擷取這類內容的某個部分，用於條件陳述式。請使用 ExtractVariables 政策執行這項操作。

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

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

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

如要瞭解如何使用 ExtractVariables 建構以內容為準的 Analytics 報表，請參閱「使用自訂分析功能分析 API 訊息內容」。

範圍

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

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

提示：如果新擷取的變數未顯示在「追蹤」工具中，請嘗試移除您新增的 <VariablePrefix> 元素。詳情請參閱「 ExtractVariables not shown in trace Apigee Community topic」

(追蹤記錄中未顯示 ExtractVariables Apigee 社群主題)。

關於比對和變數建立

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 變數會設為「/a/」後方 proxy.pathsuffix 中顯示的任何內容。舉例來說，假設 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/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

如要在 ExtractVariables 政策中參照這些查詢參數，請使用索引。查詢參數的第一個例項沒有索引，第二個例項的索引為 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>Extract Variables 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>` 元素，為政策加上標籤：管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。	不適用	必填
`continueOnError`	如果設為「`false`」，系統會在政策失敗時傳回錯誤。這是可預期的情況大多數政策的行為如果設為 `true`，即使政策已發生，流程執行作業仍會繼續執行失敗。	false	選用
`enabled`	如要強制執行政策，請設為 `true`。設為 `false` 即可停用政策。這項政策不會仍會強制執行政策。	true	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName>元素

除 name 屬性外，一併使用管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>

預設

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

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性選用

類型字串

<Source> 元素

(選用) 指定要剖析的變數。<Source> 的值預設為 message。message 值會因情境而異。在要求流程中，message 會解析為要求訊息。在回覆流程中，message 會解析為回覆訊息。

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

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

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

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

屬性

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

<VariablePrefix> 元素

(選用) 完整變數名稱是由 <VariablePrefix>、半形句號，以及您在 <Pattern> 元素或 <Variable> 元素中以大括號定義的名稱所組成。例如：myprefix.id、myprefix.dbncode 或 myprefix.oauthtoken.。

<VariablePrefix>myprefix</VariablePrefix>

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

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

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

<IgnoreUnresolvedVariables> 元素

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

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

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

如果 <XMLPayload> 中有未解析的 XPath 參照，政策會擲回下列錯誤：

{
   "fault":{
      "faultstring":"Unresolved xpath path in policy policy_name.",
      "detail":{
         "errorcode":"steps.extractvariables.InvalidXPath"
      }
   }
}

<URIPath> 元素

(選用，但詳情請參閱下表中的「狀態」列。)從要求來源訊息的 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> 元素

(選用，但詳情請參閱下表中的「狀態」列。)從要求來源訊息的指定查詢參數中擷取值。如果來源訊息解析為「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> 元素

(選用，但詳情請參閱下表中的「狀態」列。)從指定要求或回應訊息的指定 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> 元素

(選用，但詳情請參閱下表中的「狀態」列。)從指定要求或回應訊息的指定表單參數中擷取值。只有在指定郵件的 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 float 雙精準數節點集 (傳回 JSON 片段)

說明

預設

存在必要性

類型

名稱

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

名稱

必填

字串

類型

指定變數值的資料類型。

不適用

選用

字串。可用的選項如下：

字串
布林值
整數
long
float
雙精準數
節點集 (傳回 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> element

(選用) 指定要在 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 float 雙精準數節點集 (傳回 XML 片段)

說明

預設

存在必要性

類型

名稱

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

名稱

必填

字串

類型

指定變數值的資料類型。

布林值

選用

字串。可用的選項如下：

字串
布林值
整數
long
float
雙精準數
節點集 (傳回 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>

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

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

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

錯誤參考資料

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

執行階段錯誤

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

錯誤程式碼	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	如果系統傳回這個錯誤，表示 message 政策的 `Source` 元素中指定的變數為以下任一項：範圍外 (不適用於執行政策的特定流程) 無法解析 (未定義)
`steps.extractvariables.UnableToCast`	500	如果政策無法將解壓縮的影片投放，就會發生這個錯誤變數的值這通常是因為您嘗試將傳遞至另一種資料類型的變數。

部署錯誤

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

錯誤名稱	原因	修正
`NothingToExtract`	如果政策沒有任何元素 `URIPath`、`QueryParam`、 `Header`、`FormParam`、`XMLPayload` 或 `JSONPayload`， API Proxy 部署作業失敗，因為沒有可擷取的內容。
`NONEmptyPrefixMappedToEmptyURI`	如果政策的前置字串定義為 `XMLPayload` 元素下的 `Namespace` 元素，但沒有 URI
`DuplicatePrefix`	如果政策定義的前置字串數量超過在 `XMLPayload` 元素下方的 `Namespace` 元素中。
`NoXPathsToEvaluate`	如果政策沒有 `XPath` 元素 `XMLPayload` 元素，那麼 API Proxy 部署作業就會失敗，並發生這個錯誤。如果您想從 XML 酬載中擷取變數，則必須指定 `XPath` 子元素。
`EmptyXPathExpression`	如果政策的 `XMLPayload` 內有空白的 `XPath` 運算式元素，API Proxy 的部署作業就會失敗。
`NoJSONPathsToEvaluate`	如果政策沒有 `JSONPath` 元素 `JSONPayload` 元素，那麼 API Proxy 部署作業就會失敗，並發生這個錯誤。
`EmptyJSONPathExpression`	如果政策的 `XPath` 運算式包含空白的 `XMLPayload` 元素，那麼 API Proxy 部署作業就會失敗。
`MissingName`	這項政策的任何政策中沒有 `name` 屬性元素，例如 `QueryParam`、`Header`、`FormParam` 或 `Variable`，否則 API Proxy 部署作業便會失敗。
`PatternWithoutVariable`	如果政策未在 `Pattern` 元素內指定的變數，那麼 API Proxy 的部署作業就會失敗`Pattern` 元素需要名稱為要儲存擷取資料的目標變數。
`CannotBeConvertedToNodeset`	如果政策含有 `XPath` 運算式，其中 `Variable` 類型為是定義為 nodeset 但運算式無法轉換為 nodeset，則 API Proxy 的部署會失敗。
`JSONPathCompilationFailed`	政策無法編譯指定的 JSON 路徑。
`InstantiationFailed`	無法將政策執行個體化。
`XPathCompilationFailed`	如果 `XPath` 元素中使用的前置字元或值不屬於政策中宣告的命名空間，接著是失敗。
`InvalidPattern`	如有任何元素 (例如 `URIPath`) 中的 `Pattern` 元素定義無效， `QueryParam`、`Header`、`FormParam`、`XMLPayload` 或是政策中的 `JSONPayload`，而將 Deployment API Proxy 故障。如果 `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 政策

結果

影片

範例

GitHub

URI

查詢參數

多個參數

標頭

JSON

XML

關於 ExtractVariables 政策

範圍

關於比對和變數建立

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

指定多個模式

使用多個變數指定模式

比對模式中的多個執行個體

在模式中使用特殊字元

比對 JSON 和 XML

在多個位置寫入相同變數

控制沒有相符項目時的處理方式

元素參考資料

<ExtractVariables> 屬性

&lt;DisplayName&gt;元素

<Source> 元素

屬性

<VariablePrefix> 元素

<IgnoreUnresolvedVariables> 元素

<URIPath> 元素

屬性

<QueryParam> 元素

屬性

<Header> 元素

屬性

<FormParam> 元素

屬性

<Variable> 元素

屬性

<JSONPayload> 元素

<JSONPayload>/<Variable> 元素

屬性

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

<XMLPayload> 元素

屬性

<XMLPayload>/<Namespaces> element

屬性

<XMLPayload>/<Variable> 元素

屬性

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

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

<DisplayName>元素