ExtractVariables 政策

您正在查看的是 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,以及如何部署和运行每个示例。

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.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 设计者,假设您要将令牌值(而非整个标头)用作缓存查询中的键。您可以使用以上 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.latitudegeocoderesponse.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.durationdirectionsresponse.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

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

(可选)使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

不适用 必需
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true,即使在政策失败后,仍可以继续执行流。

false 可选
enabled

设置为 true 可强制执行政策。

设为 false关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。

true 可选
async

此特性已弃用。

false 已弃用

<DisplayName> 元素

除了用于 name 属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素,则会使用政策的 name 属性的值。

状态 可选
类型 字符串

<Source> 元素

(可选)指定要解析的变量。<Source> 的值默认为 messagemessage 值取与上下文相关。在请求流中,message 解析为请求消息。在响应流中,message 解析为响应消息。

虽然此政策通常用于从请求或响应消息中提取信息,但您也可以用它来从任何变量中提取信息。例如,您可以使用它从 AccessEntity 政策创建的实体、服务调用程序政策返回的数据中提取信息,或者从 XML 或 JSON 对象中提取信息。

如果 <Source> 无法解析或解析为非消息类型,则该政策将无法响应。

<Source clearPayload="true|false">request</Source>
默认: 消息
状态: 可选
类型: 字符串

属性

特性 说明 默认 状态 类型
clearPayload

如果要在从 <Source> 中提取数据后清除 <Source> 中指定的载荷,请设置为 true

仅当执行 ExtractVariables 后不需要源消息时,才使用 <clearPayload> 选项。设置为 true 会释放消息占用的内存。

false

可选 布尔值

<VariablePrefix> 元素

(可选)完整的变量名称是通过连接 <VariablePrefix>、一个点以及您在 <Pattern> 元素的 {大括号} 中或 <Variable> 元素中定义的名称来创建的。例如 myprefix.idmyprefix.dbncodemyprefix.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> 元素

(可选,请参阅下表中的“状态”行以了解详情。)从指定 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>.
类型: 不适用

属性

特性 说明 默认 状态 类型
name 指定从中提取值的标头的名称。如果多个标头具有相同的名称,请使用索引引用,其中标头的第一个实例没有索引,第二个索引位于索引 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 元素内是必需的。
类型: 不适用

属性

特性 说明 默认 状态 类型
name

指定提取值将要分配到的目标变量的名称。

name

必需 字符串
类型 指定变量值的数据类型。 不适用 可选

字符串。从列表中选择:

  • string
  • 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>/<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

必需 字符串
类型 指定变量值的数据类型。 布尔值 可选

字符串。从列表中选择:

  • string
  • 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 元素中指定的消息变量为以下任意一项,就会出现此错误:
  • 超出范围(在执行政策的特定流中不可用)
  • 无法解析(未定义)
steps.extractvariables.UnableToCast 500 如果政策无法将提取的值转换为变量,就会出现此错误。如果您尝试将一种数据类型的值设置为另一种数据类型的变量,通常就会发生这种情况。

部署错误

在您部署包含此政策的代理时,可能会发生这些错误。

错误名称 原因 修复
NothingToExtract 如果政策没有元素 URIPathQueryParamHeaderFormParamXMLPayloadJSONPayload 中的任一个,则 API 代理部署将失败,因为没有要提取的内容。
NONEmptyPrefixMappedToEmptyURI 如果政策在 XMLPayload 元素下的 Namespace 元素中定义了一个前缀,但未定义 URI,则会出现此错误。
DuplicatePrefix 如果政策在 XMLPayload 元素下的 Namespace 元素中多次定义了相同的前缀,就会出现此错误。
NoXPathsToEvaluate 如果政策在 XMLPayload 元素中没有 XPath 元素,则 API 代理的部署将失败并显示此错误。
EmptyXPathExpression 如果政策在 XMLPayload 元素内包含空的 XPath 表达式,则 API 代理部署将失败。
NoJSONPathsToEvaluate 如果政策在 JSONPayload 元素中没有 JSONPath 元素,则 API 代理的部署将失败并显示此错误。
EmptyJSONPathExpression 如果政策在 XMLPayload 元素内包含空的 XPath 表达式,则 API 代理部署将失败。
MissingName 如果政策在 QueryParamHeaderFormParamVariable等任何政策元素中没有 name 属性,则 API 代理部署将失败。
PatternWithoutVariable 如果政策未在 Pattern 元素中指定变量,则 API 代理部署将失败。Pattern 元素需要存储所提取数据的变量的名称。
CannotBeConvertedToNodeset 如果政策具有 XPath 表达式(其中将 Variable 类型定义为 nodeset),但无法将表达式转换为 nodeset,则 API 代理部署将失败。
JSONPathCompilationFailed 政策无法编译指定的 JSON 路径。
InstantiationFailed 无法实例化此政策。
XPathCompilationFailed 如果 XPath 元素中使用的前缀或值不是政策中声明的任何命名空间的一部分,则 API 代理部署将失败。
InvalidPattern 如果政策中的任何元素(如 URIPathQueryParamHeaderFormParamXMLPayloadJSONPayload)中的 Pattern 元素定义无效,则 API 代理部署将失败。

故障变量

当此政策在运行时触发错误时,将设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息

变量 其中 示例
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 消息内容

变量参考