ExtractVariables 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

内容

ExtractVariables 政策从请求或响应中提取内容，并将变量的值设置为该内容。您可以提取消息的任何部分，包括标头、URI 路径、JSON/XML 载荷、表单参数和查询参数。政策的工作原理是对消息内容应用文本模式，在找到匹配项时，使用指定的消息内容设置变量。

虽然您通常使用 ExtractVariables 从请求或响应消息中提取信息，但也可以使用它从其他来源提取信息，包括由 AccessEntity 政策创建的实体，XML 对象或 JSON 对象。

提取指定的消息内容后，您可以在处理请求和响应时在其他政策中引用该变量。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

视频

观看以下视频，详细了解 ExtractVariables 政策。

视频	说明
从 XML 载荷中提取变量	使用提取变量政策从 XML 载荷中提取变量。
从 JSON 载荷中提取变量	使用提取变量政策从 JSON 载荷中提取变量。
从参数中提取变量	从参数（例如查询、标头、表单或 URI 参数）中提取变量。
从多值参数中提取变量	从多值参数中提取变量。

示例

这些政策代码示例说明了如何从以下类型的工件中提取变量：

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://example.com/svc1/accounts/12797282

假设 API 代理的基本路径为 /svc1。当 Apigee 将上述 ExtractVariables 政策代码应用于此传入请求时，它会将变量 urirequest.id 设置为 12797282。在 Apigee 执行该政策后，处理流程中的后续政策或代码可以引用名为 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://example.com/accounts/12797282?code=DBN88271

当 Apigee 将上述 ExtractVariables 政策代码应用于此传入请求时，它会将变量 queryinfo.dbncode 设置为 88271。在 Apigee 执行该政策后，处理流程中的后续政策或代码可以引用名为 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 设计允许您指定多个同名的查询参数。您可以使用 ExtractVariables 政策来提取查询参数的多个实例的值。如需引用政策中同名的查询参数，请使用索引，其中查询参数的第一个实例没有索引，第二个索引为索引 2，第三个索引为索引 3，依此类推。

考虑以上示例政策代码处理以下传入请求的情况：

GET http://example.com/weather?w=Boston&w=Chicago

当 Apigee 将上述 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 将上述 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>

考虑以下 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 将上述 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>

考虑以下 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 将上述 ExtractVariables 政策代码应用于此 XML 消息时，它会设置三个变量。

directionsresponse.travelmode：获取值 DRIVING
directionsresponse.duration：获取值 19
directionsresponse.timeunit：获取值 minutes

所有变量均使用相同的变量前缀 directionsresponse。这些变量的后缀由 <Variable> 元素的 name 属性明确指定。

您现在可以在代理中访问变量 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>

注意：设置 Content-Type：从 XML 消息（包括 SOAP）中提取变量时，仅当 Content-Type 在消息标头（或 SOAP 标头）中设置时（例如 application/xml），变量提取才有效。

ExtractVariables 政策简介

API 开发者构建 API 代理，以根据消息的内容（包括标头、URI 路径、载荷和查询参数）实现不同行为。通常，代理会提取部分内容以在条件语句中使用。为此，请使用 ExtractVariables 政策。

在定义 ExtractVariables 政策时，您可以选择：

要设置的变量的名称
变量的来源
要提取和设置的变量数量

执行时，政策会对内容应用文本模式，并在发现匹配项时将指定变量的值设置为内容。然后，其他政策和代码可使用这些变量启用动态行为，或向 Apigee API Analytics 发送业务数据。

范围

使用 ExtractVariables 政策设置的变量具有“全局”范围。也就是说，在 ExtractVariables 政策定义新变量后，您可以从流（在 ExtractVariables 政策之后执行）的任何阶段的任何政策或代码访问该变量。包括：

PreFlow：ProxyEndpoint 和 TargetEndpoint（请求和响应）
PostFlow：ProxyEndpoint 和 TargetEndpoint（请求和响应）
PostClientFlow: ProxyEndpoint（仅限响应，使用 MessageLogging 政策>）
错误流

提示：如果调试工具中未看到新提取的变量，请尝试移除已添加的 <VariablePrefix> 元素。如需了解详情，请参阅此 ExtractVariables 未显示在跟踪记录中。

匹配和变量创建简介

ExtractVariables 政策从请求或响应中提取信息，并将此信息写入变量。对于您可以提取的每种信息类型（例如 URI 路径或 XML 数据），您可以指定要匹配的模式以及用于保存所提取信息的变量的名称。

但是，模式匹配方式取决于提取的来源。以下各部分介绍了您可以提取的两类基本信息。

匹配 URI 路径、查询参数、标头、表单参数和变量

从 URI 路径、查询参数、标头、表单参数和变量中提取信息时，可使用 <Pattern> 标记指定一个或多个要匹配的模式。例如，以下政策示例显示了 URI 路径的单个匹配模式：

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

在此示例中，urirequest.pathSeg 变量设置为 /a/ 后 proxy.pathsuffix 中显示的任何内容。例如，假设您的 API 代理的基本路径为 /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>

