您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
内容
ExtractVariables 政策从请求或响应中提取内容,并将变量的值设置为该内容。您可以提取消息的任何部分,包括标头、URI 路径、JSON/XML 载荷、表单参数和查询参数。政策的工作原理是对消息内容应用文本模式,在找到匹配项时,使用指定的消息内容设置变量。
虽然您通常会使用此政策从请求或响应消息中提取信息,但您也可以使用它从其他来源提取信息,包括 AccessEntity 政策创建的实体、XML 对象或 JSON 对象。
提取指定的消息内容后,您可以在处理请求和响应时在其他政策中引用该变量。
视频
观看以下视频,详细了解 ExtractVariables 政策。
视频 | 说明 |
---|---|
从 XML 载荷中提取变量 | 使用提取变量政策从 XML 载荷中提取变量。 |
从 JSON 载荷中提取变量 | 使用提取变量政策从 JSON 载荷中提取变量。 |
从参数中提取变量 | 从参数(例如查询、标头、表单或 URI 参数)中提取变量。 |
从多值参数中提取变量 | 从多值参数中提取变量。 |
从查询参数中提取变量(传统版 Edge) | 使用传统版 Edge 界面从查询参数中提取变量。 |
从 XML 或 JSON 载荷中提取变量(传统 Edge) | 使用传统版 Edge 界面从 XML 或 JSON 载荷中提取变量。 |
示例
这些政策代码示例说明了如何从以下类型的工件中提取变量:
GitHub
这些链接指向可在 Edge 上部署和运行的有效 API 代理示例。它们使用 ExtractVariable,并位于 GitHub 上的 Apigee 的 api-platform-samples 代码库中。README 文件说明了每种情况下如何使用 ExtractVariable,以及如何部署和运行每个示例。
- 提取和分配变量示例(从 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 代理的基本路径为 /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
。
您现在可以在代理中访问变量 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。例如,以下 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
。
您现在可以在代理中访问变量 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
。
您现在可以在代理中访问变量 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
。
您现在可以在代理中访问变量 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 代理,以根据消息的内容(包括标头、URI 路径、载荷和查询参数)实现不同行为。通常,代理会提取部分内容以在条件语句中使用。为此,请使用 ExtractVariables 政策。
在定义 ExtractVariables 政策时,您可以选择:
- 要设置的变量的名称
- 变量的来源
- 要提取和设置的变量数量
执行时,政策会对内容应用文本模式,并在发现匹配项时将指定变量的值设置为内容。然后,其他政策和代码可以使用这些变量来实现动态行为或将业务数据发送到 Edge API Analytics。
如需了解如何使用 ExtractVariables 构建内容驱动的 Analytics 报告,请参阅使用自定义分析工具分析 API 消息内容。
范围
使用 ExtractVariables 政策设置的变量具有“全局”范围。也就是说,在 ExtractVariables 政策定义新变量后,您可以从流(在 ExtractVariables 政策之后执行)的任何阶段的任何政策或代码访问该变量。包括:
- PreFlow:ProxyEndpoint 和 TargetEndpoint(请求和响应)
- PostFlow:ProxyEndpoint 和 TargetEndpoint(请求和响应)
- PostClientFlow:ProxyEndpoint(仅响应,使用消息日志记录政策)
- 错误流
匹配和变量创建简介
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 变量设置为 proxy.pathsuffix 中“/a/”后面的的所有内容。例如,假设您的 API 代理的基本路径为 /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 代理的基本路径为 /basepath/v1,则发送到 API 代理的入站请求网址格式如下:
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 代理的基本路径为 /basepath/v1,则对于入站请求网址:
http://myCo.com/basepath/v1/a/b/c/d
urirequest.pathSeg1 变量设置为“b”,urirequest.pathSeg2 变量设置为“d”。
匹配模式中的多个实例
如果某个项有多个同名的实例,您也可以匹配模式。例如,您可以发出包含多个同名的查询参数或标头的请求。以下请求包含两个名为“w”的查询参数:
http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2
如需在 ExtractVariables 政策中引用这些查询参数,请使用索引,其中查询参数的第一个实例没有索引,第二个位于索引 2,第三个索引位于索引 3,以此类推。例如,以下政策提取请求中名为“w”的第二个查询参数的值:
<ExtractVariables name="ExtractVariables-1"> <Source>request</Source> <QueryParam name="w.2"> <Pattern ignoreCase="true">{secondW}</Pattern> </QueryParam> <VariablePrefix>urirequest</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
urirequest.secondW 变量设置为“2”。如果请求中省略了第二个查询参数,则 urirequest.secondW 变量为空。只要请求中有多个名称相同的项,就请使用索引。
在模式中使用特殊字符
匹配 URI 路径时,您可以在模式中使用“*”和“**”通配符,其中:
- “*”匹配路径的任意一个段
- “**”匹配路径的多个段
例如,您可以指定 <URIPath> 元素的模式,如下所示:
<URIPath> <Pattern ignoreCase="true">/a/*/{id}</Pattern> <Pattern ignoreCase="true">/a/**/{id}</Pattern> </URIPath>
第一个模式与路径后缀(基本路径后面的 URI 路径部分)为“/a/b/c”、“/a/foo/bar”等的请求匹配。第二个模式与“/a/”后面任意数量的路径段匹配,例如“/a/foo/bar/baz/c”以及“/a/b/c”和“/a/foo/bar”。
指定查询参数、标头和表单参数的模式时,“*”字符指定为匹配任意数量的字符。例如,匹配标头时,将模式指定为:
*;charset={encoding}
此模式匹配值“text/xml;charset=UTF-16”和“application/xml;charset=ASCII”。
如果传递给 ExtractVariables 政策的值包含特殊字符(例如“{”),请使用“%”字符进行转义。以下示例对模式中的“{”和“}”字符进行转义,因为它们在查询参数的值中用作字面量字符:
<QueryParam> <Pattern ignoreCase="true">%{user%} {name}</Pattern> </QueryParam>
在此示例中,模式与值“{user} Steve”匹配,但与值“user Steve”不匹配。
匹配 JSON 和 XML
从 JSON 和 XML 中提取数据时,您可以在政策中指定一个或多个 <Variable> 标记。<Variable> 标记指定存储提取信息的目标变量的名称,以及指向提取信息的 JsonPath (JSON) 或 XPATH (XML)。
系统会对政策中的所有 <Variable> 标记进行计算,以便您可以通过单个政策中填充多个变量。如果 <Variable> 标记的计算结果不是 JSON 或 XML 中的有效字段,则不会创建相应的变量。
以下示例展示了从响应的 JSON 正文填充两个变量的 ExtractVariables 政策:
<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,从而将政策配置为将任何无法解析的变量视为空字符串 (null):
<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 |
政策的内部名称。 (可选)使用 |
不适用 | 必需 |
continueOnError |
设置为 设置为 |
false | 可选 |
enabled |
设置为 设为 |
true | 可选 |
async |
此特性已弃用。 |
false | 已弃用 |
<DisplayName> 元素
除了用于 name
属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
<DisplayName>Policy Display Name</DisplayName>
默认 |
不适用 如果省略此元素,则会使用政策的 |
---|---|
状态 | 可选 |
类型 | 字符串 |
<Source> 元素
(可选)指定要解析的变量。<Source>
的值默认为 message
。message
值取与上下文相关。在请求流中,message
解析为请求消息。在响应流中,message
解析为响应消息。
虽然此政策通常用于从请求或响应消息中提取信息,但您也可以用它来从任何变量中提取信息。例如,您可以使用它从 AccessEntity 政策创建的实体、服务调用程序政策返回的数据中提取信息,或者从 XML 或 JSON 对象中提取信息。
如果 <Source>
无法解析或解析为非消息类型,则该政策将无法响应。
<Source clearPayload="true|false">request</Source>
默认: | 消息 |
状态: | 可选 |
类型: | 字符串 |
属性
特性 | 说明 | 默认 | 状态 | 类型 |
---|---|---|---|---|
clearPayload |
如果要在从 <Source> 中提取数据后清除 <Source> 中指定的载荷,请设置为 true。 |
false |
可选 | 布尔值 |
<VariablePrefix> 元素
(可选)完整的变量名称是通过连接 <VariablePrefix>
、一个点以及您在 <Pattern>
元素的 {大括号} 中或 <Variable> 元素中定义的名称来创建的。例如 myprefix.id
、myprefix.dbncode
或 myprefix.oauthtoken.
。
<VariablePrefix>myprefix</VariablePrefix>
例如,假设 name 的值为“user”。
- 如果未指定
<VariablePrefix>
,则提取的值将分配给名为user
的变量。 - 如果
<VariablePrefix>
指定为 myprefix,则提取的值将分配给名为myprefix.user
的变量。
默认: | 不适用 |
状态: | 可选 |
类型: | 字符串 |
<IgnoreUnresolvedVariables> 元素
(可选)设置为 true
可将任何无法解析的变量视为空字符串 (null)。如果您希望政策在任何引用的变量无法解析时抛出错误,请设置为 false
。
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
默认: | False |
状态: | 可选 |
类型: | 布尔值 |
如果 XPath 引用在 <XMLPayload>
中未解析,此政策会抛出以下错误:
{ "fault":{ "faultstring":"Unresolved xpath path in policy policy_name.", "detail":{ "errorcode":"steps.extractvariables.InvalidXPath" } } }
<URIPath> 元素
(可选,请参阅下表中的“状态”行以了解详情。)从 request 源消息的 proxy.pathsuffix 中提取值。应用于该模式的路径为 proxy.pathsuffix,不包括 API 代理的基本路径。如果源消息解析为 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>. |
类型: | 不适用 |
属性
特性 | 说明 | 默认 | 状态 | 类型 |
---|---|---|---|---|
name | 指定查询参数的名称。如果多个查询参数具有相同的名称,请使用索引引用,其中查询参数的第一个实例没有索引,第二个索引位于索引 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>. |
类型: | 不适用 |
属性
特性 | 说明 | 默认 | 状态 | 类型 |
---|---|---|---|---|
name | 指定从中提取值的标头的名称。如果多个标头具有相同的名称,请使用索引引用,其中标头的第一个实例没有索引,第二个索引位于索引 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 元素内是必需的。 |
类型: | 不适用 |
属性
特性 | 说明 | 默认 | 状态 | 类型 |
---|---|---|---|---|
name |
指定提取值将要分配到的目标变量的名称。 |
name |
必需 | 字符串 |
类型 | 指定变量值的数据类型。 | 不适用 | 可选 |
字符串。从列表中选择:
|
<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>/<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>
默认: | 不适用 |
状态: | 可选 |
类型: | 不适用 |
属性
特性 | 说明 | 默认 | 状态 | 类型 |
---|---|---|---|---|
name |
指定提取值将要分配到的目标变量的名称。 |
name |
必需 | 字符串 |
类型 | 指定变量值的数据类型。 | 布尔值 | 可选 |
字符串。从列表中选择:
|
<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:
|
build |
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. |
build |
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. |
build |
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. | build |
steps.extractvariables.SourceMessageNotAvailable |
500 | This error occurs if the message
variable specified in the Source element of the policy
is either:
|
build |
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. | build |
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. |
build |
NONEmptyPrefixMappedToEmptyURI |
This error occurs if the policy has a prefix defined in the
Namespace element under the XMLPayload element, but no URI is
defined. |
build |
DuplicatePrefix |
This error occurs if the policy has the same prefix defined more than
once in the Namespace element under the XMLPayload element. |
build |
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.
|
build |
EmptyXPathExpression |
If the policy has an empty XPath expression within the XMLPayload
element, then the deployment of the API proxy fails. |
build |
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. |
build |
EmptyJSONPathExpression |
If the policy has an empty XPath expression within the
XMLPayload element, then the deployment of the API proxy fails. |
build |
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. |
build |
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. |
build |
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. |
build |
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. |
build |
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.
|
build |
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>