ExtractVariables 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

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

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

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

影片

請觀看以下影片,進一步瞭解「擷取變數」政策。

影片 說明
從 XML 酬載擷取變數 使用「擷取變數」政策從 XML 酬載中擷取變數。
從 JSON 酬載擷取變數 使用「擷取變數」政策從 JSON 酬載中擷取變數。
從參數擷取變數 從參數中擷取變數,例如查詢、標頭、表單或 URI 參數。
從多重值參數擷取變數 從多重值參數擷取變數。
從查詢參數 (傳統版 Edge) 中擷取變數 使用傳統版 Edge UI 擷取查詢參數中的變數。
從 XML 或 JSON 酬載 (Classic 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 將上方的「擷取變數」政策程式碼套用至這個傳入要求時,會將變數 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 將上方的「擷取變數」政策程式碼套用至這個傳入要求時,會將變數 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 將上方的「擷取變數」政策程式碼套用至這個傳入要求時,會將變數 queryinfo.firstWeather 設為 Boston,並將變數 queryInfo.secondWeather 設為 Chicago

您現在可以在 Proxy 中存取 queryinfo.firstWeatherqueryinfo.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 設計人員,假設您想在快取查詢中使用權杖值 (而非整個標頭) 做為索引鍵,您可以使用上方的「擷取變數」政策程式碼來擷取權杖。

當 Apigee Edge 將上方的「擷取變數」政策程式碼套用至這個標頭時,系統會將變數 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 將上方的「擷取變數」政策程式碼套用至此 JSON 訊息時,會設定兩個變數:geocoderesponse.latitudegeocoderesponse.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 將上方的「擷取變數」政策程式碼套用至這則 XML 訊息時,會設定三個變數:directionsresponse.travelmode, directionsresponse.durationdirectionsresponse.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>

關於「擷取變數」政策

API 開發人員建構的 API Proxy 會根據訊息內容 (包括標頭、URI 路徑、酬載和查詢參數) 而有不同的行為。Proxy 通常會擷取此內容的部分內容,以便在條件陳述式中使用。使用「擷取變數」政策即可。

定義「擷取變數」政策時,您可以選擇:

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

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

如要瞭解如何使用「擷取變數」建構內容導向 Analytics (分析) 報表,請參閱「使用自訂數據分析分析 API 訊息內容」一文。

範圍

使用 ExtractVariables 政策設定的變數具有 global 範圍。也就是說,在「ExtractVariables」政策定義新變數後,您可以從任何流程階段 (即執行「擷取變數」政策「之後」) 的任何政策或程式碼存取該變數。其中包括:

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

關於比對和建立變數

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

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

相符的 URI 路徑、查詢參數、標頭、表單參數和變數

從 URI 路徑、查詢參數、標頭、表單參數和變數中擷取資訊時,請使用 <Pattern> 標記指定一或多個要比對的模式。例如,下列政策範例顯示 URI 路徑的單一比對模式:

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

在這個範例中,urirequest.pathSeg 變數會設為 Proxy.pathsuffix 後方「/a/」後方的內容。舉例來說,假設您的 API Proxy 基本路徑為 /basepath/v1。透過傳送至 http://myCo.com/basepath/v1/a/b 的傳入要求時,變數會設為「b」。

指定多個模式

您可以指定多個對應於 <Pattern> 標記,其中:

  • 系統會測試所有模式是否相符。
  • 如果沒有相符的模式,政策就不會有任何項目,也不會建立變數。
  • 如果同時符合多個模式,系統會使用具有最長路徑片段的模式進行擷取。
  • 如果兩個相符的模式具有最長的路徑片段,則系統會使用政策中第一個指定的模式進行擷取。

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

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

假設某個 API Proxy 的基本路徑為 /basepath/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>

針對傳入要求網址,再次使用基本路徑為 /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/a/c」和「/a/b/a/c」)。

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

*;charset={encoding}

此模式與「text/xml;charset=UTF-16」和「application/xml;charset=ASCII」值相符。

