DataCapture 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

DataCapture 政策会从 API 代理中捕获数据（例如载荷、HTTP 标头以及路径或查询参数），以便在 Analytics 中使用。您可以在自定义 Analytics 报告中使用捕获的数据，也可以实现获利和监控规则。

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

数据收集器资源

要使用 DataCapture 政策，您必须先创建数据收集器资源。如需了解使用 Apigee 界面和 Apigee API 创建数据收集器资源的步骤，请参阅创建数据收集器。

`<DataCapture>`

<DataCapture> 元素定义了 DataCapture 政策。

<DataCapture async="true" continueOnError="true" enabled="true" name="DC">

这是一个 DataCapture 政策示例：

<DataCapture name="DC-1">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="my_data_variable" />
    </Capture>
</DataCapture>

DataCapture 政策的主要元素是 <Capture> 元素，用于指定捕获数据的方法。它包含两个必需的子元素：

<DataCollector> 元素，用于指定数据收集器 REST 资源。在本例中，该资源的名称为 dc_data_collector。
<Collect> 元素，用于指定捕获数据的方法。

在这个简单示例中，数据从名为 my_data_variable 的变量中提取，该变量已在代理的其他位置创建。变量由 ref 属性指定。

此外，<Collect> 元素还提供了其他几种通过其子元素捕获来源的数据。如需查看使用 DataCapture 政策捕获数据的更多示例，请参阅示例。

注意：您可以使用多个 <Capture> 元素，前提是它们对各自的子元素 <DataCollector 使用不同的值。例如，如果定义另一个数据收集器资源 dc_data_collector2，可以将以下 <Capture> 块添加到上面所示的政策中：

    <Capture>
        <DataCollector>dc_data_collector2</DataCollector>
            <Collect ref="my_data_variable2"/>
    </Capture>

但是，您无法添加两个用于在同一政策中引用同一数据收集器资源的 <Capture> 元素。

DataCapture 元素的语法如下。

<DataCapture name="capturepayment" continueOnError="false" enabled="true"> 
  <DisplayName>Data-Capture-Policy-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

  <!-- Existing Variable -->
  <Capture>
    <Collect ref="existing-variable" default="0"></Collect>
    <DataCollector>dc_1</DataCollector>
  </Capture>

  <!-- JSONPayload -->
  <Capture>
    <DataCollector>dc_2</DataCollector>
    <Collect default="0">
      <Source>request</Source>
      <JSONPayload>
        <JSONPath>result.var</JSONPath>
      </JSONPayload>
    </Collect>
  </Capture>

  <!-- URIPath -->
  <Capture>
    <DataCollector>dc_3</DataCollector>
    <Collect default="0">
      <URIPath>
        <!-- All patterns must specify a single variable to extract named $ -->
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
        <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
      </URIPath>
    </Collect>
  </Capture>
</DataCapture>

注意：DataCapture 政策的某些元素的行为与具有相同名称的 ExtractVariables 政策的相应元素有所不同。这些元素包括 <URIPath>、<QueryParam>、<Header>、<FormParam>、<JSONPayload> 和 <XMLPayload>。

要了解这些元素在 DataCapture 政策中的工作原理，请参阅 <Collect> 的子元素。

此元素具有所有政策中常见的以下属性：

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

下表提供了 <DataCapture> 的子元素的简要说明。

子元素	必需	说明
`<Capture>`	必需	捕获指定变量的数据。

示例

以下示例展示了使用 DataCapture 政策的各种方式。

捕获内置变量的数据

以下代码示例说明了如何捕获内置变量 message.content 的数据，该变量包含请求的内容、响应或错误消息。如需详细了解内置变量，请参阅流变量。

<DataCapture name="DC-FullMessage">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="message.content" />
    </Capture>
</DataCapture>

在以上代码中，</Collect> 元素的 ref 特性指定要捕获的变量，该变量在此示例中名为 "message.content"。

该示例使用 <Capture> 元素来捕获数据，该元素还包含指定数据收集器资源名称的 <DataCollector> 元素。

以内嵌方式采集数据

下一个示例展示了如何使用 <JSONPayload>（<Collect> 元素的子元素）以内嵌方式捕获数据。

<DataCapture name="DC-Currency">
    <Capture>
        <DataCollector>dc_data_collector<DataCollector>
        <Collect>
            <JSONPayload>
                <JSONPath>$.results[0].currency</JSONPath>
            </JSONPayload>
        </Collect>
    </Capture>
</DataCapture>

在上述代码中：

<JSONPayload> 元素指定从中提取变量值的 JSON 格式消息。
<JSONPath> 元素指定用于从消息中提取值的 JSON 路径，在本例中为 $.results[0].currency。