再次为入站请求网址提供基本路径为 /basepath/v1 的 API 代理：

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

下表介绍了所有政策父元素通用的特性：

属性	说明	默认	Presence
`name`	政策的内部名称。`name` 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。（可选）使用 `<DisplayName>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
`continueOnError`	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障	false	可选
`enabled`	设置为 `true` 可强制执行政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
`async`	此特性已弃用。	false	已弃用

<DisplayName> 元素

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

<DisplayName>Policy Display Name</DisplayName>

默认

默认	不适用如果省略此元素，则会使用政策的 `name` 属性的值。
Presence	可选
类型	字符串

不适用

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

Presence 可选

类型字符串

<Source> 元素

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

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

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

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

默认：	消息
状态：	可选
类型：	字符串

属性

属性说明默认值 Presence 类型

属性	说明	默认值	Presence	类型
`clearPayload`	如想在提取数据后清除 `<Source>` 中指定的载荷，请将其设置为true。请仅在执行 ExtractVariables 后不需要源消息的情况下使用 `<clearPayload>` 选项。设置为 true 会释放消息占用的内存。	false	可选	布尔值

clearPayload

如想在提取数据后清除 <Source> 中指定的载荷，请将其设置为true。

请仅在执行 ExtractVariables 后不需要源消息的情况下使用 <clearPayload> 选项。设置为 true 会释放消息占用的内存。

false

可选

布尔值

<VariablePrefix> 元素

（可选）完整的变量名称是通过连接 <VariablePrefix>、一个点以及您在 <Pattern> 元素的 {大括号} 中或 <Variable> 元素中定义的名称来创建的。例如 myprefix.id、myprefix.dbncode 或 myprefix.oauthtoken.。

<VariablePrefix>myprefix</VariablePrefix>

例如，假设名称的值为“user”。

如果未指定 <VariablePrefix>，则提取的值将分配给名为 user 的变量。
如果 <VariablePrefix> 指定为 myprefix，则提取的值将分配给名为 myprefix.user 的变量。

默认：	不适用
状态：	可选
类型：	字符串

<IgnoreUnresolvedVariables> 元素

（可选）设置为 true 可将任何无法解析的变量视为空字符串 (null)。如果您希望政策在任何引用的变量无法解析时抛出错误，请设置为 false。

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

默认：	False
状态：	可选
类型：	布尔值

<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>.`
类型：	不适用

属性

属性	说明	默认值	Presence	类型
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>.`
类型：	不适用

属性

属性	说明	默认值	Presence	类型
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>.`
类型：	不适用

属性

属性	说明	默认值	Presence	类型
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>.`
类型：	不适用

属性

属性	说明	默认值	Presence	类型
name	从中提取值的表单参数的名称。	不适用	必需	字符串

<Variable> 元素

（可选，请参阅下表中的“状态”行以了解详情。）指定要从中提取值的变量的名称。

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

从变量中提取两个值：

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>

默认：	不适用
状态：	可选。但是，必须至少包含以下其中一项：`<URIPath>`、`<QueryParam>`、`<Header>`、`<FormParam>`、`<JSONPayload>` 或 `<XMLPayload>.`
类型：	不适用

属性

属性	说明	默认值	Presence	类型
name	要从中提取值的变量的名称。	不适用	必需	字符串

<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 元素内是必需的。
类型：	不适用

属性

属性	说明	默认值	Presence	类型
name	指定提取值将要分配到的目标变量的名称。	name	必需	字符串
type	指定变量值的数据类型。	不适用	可选	字符串。从列表中选择：字符串布尔值整数 long float double nodeset（返回 JSON 片段）

说明

默认值

Presence

类型

name

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

name

必需

字符串

type

指定变量值的数据类型。

不适用

可选

字符串。从列表中选择：

字符串
布尔值
整数
long
float
double
nodeset（返回 JSON 片段）

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

（在 JSONPayload:Variable 元素中是必需的。）指定用于从 JSON 格式的消息中提取值的 JSON 路径。

注意：<JSONPath> 元素支持名为消息模板化的动态字符串替换功能。

<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>.`
类型：	不适用

属性