如果傳遞至「ExtractVariables」政策的值含有「{」等特殊字元,請使用「%」字元進行逸出。以下範例會逸出模式中的「{" and "}」字元,因為它們會做為查詢參數值中的常值字元:

<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 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> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

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

不適用

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

存在必要性 選用
類型 字串

<Source> 元素

(選用) 指定要剖析的變數。<Source> 的值預設為 messagemessage 值須區分大小寫。在要求流程中,message 會解析為要求訊息。在回應流程中,message 會解析為回應訊息。

雖然您經常使用這項政策從要求或回應訊息中擷取資訊,但也能用來擷取任何變數中的資訊。舉例來說,您可以使用這個引數從 AccessEntity 政策建立的實體擷取資訊、從服務呼叫政策傳回的資料,或是從 XML 或 JSON 物件擷取資訊。

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

<Source clearPayload="true|false">request</Source>
預設: 訊息
所在地: 選用
類型: 字串

屬性

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

從資料表擷取資料後,如果您想清除 <Source> 中指定的酬載,請設為 true

只有在執行「ExtractVariables」後不需要來源訊息時,才使用 <clearPayload> 選項。設為 true 則會釋出訊息使用的記憶體。

false

選用 布林值

<VariablePrefix> 元素

(選用) 將 <VariablePrefix>、點和您在 <Pattern> 元素或 <Variable> 元素中定義的 {大括號} 定義名稱,即可建立完整的變數名稱。例如 myprefix.idmyprefix.dbncodemyprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

舉例來說,假設名稱的值是「user」。

  • 如未指定 <VariablePrefix>,系統會將擷取的值指派給名為 user 的變數。
  • 如果將 <VariablePrefix> 指定為 myprefix,擷取的值會指派給名為 myprefix.user 的變數。
預設: 不適用
所在地: 選用
類型: 字串

<IgnoreUnresolvedVariables> 元素

(選用) 設為 true,將所有無法解析的變數視為空字串 (空值)。如要讓政策在參照的變數無法解析時擲回錯誤,請設為 false

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
預設: false
所在地: 選用
類型: 布林值

如果 <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> 元素

(選用,但詳情請參閱下表的「所在地」列)。從指定 requestresponse 訊息的指定 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> 元素

(選用,但詳情請參閱下表的「所在地」列)。從指定 requestresponse 訊息的指定表單參數中擷取值。只有在指定訊息的 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 元素中的必要項目。
類型: 不適用

屬性

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

指定擷取值的變數名稱。

名稱

需要 字串
類型 指定變數值的資料類型。 不適用 選用

字串。可用的選項如下:

  • 字串
  • boolean
  • 整數
  • long
  • float
  • double
  • nodeset (傳回 JSON 片段)

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

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

<Variable name="name">
   <JSONPath>$.rss.channel.title</JSONPath>
</Variable>
預設: 不適用
所在地: 需要
類型: 字串

<XMLPayload> 元素

(選用,但詳情請參閱下表的「所在地」列)。指定 XML 格式訊息,用於擷取變數值。只有在訊息的 Content-Type 標頭為 text/xmlapplication/xmlapplication/*+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>/<命名空間> 元素

(選用) 指定要在 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>
預設: 不適用
所在地: 選用
類型: 不適用

屬性

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

指定擷取值的變數名稱。

名稱

需要 字串
類型 指定變數值的資料類型。 布林值 選用

字串。可用的選項如下:

  • 字串
  • boolean
  • 整數
  • long
  • float
  • double
  • nodeset (傳回 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>
預設: 不適用
所在地: 需要
類型: 字串

錯誤參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 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 如果政策的 Source 元素中指定 message 變數,就會發生這個錯誤:
  • 超出範圍 (不適用於執行政策的特定流程) 或
  • 無法解析 (未定義)
steps.extractvariables.UnableToCast 500 如果政策無法將擷取的值轉換為變數,就會發生這個錯誤。一般來說,如果您嘗試將某個資料類型的值設為另一種資料類型的變數,就會發生這類情況。

部署錯誤

若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。

錯誤名稱 原因 修正
NothingToExtract 如果政策中沒有任何元素 URIPathQueryParamHeaderFormParamXMLPayloadJSONPayload,API Proxy 的部署就會失敗,因為沒有可擷取的項目。
NONEmptyPrefixMappedToEmptyURI 如果政策的 Namespace 元素在 XMLPayload 元素下方已定義前置字串,但未定義 URI,就會發生這個錯誤。
DuplicatePrefix 如果政策在 XMLPayload 元素的 Namespace 元素中多次定義相同前置字串,就會發生這個錯誤。
NoXPathsToEvaluate 如果政策的 XMLPayload 元素中沒有 XPath 元素,API Proxy 部署作業就會失敗,並發生這個錯誤。
EmptyXPathExpression 如果政策的 XMLPayload 元素中包含空白的 XPath 運算式,API Proxy 的部署就會失敗。
NoJSONPathsToEvaluate 如果政策在 JSONPayload 元素中沒有 JSONPath 元素,API Proxy 部署就會失敗,並發生這項錯誤。
EmptyJSONPathExpression 如果政策的 XMLPayload 元素中含有空白的 XPath 運算式,API Proxy 的部署就會失敗。
MissingName 如果在必要情況下,政策的任何政策元素 (例如 QueryParamHeaderFormParamVariable) 中沒有 name 屬性,API Proxy 的部署作業就會失敗。
PatternWithoutVariable 如果政策未在 Pattern 元素中指定變數,API Proxy 的部署作業就會失敗。Pattern 元素需要指定要儲存擷取資料的變數名稱。
CannotBeConvertedToNodeset 如果政策中有 XPath 運算式,其中 Variable 類型定義為 nodeset,但運算式無法轉換為 nodeset,API Proxy 部署就會失敗。
JSONPathCompilationFailed 政策無法編譯指定的 JSON 路徑。
InstantiationFailed 無法執行個體化政策。
XPathCompilationFailed 如果 XPath 元素中使用的前置字串或值不屬於政策中任何宣告的命名空間,那麼 API Proxy 部署作業就會失敗。
InvalidPattern 如果政策內任何元素 (例如 URIPathQueryParamHeaderFormParamXMLPayloadJSONPayload) 中的 Pattern 元素定義無效,API Proxy 的部署作業就會失敗。

錯誤變數

當這項政策在執行階段觸發錯誤時,系統會設定這些變數。詳情請參閱「政策錯誤須知」。

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

錯誤回應範例

{
   "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>

結構定義

相關主題

使用自訂數據分析分析 API 訊息內容

變數參考資料