举例来说，假设收到消息时提取的值是 1120。那么发送给 Analytics 的最终条目

{
    "dc_data_collector": "1120"
}

<Capture>

<Capture> 元素指定捕获数据的方法。

<Capture />

下表提供了 <Capture> 的子元素的简要说明。

子元素	是否必需？	说明
`<DataCollector>`	必需	指定数据收集器资源。
`<Collect>`	必需	指定捕获数据的方法。

<DataCollector>

<DataCollector> 元素指定数据收集器资源。

<DataCollector>dc_data_collector</DataCollector>

下表说明 <DataCollector> 元素的属性。

属性	说明	默认值	是否必需？	类型
范围	如果要捕获获利变量，请指定此属性并将值设置为 `monetization`。如需详细了解您可以捕获的获利变量，请参阅捕获获利数据。	不适用	可选	字符串

<DataCollector> 元素的正文包含数据收集器资源的名称。

<Collect>

<Collect> 元素指定捕获数据的方法。

<Collect ref="existing-variable" default="0"/>

下表说明 <Collect> 元素的特性。

属性	说明	默认值	是否必需？	类型
ref	要为其捕获数据的变量。	不适用	可选 - 如果省略 `ref`，则必须仅指定以下其中一项：`QueryParam`、`Header`、`FormParam`、`URIPath`、`JSONPayload` 或 `XMLPayload`。	字符串
默认	指定在未在运行时填充变量值时发送到 Analytics 的值。例如，如果您设置了 `default="0"`，则发送到 Analytics 的值将为 0。	如果您未指定 `default` 的值，并且变量值在运行时未填充，则发送到 Analytics 的值将为 `null`（对于数字变量）或 `"Not set"`（对于字符串变量）。	必需	字符串

可以使用 ref 特性从现有变量捕获数据，也可以使用 <Collect> 子元素捕获数据。

`<Collect>` 的子元素

下表提供了 <Collect> 的子元素的简要说明：

注意：下面列出的 <Collect> 的子元素的行为与 ExtractVariables 政策的对应元素（具有相同的名称）有所不同。

子元素	是否必需？	说明
`<Source>`	可选	指定要解析的变量。
`<URIPath>`	可选	从 request 源消息的 `proxy.pathsuffix` 中提取值。
`<QueryParam>`	可选	从 request 源消息的指定查询参数中提取值。
`<Header>`	可选	从指定 request 或 response 消息的指定 HTTP 标头中提取值。
`<FormParam>`	可选	从指定 request 或 response 消息的指定表单参数中提取值。
`<JSONPayload>`	可选	指定将从中提取变量值的 JSON 格式的消息。注意：与 ExtractVariables 政策中的相应元素不同，`DataCapture` 政策中的 `<JSONPayload>` 元素不需要或嵌套 `<Variable>` 元素。
`<XMLPayload>`	可选	指定将从中提取变量值的 XML 格式的消息。注意：与 ExtractVariables 政策中的相应元素不同，`DataCapture` 政策中的 `<XMLPayload>` 元素不需要或嵌套 `<Variable>` 元素。

<Source>

