您正在查看 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 的方式,以及如何部署和執行各個範例。
- 擷取及指派變數範例 (從 JSON 和 XML 訊息中擷取資料)
- 存取實體範例
- 分頁和快取範例
- 重新轉送目標網址範例
- 政策組合混搭範例
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.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 設計人員,假設您想在快取查詢中使用權杖值 (而非整個標頭) 做為索引鍵,您可以使用上方的「擷取變數」政策程式碼來擷取權杖。
當 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.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 將上方的「擷取變數」政策程式碼套用至這則 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>
關於「擷取變數」政策
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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<Source> 元素
(選用) 指定要剖析的變數。<Source>
的值預設為 message
。message
值須區分大小寫。在要求流程中,message
會解析為要求訊息。在回應流程中,message
會解析為回應訊息。
雖然您經常使用這項政策從要求或回應訊息中擷取資訊,但也能用來擷取任何變數中的資訊。舉例來說,您可以使用這個引數從 AccessEntity 政策建立的實體擷取資訊、從服務呼叫政策傳回的資料,或是從 XML 或 JSON 物件擷取資訊。
如果 <Source>
無法解析,或解析為非訊息類型,則政策將無法回應。
<Source clearPayload="true|false">request</Source>
預設: | 訊息 |
所在地: | 選用 |
類型: | 字串 |
屬性
屬性 | 說明 | 預設 | 存在必要性 | 類型 |
---|---|---|---|---|
clearPayload |
從資料表擷取資料後,如果您想清除 <Source> 中指定的酬載,請設為 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>
預設: | 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> 元素
(選用,但詳情請參閱下表的「所在地」列)。從指定 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 元素中的必要項目。 |
類型: | 不適用 |
屬性
屬性 | 說明 | 預設 | 存在必要性 | 類型 |
---|---|---|---|---|
名稱 |
指定擷取值的變數名稱。 |
名稱 |
需要 | 字串 |
類型 | 指定變數值的資料類型。 | 不適用 | 選用 |
字串。可用的選項如下:
|
<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 |
設為 |
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>
預設: | 不適用 |
所在地: | 選用 |
類型: | 不適用 |
屬性
屬性 | 說明 | 預設 | 存在必要性 | 類型 |
---|---|---|---|---|
名稱 |
指定擷取值的變數名稱。 |
名稱 |
需要 | 字串 |
類型 | 指定變數值的資料類型。 | 布林值 | 選用 |
字串。可用的選項如下:
|
<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 |
發生這個錯誤時,會發生以下錯誤:
|
build |
steps.extractvariables.ImmutableVariable |
500 | 政策中使用的變數不可變更。政策無法設定這個變數。 | |
steps.extractvariables.InvalidJSONPath |
500 | 如果政策的 JSONPath 元素中使用無效的 JSON 路徑,就會發生這個錯誤。舉例來說,如果 JSON 酬載沒有 Name 物件,但您在政策中將路徑指定為 Name ,就會發生這個錯誤。 |
build |
steps.extractvariables.JsonPathParsingFailure |
500 | 如果政策無法剖析 JSON 路徑,並從 Source 元素中指定的流程變數擷取資料,就會發生這個錯誤。通常,如果 Source 元素中指定的流程變數不存在於目前的流程中,就會發生這種情況。 |
build |
steps.extractvariables.SetVariableFailed |
500 | 如果政策無法將值設為變數,就會發生這個錯誤。 如果您嘗試將值指派給多個變數,而且變數的名稱開頭為以巢狀點分隔格式的字詞,通常就會發生這個錯誤。 | build |
steps.extractvariables.SourceMessageNotAvailable |
500 | 如果政策的 Source 元素中指定 message 變數,就會發生這個錯誤:
|
build |
steps.extractvariables.UnableToCast |
500 | 如果政策無法將擷取的值轉換為變數,就會發生這個錯誤。一般來說,如果您嘗試將某個資料類型的值設為另一種資料類型的變數,就會發生這類情況。 | build |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
NothingToExtract |
如果政策中沒有任何元素 URIPath 、QueryParam 、Header 、FormParam 、XMLPayload 或 JSONPayload ,API Proxy 的部署就會失敗,因為沒有可擷取的項目。 |
build |
NONEmptyPrefixMappedToEmptyURI |
如果政策的 Namespace 元素在 XMLPayload 元素下方已定義前置字串,但未定義 URI,就會發生這個錯誤。 |
build |
DuplicatePrefix |
如果政策在 XMLPayload 元素的 Namespace 元素中多次定義相同前置字串,就會發生這個錯誤。 |
build |
NoXPathsToEvaluate |
如果政策的 XMLPayload 元素中沒有 XPath 元素,API Proxy 部署作業就會失敗,並發生這個錯誤。
|
build |
EmptyXPathExpression |
如果政策的 XMLPayload 元素中包含空白的 XPath 運算式,API Proxy 的部署就會失敗。 |
build |
NoJSONPathsToEvaluate |
如果政策在 JSONPayload 元素中沒有 JSONPath 元素,API Proxy 部署就會失敗,並發生這項錯誤。 |
build |
EmptyJSONPathExpression |
如果政策的 XMLPayload 元素中含有空白的 XPath 運算式,API Proxy 的部署就會失敗。 |
build |
MissingName |
如果在必要情況下,政策的任何政策元素 (例如 QueryParam 、Header 、FormParam 或 Variable ) 中沒有 name 屬性,API Proxy 的部署作業就會失敗。 |
build |
PatternWithoutVariable |
如果政策未在 Pattern 元素中指定變數,API Proxy 的部署作業就會失敗。Pattern 元素需要指定要儲存擷取資料的變數名稱。 |
build |
CannotBeConvertedToNodeset |
如果政策中有 XPath 運算式,其中 Variable 類型定義為 nodeset,但運算式無法轉換為 nodeset,API Proxy 部署就會失敗。 |
build |
JSONPathCompilationFailed |
政策無法編譯指定的 JSON 路徑。 | |
InstantiationFailed |
無法執行個體化政策。 | |
XPathCompilationFailed |
如果 XPath 元素中使用的前置字串或值不屬於政策中任何宣告的命名空間,那麼 API Proxy 部署作業就會失敗。 |
build |
InvalidPattern |
如果政策內任何元素 (例如 URIPath 、QueryParam 、Header 、FormParam 、XMLPayload 或 JSONPayload ) 中的 Pattern 元素定義無效,API Proxy 的部署作業就會失敗。
|
build |
錯誤變數
當這項政策在執行階段觸發錯誤時,系統會設定這些變數。詳情請參閱「政策錯誤須知」。
錯誤回應範例
{ "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>