本頁面由 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 設計允許您指定多個同名的查詢參數。您可以使用 ExtractVariables 政策，擷取查詢參數多個執行個體的值。如要在政策中參照同名的查詢參數，請使用索引。查詢參數的第一個例項沒有索引，第二個例項的索引為 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 v2.0 不記名憑證。請考慮上述範例政策程式碼，搭配使用含有類似下列標頭的 OAuth v2.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，根據訊息內容 (包括標頭、URI 路徑、酬載和查詢參數) 採取不同行為。通常，Proxy 會擷取這類內容的部分資訊，用於條件陳述式。請使用 ExtractVariables 政策執行這項操作。

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

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

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

範圍

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

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

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

關於比對和變數建立

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 為 /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 路徑中位於基本路徑後方的部分) 的要求，例如「/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> 元素

(選用) 完整變數名稱的建立方式，是將 <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>

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

<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 浮點數雙精度值節點集 (傳回 JSON 片段)

說明

預設

存在必要性

類型

名稱

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

名稱

必填

字串

類型

指定變數值的資料類型。

不適用

選用

字串。可用的選項如下：

字串
布林值
整數
long
浮點數
雙精度值
節點集 (傳回 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 浮點數雙精度值節點集 (傳回 XML 片段)

說明

預設

存在必要性

類型

名稱

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

名稱

必填

字串

類型

指定變數值的資料類型。

布林值

選用

字串。可用的選項如下：

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

屬性

<XMLPayload>/<Variable> 元素

屬性

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

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

ExtractVariables 政策