指定一个变量，用于命名要解析的消息。<Source> 的值默认为 message。message 值取与上下文相关。在请求流中，message 解析为请求消息。在响应流中，message 解析为响应消息。

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

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<Collect>`
子元素	不适用

<Source >request</Source>

<URIPath>

从 request 源消息的 proxy.pathsuffix 中提取值。应用于该模式的路径为 proxy.pathsuffix，不包括 API 代理的基本路径。如果源消息解析为 response 消息类型，则该元素不执行任何操作。

默认值	不适用
是否必需？	可选
类型	复杂
父元素	`<Collect>`
子元素	<Pattern>

属性

属性	说明	默认值	是否必需？	类型
ignoreCase	指定在匹配模式时忽略大小写。	false	可选	布尔值

<Collect>
    <URIPath>
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
    </URIPath>
</Collect>

您可以使用多个 <Pattern> 元素：

<URIPath>
   <Pattern ignoreCase="false">/foo/{$}</Pattern>
   <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
</URIPath>

注意：您必须指定一个名为 {$} 的变量。可能有多个唯一的 Pattern 元素，但第一个匹配模式将针对特定请求进行解析。

<QueryParam>

从 request 源消息的指定查询参数中提取值。如果源消息解析为 response 消息类型，则该元素不执行任何操作。

默认值	不适用
是否必需？	可选
类型	复杂
父元素	`<Collect>`
子元素	<Pattern>

属性

属性	说明	默认值	是否必需？	类型
name	指定查询参数的名称。如果多个查询参数具有相同的名称，请使用索引引用，其中查询参数的第一个实例没有索引，第二个索引位于索引 2，第三个索引位于索引 3，以此类推。	不适用	必需	字符串

<Collect>
    <QueryParam name="code">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

如果多个查询参数具有相同的名称，请使用索引来引用参数：

<Collect>
    <QueryParam name="code.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

注意：您必须指定一个名为 {$} 的变量。可能有多个唯一的 Pattern 元素，但针对特定匹配将解析第一个匹配模式。

<Header>

从指定的 request 或 response 消息的指定 HTTP 标头中提取值。如果多个标头具有相同的名称，则它们的值存储在一个数组中。

默认值	不适用
是否必需？	可选
类型	复杂
父元素	`<Collect>`
子元素	<Pattern>

属性

属性	说明	默认值	是否必需？	类型
name	指定从中提取值的标头的名称。如果多个标头具有相同的名称，请使用索引引用，其中标头的第一个实例没有索引，第二个索引位于索引 2，第三个索引位于索引 3，以此类推。使用 `.values` 来获取数组中的所有标头。	不适用	必需	字符串

<Collect>
    <Header name="my_header">
        <Pattern ignoreCase="false">Bearer {$}</Pattern>
    </Header>
</Collect>

如果多个标头具有相同的名称，请使用索引来引用数组中的各个标头：

<Collect>
    <Header name="my_header.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

或者列出数组中的所有标头，如下所示：

<Collect>
    <Header name="my_header.values">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

注意：您必须指定一个名为 {$} 的变量。可能有多个唯一的 Pattern 元素，但第一个匹配模式将针对特定请求进行解析。

<FormParam>

从指定的 request 或 response 消息的表单参数中提取值。仅当指定消息的 Content-Type 标头为 application/x-www-form-urlencoded 时，才能提取表单参数。

默认值	不适用
是否必需？	可选
类型	复杂
父元素	`<Collect>`
子元素	<Pattern>

属性

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

<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

注意：您必须指定一个名为 {$} 的变量。可能有多个唯一的 Pattern 元素，但第一个匹配模式将针对特定请求进行解析。

<JSONPayload>

指定将从中提取变量值的 JSON 格式的消息。只有在消息的 Content-Type 标头为 application/json 时，才会执行 JSON 提取。

默认值	不适用
是否必需？	可选
类型	复杂
父元素	`<Collect>`
子元素	<JSONPath>

<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

注意：与 ExtractVariables 政策中的相应元素不同，DataCapture 政策中的 <JSONPayload> 元素不需要 <Variable> 元素，也不会嵌套在其中。

<JSONPath>

<JSONPayload> 元素的必需子元素。指定用于从 JSON 格式的消息中提取值的 JSON 路径。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<JSONPayload>`
子元素	不适用

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

<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

