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

ExtractVariables 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

結果

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

雖然您經常使用這項政策從要求或回應訊息擷取資訊，但也能從其他來源擷取資訊，包括 AccessEntity 政策、 XML 物件或 JSON 物件

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

影片

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

影片	說明
擷取變數從 XML 酬載中	使用擷取變數政策從 XML 酬載中擷取變數。
擷取變數從 JSON 酬載	使用擷取變數政策從 JSON 酬載中擷取變數。
擷取變數使用參數	從參數中擷取變數，例如查詢、標頭、表單或 URI 參數。
擷取變數利用多重值參數	從多重值參數中擷取變數。
擷取變數 from 查詢參數 (傳統版 Edge)	使用傳統版 Edge UI，從查詢參數中擷取變數。
擷取變數來自 XML 或 JSON 酬載 (傳統邊緣)	使用傳統版 Edge UI，從 XML 或 JSON 酬載中擷取變數。

範例

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

GitHub

這些連結指向了您可以在 Edge 上部署及執行的 API Proxy 範例。他們使用 ExtractVariables，而且位於 Apigee 的 api-platform-samples 存放區中 GitHub。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> 元素會告知擷取變數政策來擷取 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。

您現在可以存取變數 queryinfo.firstWeather 和 queryinfo.secondWeather 存取 Proxy 的 IP 位址。舉例來說，下列 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 Edge 將上方的 ExtractVariables 政策程式碼套用至這個標頭時，會將 clientrequest.oauthtoken 變數設為 TU08xptfFfeM7aS0xHqlxTgEAdAM。

您現在可以在clientrequest.oauthtoken Proxy 上。舉例來說，下列 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。

您現在可以在geocoderesponse.latitude Proxy 上。舉例來說，下列 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。

您現在可以在directionresponse.travelmode 存取 Proxy 的 IP 位址。舉例來說，下列 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 政策的好處而負責任的 AI 技術做法有助於達成這項目標

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

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

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

若要瞭解如何使用 ExtractVariables 製作內容導向 Analytics 報表，請參閱：分析使用自訂數據分析的 API 訊息內容。

範圍

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

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

，瞭解如何調查及移除這項存取權。

提示：如果沒看到新擷取的變數，追蹤工具，請嘗試移除您新增的 <VariablePrefix> 元素。詳情請參閱 Trace 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 的傳入要求網址的格式如下：

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>

針對傳入要求，重整改以 /basepath/v1 做為基礎路徑的 API Proxy 網址：

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>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 傳回呼叫政策，或從 XML 或 JSON 物件中擷取資訊。

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

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

預設：	訊息
所在地：	選用
類型：	字串

屬性

屬性	說明	預設	存在必要性	類型
clearPayload	如要清除 <Source>從中擷取資料後只有在來源郵件並非如此時，才使用`<clearPayload>`選項必須在執行 ExtractVariables 後完成這項作業。設為 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>元素

(選用，但請參閱下表的「所在地」列，瞭解詳細資訊)。擷取值來自 request 來源訊息的 Proxy.pathsuffix套用至格式為 proxy.pathsuffix，且不包含 API Proxy 的基本路徑。如果來源訊息會解析為 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 格式訊息。JSON 只有在訊息的 Content-Type 標頭為 application/json 時才會執行擷取。

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

預設：	不適用
所在地：	選用設定。不過，您必須至少提供下列其中一項： `<URIPath>`、`<QueryParam>`、`<Header>`、 `<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
類型：	不適用

<JSONPayload>/<Variable> 元素

(在 JSONPayload 元素中需要)。指定擷取值的變數。您可以在 <Variable> 元素中加入多個 <Variable> 標記並填入資料有多個變數

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

預設：	不適用
所在地：	JSONPayload 元素中的必要欄位。
類型：	不適用

屬性

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

說明

預設

存在必要性

類型

名稱

指定擷取值所屬的變數名稱。

名稱

必填

字串

類型

指定變數值的資料類型。

不適用

選用

字串。可用的選項如下：

字串
布林值
整數
long
float
雙精準數
nodeset (傳回 JSON 片段)

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

(在 JSONPayload:Variable 元素中為必要項目。)指定 JSON 路徑，用於擷取值。

<JSONPath> 元素支援呼叫的動態字串替換功能訊息範本。

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

預設：	不適用
所在地：	必填
類型：	字串

<XMLPayload>元素

(選用，但請參閱下表的「所在地」列，瞭解詳細資訊)。指定 XML 格式的訊息，系統會從該訊息中擷取變數值。XML 酬載只有在訊息的 Content-Type 標頭時才會擷取。是 text/xml、application/xml。或 application/*+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 float 雙精準數 nodeset (傳回 XML 片段)

說明

預設

存在必要性

類型

名稱

指定擷取值所屬的變數名稱。

名稱

必填

字串

類型

指定變數值的資料類型。

布林值

選用

字串。可用的選項如下：

字串
布林值
整數
long
float
雙精準數
nodeset (傳回 XML 片段)

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

(在 XMLPayload:Variable 元素中為必要項目。)指定針對變數。僅支援 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>

預設：	不適用
所在地：	必填
類型：	字串

注意：使用 parent、ancestor、following 和 Edge 不支援 XPath 運算式中的 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

寫入 設定變數

控管系統偵測不到相符結果時的處理方式

元素參照

&lt;ExtractVariables&gt;屬性

&lt;DisplayName&gt;元素

&lt;Source&gt;元素

屬性

&lt;VariablePrefix&gt;元素

&lt;IgnoreUnresolvedVariables&gt;元素

&lt;URIPath&gt;元素

屬性

&lt;QueryParam&gt;元素

屬性

&lt;Header&gt;元素

屬性

&lt;FormParam&gt;元素

屬性

&lt;Variable&gt;元素

屬性

&lt;JSONPayload&gt;元素

&lt;JSONPayload&gt;/&lt;Variable&gt; 元素

屬性

&lt;JSONPayload&gt;/&lt;Variable&gt;/&lt;JSONPath&gt;元素

&lt;XMLPayload&gt;元素

屬性

&lt;XMLPayload&gt;/&lt;Namespaces&gt; 元素

屬性

&lt;XMLPayload&gt;/&lt;Variable&gt; 元素

屬性

&lt;XMLPayload&gt;/&lt;Variable&gt;/&lt;XPath&gt;元素

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

結構定義

相關主題

寫入設定變數

<ExtractVariables>屬性

<DisplayName>元素

<Source>元素

<VariablePrefix>元素

<IgnoreUnresolvedVariables>元素

<URIPath>元素

<QueryParam>元素

<Header>元素

<FormParam>元素

<Variable>元素

<JSONPayload>元素

<JSONPayload>/<Variable> 元素

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

<XMLPayload>元素

<XMLPayload>/<Namespaces> 元素

<XMLPayload>/<Variable> 元素

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