属性	说明	默认值	Presence	类型
`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>

默认：	不适用
状态：	可选
类型：	字符串

属性

属性	说明	默认值	Presence	类型
`prefix`	命名空间前缀。	不适用	必需	字符串

<XMLPayload>/<Variable> 元素

（可选）指定提取值将要分配到的目标变量。

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

默认：	不适用
状态：	可选
类型：	不适用

属性

属性	说明	默认值	Presence	类型
name	指定提取值将要分配到的目标变量的名称。	name	必需	字符串
type	指定变量值的数据类型。	布尔值	可选	字符串。从列表中选择：字符串布尔值整数 long float double nodeset（返回 XML 片段）

说明

默认值

Presence

类型

name

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

name

必需

字符串

type

指定变量值的数据类型。

布尔值

可选

字符串。从列表中选择：

字符串
布尔值
整数
long
float
double
nodeset（返回 XML 片段）

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

（在 XMLPayload:Variable 元素中是必需的。）指定为变量定义的 XPath。仅支持 XPath 1.0 表达式。

<XPath> 元素不支持消息模板。

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

具有命名空间的示例。如果您在 XPath 表达式中使用了命名空间，则必须在政策的 <XMLPayload><Namespaces> 部分声明命名空间。

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>

默认：	不适用
状态：	必需
类型：	字符串

注意：Apigee 不支持在 XPath 表达式中使用 parent、ancestor、following 和 preceding。如要获得相同的匹配结果，请尝试使用显式节点名称匹配或索引。例如：

<XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
获取 foo_attribute 的值。
<XPath>/Attributes/Attribute[4]/Value</XPath>
获取第 4 个属性的值。

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	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`	如果政策没有元素 `URIPath`、`QueryParam`、`Header`、`FormParam`、`XMLPayload` 或 `JSONPayload` 中的任一个，则 API 代理部署将失败，因为没有要提取的内容。
`NONEmptyPrefixMappedToEmptyURI`	如果政策在 `XMLPayload` 元素下的 `Namespace` 元素中定义了一个前缀，但未定义 URI，则会出现此错误。
`DuplicatePrefix`	如果政策在 `XMLPayload` 元素下的 `Namespace` 元素中多次定义了相同的前缀，就会出现此错误。
`NoXPathsToEvaluate`	如果政策在 `XMLPayload` 元素中没有 `XPath` 元素，则 API 代理的部署将失败并显示此错误。如果要从 XML 载荷中提取变量，则必须指定 `XPath` 子元素。
`EmptyXPathExpression`	如果政策在 `XMLPayload` 元素内包含空的 `XPath` 表达式，则 API 代理部署将失败。
`NoJSONPathsToEvaluate`	如果政策在 `JSONPayload` 元素中没有 `JSONPath` 元素，则 API 代理的部署将失败并显示此错误。
`EmptyJSONPathExpression`	如果政策在 `XMLPayload` 元素内包含空的 `XPath` 表达式，则 API 代理部署将失败。
`MissingName`	如果政策在 `QueryParam`、`Header`、`FormParam` 或 `Variable`等任何政策元素中没有 `name` 属性，则 API 代理部署将失败。
`PatternWithoutVariable`	如果政策未在 `Pattern` 元素中指定变量，则 API 代理部署将失败。`Pattern` 元素需要存储所提取数据的变量的名称。
`CannotBeConvertedToNodeset`	如果政策具有 `XPath` 表达式（其中将 `Variable` 类型定义为 nodeset），但无法将表达式转换为 nodeset，则 API 代理部署将失败。
`JSONPathCompilationFailed`	政策无法编译指定的 JSON 路径。	不适用
`InstantiationFailed`	无法实例化此政策。	不适用
`XPathCompilationFailed`	如果 `XPath` 元素中使用的前缀或值不是政策中声明的任何命名空间的一部分，则 API 代理部署将失败。
`InvalidPattern`	如果政策中的任何元素（如 `URIPath`、`QueryParam`、`Header`、`FormParam`、`XMLPayload` 或 `JSONPayload`）中的 `Pattern` 元素定义无效，则 API 代理部署将失败。 `Pattern` 元素不包含变量时会被视为无效。如需详细了解模式匹配，请参阅关于匹配和变量创建。

故障变量

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

变量	位置	示例
`fault.name="fault_name"`	`fault_name` 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	`fault.name = "SourceMessageNotAvailable"`
`extractvariables.policy_name.failed`	`policy_name` 是抛出故障的政策的用户指定名称。	`extractvariables.EV-ParseJsonResponse.failed = true`

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 errorcode 部分。不要依赖 faultstring 中的文本，因为它可能会发生变化。

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

故障规则示例

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

ExtractVariables 政策

内容

视频

示例

URI

查询参数

多个参数

标头

JSON

XML

ExtractVariables 政策简介

范围

匹配和变量创建简介

匹配 URI 路径、查询参数、标头、表单参数和变量

指定多个模式

指定具有多个变量的模式

匹配模式中的多个实例

在模式中使用特殊字符

匹配 JSON 和 XML

在多个位置写入同一变量

控制没有匹配时的行为

元素参考

<ExtractVariables> 属性

<DisplayName> 元素

<Source> 元素

属性

<VariablePrefix> 元素

<IgnoreUnresolvedVariables> 元素

<URIPath> 元素

属性

<QueryParam> 元素

属性

<Header> 元素

属性

<FormParam> 元素

属性

<Variable> 元素

属性

<JSONPayload> 元素

<JSONPayload>/<Variable> 元素

属性

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

<XMLPayload> 元素

属性

<XMLPayload>/<Namespaces> 元素

属性

<XMLPayload>/<Variable> 元素

属性

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

错误参考信息

运行时错误

部署错误

故障变量

错误响应示例

故障规则示例

架构

相关主题