指定将从中提取变量值的 XML 格式的消息。仅当消息的 Content-Type 标头为 text/xml、application/xml 或 application/*+xml 时才会提取 XML 载荷。

默认值	不适用
是否必需？	可选
类型	复杂
父元素	`<Collect>`
子元素	`<Namespaces>` `<XPath>`

下表提供了 <XMLPayload> 的子元素的简要说明。

子元素	是否必需？	说明
`<Namespaces>`	可选	指定要在 XPath 评估中使用的零个或更多命名空间。
`<XPath>`	必需	指定为变量定义的 XPath。

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="soap">http://schemas.xmlsoap.org/soap/envelope/</Namespace>
            <Namespace prefix="ns1">http://ns1.example.com/operations</Namespace>
        </Namespaces>
        <!-- get the local name of the SOAP operation -->
        <XPath>local-name(/soap:Envelope/soap:Body/ns1:*[1])</XPath>
    </XMLPayload>
</Collect>

注意：与 ExtractVariables 政策中的 <XMLPayload> 元素不同，DataCapture 政策中的 <XMLPayload> 元素不会嵌套在 <Variable> 元素中。

<Namespaces>

指定可在 XPath 表达式中使用的命名空间集。示例如下。

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
            <Namespace prefix="places">http://places.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint/places:name</XPath>
    </XMLPayload>
</Collect>

如果您未在 XPath 表达式中使用命名空间，则可以省略或注释掉 <Namespaces> 元素，如以下示例所示：

<Collect>
    <XMLPayload>
        <!-- <Namespaces/> -->
        <XPath>/Directions/route/leg/name</XPath>
    </XMLPayload>
</Collect>

<Namespace>

指定在 XPath 表达式中使用的一个命名空间和相应的前缀。示例如下。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<Namespaces>`
子元素	不适用

属性

属性	说明	默认值	是否必需？	类型
`prefix`	用于引用 xpath 表达式中的命名空间的前缀。此前缀不必与在原始 XML 文档中使用的前缀相同。	不适用	必需	字符串

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint</XPath>
    </XMLPayload>
</Collect>

<XPath>

元素的必需子元素。指定为变量定义的 XPath。仅支持 XPath 1.0 表达式。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<XMLPayload>`
子元素	不适用

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

   <XPath>/test/example</XPath>

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

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

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

<ThrowExceptionOnLimit>

<ThrowExceptionOnLimit> 元素指定达到变量数量的捕获限制或变量大小上限时会发生什么情况。请参阅强制执行捕获限制。

<ThrowExceptionOnLimit> 的值可以是以下值之一：

false：变量的数据会发送到 Analytics。
true：返回错误消息，并且数据不会发送到 Analytics。

错误参考信息

运行时错误

下表介绍了执行政策时可能发生的运行时错误。

故障代码	原因
`DataCollectorTypeMismatch`	要捕获的值与 `DataCollector` 类型不匹配。
`ExtractionFailure`	数据提取失败。
`UnresolvedVariable`	变量不存在。
`VariableCountLimitExceeded`	捕获的变量数超过了变量数上限（100 个变量）。
`VariableValueLimitExceeded`	捕获值的大小超过了单一变量上限（400 字节）。
`MsgContentParsingFailed`	消息内容无法解析为 XML 或 JSON。
`InvalidMsgContentType`	消息内容类型与政策捕获子句中的预期消息内容类型不匹配。
`NonMsgVariable`	`<Source>` 元素值未引用消息变量。
`JSONPathQueryFailed`	`JSONPath` 查询未能解析为值。
`PrivateVariableAccess`	尝试访问私有变量失败。
`XPathEvaluationFailed`	`XPath` 无法解析为值。

运行时错误通过以下两种方式返回：

向客户端 (continueOnError=false) 返回错误响应
如果将政策的 continueOnError 特性设置为 false，则在政策执行期间发生的错误将中止消息处理并返回描述性错误消息。政策将尝试在返回消息之前捕获数据捕获政策中的所有相关错误。

DataCapture 错误分析字段

dataCapturePolicyErrors 字段包含已发生的所有错误的列表。下面显示的是 Analytics 数据映射情况的示例：

# Example payload
[
     {
         errorType: TypeMismatch,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchaseValue
     },
     {
         errorType: MaxValueSizeLimitReached,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchasedItems
     },
]

此字段受 400 字节变量大小限制的约束。

部署错误

故障代码	原因
`DeploymentAssertionError`	部署期间无法在组织中找到该政策中引用的 DataCollector。
`JsonPathCompilationFailed`	使用指定的 `JSONPath` 进行编译失败。
`XPathCompilationFailed`	如果 `XPath` 元素中使用的前缀或值不是政策中声明的任何命名空间的一部分，则 API 代理部署将失败。
`PatternCompilationFailed`	模式编译失败。

在调试工具中查找 `DataCapture` 错误

调试工具中提供了 dataCapturePolicyErrors 变量。您可以使用 Google Analytics 不必发现错误来检测错误。例如，如果升级混合版本版本并在意外部署的代理中意外打断，则会出现错误。

强制执行捕获限制

Apigee 对捕获的数据中的变量施加以下限制：

允许的变量数为 100。
每个变量（包括列表值）的大小上限为 400 个字节。

执行数据捕获政策时，在将值添加到消息上下文中的数据捕获映射之前：

如果已达到变量数量上限，则新变量将被丢弃。
如果已达到变量大小限制，则系统会对值进行修剪，以满足所需的限制。

在这两种情况下：

调试消息将记录在消息处理器日志中。
系统会将 limit reached 错误消息附加到 dataCapturePolicyErrors，后者可在 Analytics 和 Debug 中使用。注意：只会附加一条有关达到允许的最大变量数的错误消息。
如果 <ThrowExceptionOnLimit> 为 true，则数据不会发送到 Analytics，而是会向客户端返回错误。

DataCapture 政策

概览

数据收集器资源

<DataCapture>

示例

捕获内置变量的数据

以内嵌方式采集数据

<Capture>

<DataCollector>

<Collect>

<Collect> 的子元素

<Source>

<URIPath>

属性

<QueryParam>

属性

<Header>

属性

<FormParam>

属性

<JSONPayload>

<JSONPath>

<XMLPayload>

<Namespaces>

<Namespace>

属性

<XPath>

<ThrowExceptionOnLimit>

错误参考信息

运行时错误

部署错误

在调试工具中查找 DataCapture 错误

强制执行捕获限制

相关主题

`<DataCapture>`

`<Collect>` 的子元素

在调试工具中查找 `DataCapture` 错误