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>

關於 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 (僅限回應，使用訊息記錄政策)
  • 錯誤流程
(追蹤記錄中未顯示 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 已淘汰

&lt;DisplayName&gt;元素

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

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，政策的 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 片段)

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

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

<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 片段)

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

(XMLPayload:Variable 元素中為必填屬性)。指定為變數定義的 XPath。系統僅支援 XPath 1.0 運算式。

<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>
預設值： 不適用
外觀狀態： 必填
類型： 字串

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.extractvariables.ExecutionFailed 500

This error occurs when:

  • The input payload (JSON, XML) is empty.
  • The input (JSON, XML, etc) passed to the policy is invalid or malformed.
steps.extractvariables.ImmutableVariable 500 A variable used in the policy is immutable. The policy was unable to set this variable.
steps.extractvariables.InvalidJSONPath 500 This error occurs if an invalid JSON path is used in the JSONPath element of the policy. For example, if a JSON payload does not have the object Name, but you specify Name as the path in the policy, then this error occurs.
steps.extractvariables.JsonPathParsingFailure 500 This error occurs when the policy is unable to parse a JSON path and extract data from the flow variable specified in Source element. Typically this happens if the flow variable specified in the Source element does not exist in the current flow.
steps.extractvariables.SetVariableFailed 500 This error occurs if the policy could not set the value to a variable. The error generally happens if you try to assign values to multiple variables whose names start with the same words in a nested dot-separated format.
steps.extractvariables.SourceMessageNotAvailable 500 This error occurs if the message variable specified in the Source element of the policy is either:
  • Out of scope (not available in the specific flow where the policy is being executed) or
  • Can't be resolved (is not defined)
steps.extractvariables.UnableToCast 500 This error occurs if the policy was unable to cast the extracted value to a variable. Typically this happens if you attempt to set the value of one data type to a variable of another data type.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
NothingToExtract If the policy does not have any of the elements URIPath, QueryParam, Header, FormParam, XMLPayload, or JSONPayload, the deployment of the API Proxy fails, because there's nothing to extract.
NONEmptyPrefixMappedToEmptyURI This error occurs if the policy has a prefix defined in the Namespace element under the XMLPayload element, but no URI is defined.
DuplicatePrefix This error occurs if the policy has the same prefix defined more than once in the Namespace element under the XMLPayload element.
NoXPathsToEvaluate If the policy does not have the XPath element within the XMLPayload element, then the deployment of the API proxy fails with this error.
EmptyXPathExpression If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
NoJSONPathsToEvaluate If the policy does not have the JSONPath element within the JSONPayload element, then the deployment of the API proxy fails with this error.
EmptyJSONPathExpression If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
MissingName If the policy does not have the name attribute in any of the policy elements like QueryParam, Header, FormParam or Variable, where it is required, then the deployment of the API proxy fails.
PatternWithoutVariable If the policy does not have a variable specified within the Pattern element, then the deployment of the API proxy fails. The Pattern element requires the name of the variable in which extracted data will be stored.
CannotBeConvertedToNodeset If the policy has an XPath expression where the Variable type is defined as nodeset, but the expression cannot be converted to nodeset, then the deployment of the API proxy fails.
JSONPathCompilationFailed The policy could not compile a specified JSON Path.
InstantiationFailed The policy could not be instantiated.
XPathCompilationFailed If the prefix or the value used in the XPath element is not part of any of the declared namespaces in the policy, then the deployment of the API proxy fails.
InvalidPattern If the Pattern element definition is invalid in any of the elements like URIPath, QueryParam, Header, FormParam, XMLPayload or JSONPayload within the policy, then the deployment of the API proxy fails.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. extractvariables.EV-ParseJsonResponse.failed = true

Example error response

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

Example fault rule

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

結構定義

相關主題

使用自訂分析功能分析 API 訊息內容

變數參考資料