使用自定义分析工具分析 API 消息内容

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

Edge API Analytics 会从每个 API 请求和响应中收集和分析各种统计信息。这些信息会自动收集，然后显示在 Edge 界面中或使用 Metrics API。如需详细了解这些统计信息，请参阅metrics和维度。

您可能还希望收集特定于 API 代理、应用、产品或开发者的自定义分析数据。例如，您可能希望从查询参数、请求标头、请求和响应正文或者您在 API 中定义的变量中收集资料。

本主题演示了如何使用 StatisticsCollector 政策从 API 请求/响应中提取自定义分析数据，并将这些数据提供给 Edge API Analytics。 然后介绍如何在 Edge 界面中的报告中或使用 Edge API 查看分析数据。

关于 Google Book API

本主题介绍如何将 API 代理请求中的自定义分析数据捕获到 Google Books API。借助 Google Books API，您可以按书名、主题、作者和其他特性搜索书籍。

例如，向 /volumes 端点发出请求以按书名执行搜索。将单个查询参数传递到包含书名的 Books API：

curl https://www.googleapis.com/books/v1/volumes?q=davinci%20code

调用会返回匹配搜索条件的项构成的 JSON 数组。以下所示为响应中的第一个数组元素（请注意，为简单起见，部分内容已省略）：

{
 "kind": "books#volumes",
 "totalItems": 1799,
 "items": [
  {
   "kind": "books#volume",
   "id": "ohZ1wcYifLsC",
   "etag": "4rzIsMdBMYM",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/ohZ1wcYifLsC",
   "volumeInfo": {
    "title": "The Da Vinci Code",
    "subtitle": "Featuring Robert Langdon",
    "authors": [
     "Dan Brown"
    ],
    "publisher": "Anchor",
    "publishedDate": "2003-03-18",
    "description": "MORE THAN 80 MILLION COPIES SOLD ....",
    "industryIdentifiers": [
     {
      "type": "ISBN_10",
      "identifier": "0385504217"
     },
     {
      "type": "ISBN_13",
      "identifier": "9780385504218"
     }
    ],
    "readingModes": {
     "text": true,
     "image": true
    },
    "pageCount": 400,
    "printType": "BOOK",
    "categories": [
     "Fiction"
    ],
    "averageRating": 4.0,
    "ratingsCount": 710,
    "maturityRating": "NOT_MATURE",
    "allowAnonLogging": true,
    "contentVersion": "0.18.13.0.preview.3",
    "panelizationSummary": {
     "containsEpubBubbles": false,
     "containsImageBubbles": false
    },
...
   "accessInfo": {
    "country": "US",
    "viewability": "PARTIAL",
    "embeddable": true,
    "publicDomain": false,
    "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
    "epub": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
    "pdf": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
...
   }
  }

请注意，系统会突出显示响应的几个方面：

  • 搜索结果数量
  • 书籍平均评分
  • 评分数量
  • 提供 PDF 版书籍

以下各部分介绍了如何收集响应以上几个方面以及包含搜索条件的查询参数 q 的统计信息。

为 Google Book API 创建 API 代理

您必须先创建一个调用 Google Book API 的 Edge API 代理，然后才能收集 Google Book API 的统计信息。然后，您可以调用该 API 代理，向 Google Book API 发出请求。

教程中关于创建 API 代理的第 2 步：创建 API 代理介绍了如何创建会调用 https://mocktarget.apigee.net API 的代理。请注意，本教程中描述的代理不需要 API 密钥即可调用 API。

使用相同的过程为 Google Book API 的 /volumes 端点创建 API 代理。在过程的第 5 步，当您创建 API 代理时，请设置以下属性以引用 Google Books API：

  • 代理名称：“mybooksearch”
  • 代理基本路径：“/mybooksearch”
  • 现有 API：“https://www.googleapis.com/books/v1/volumes”

创建和部署代理后，您应该能够使用表单中的 curl 命令来调用该代理：

curl http://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

其中，org_name 和 env_name 指定部署代理的组织和环境。例如： 

curl http://myorg-test.apigee.net/mybooksearch?q=davinci%20code

收集自定义分析数据

从 API 请求中收集分析数据分为两步：

  1. 提取相关数据并将其写入变量。

    传递给 Edge API Analytics 的所有数据都来自变量中存储的值。某些数据会自动存储在预定义的 Edge Flow 变量中，例如传递给 API 代理的查询参数的值。如需详细了解预定义的流变量，请参阅流变量概览。

    使用 ExtractVariables 政策从请求或响应中提取自定义内容，然后将该数据写入变量。

  2. 将变量中的数据写入 Edge API Analytics。

    使用 Stats Collector 政策将变量中的数据写入 Edge API Analytics。数据可能来自预定义的 Edge 流变量，或者由提取变量政策创建的变量。

收集统计数据后，您可以使用 Edge 管理界面或 API 检索和过滤统计信息。例如，您可以生成一个自定义报告以显示每个书名的平均评分，其中书名与传递给 API 的查询参数的值相对应。

使用 ExtractVariables 政策提取分析数据

必须先提取分析数据并将其存储到变量（由 Edge 预定义的流变量或您定义的自定义变量）中，然后才能将其传递给 API Analytics。要将数据写入变量，请使用 ExtractVariables 政策。

ExtractVariables 政策可以使用 JSONPath 或 XPath 表达式来解析消息载荷。如需从 Google Book API 的 JSON 搜索结果中提取信息，请使用 JSONPath 表达式。 例如，要从 JSON 结果数组中的第一项中提取 averageRating 的值，请使用以下 JSONPath 表达式：

$.items[0].volumeInfo.averageRating

在 JSONPath 经过评估后，ExtractVariables 政策会将提取的值写入变量中。

在此示例中，您将使用 ExtractVariables 政策创建以下四个变量：

  • responsejson.totalitems
  • responsejson.ratingscount
  • responsejson.avgrating
  • responsejson.pdf

在这些变量中，responsejson 是变量前缀，totalitems、ratingscount、avgrating 和 pdf 是变量名称。

以下 ExtractVariables 政策介绍了如何从 JSON 响应中提取数据并将其写入自定义变量。每个 <Variable> 元素都使用 name 属性来指定自定义变量的名称和关联的 JSONPath 表达式。<VariablePrefix> 元素指定变量前缀。

在 Edge 界面中将此政策添加到您的 API 代理。如果您在 XML 中构建 API 代理，请将政策添加到 /apiproxy/policies 下名为 ExtractVars.xml 的文件中：

<ExtractVariables name="ExtractVars">
    <Source>response</Source>
    <JSONPayload>
        <Variable name="totalitems">
            <JSONPath>$.totalItems</JSONPath>
        </Variable>
        <Variable name="ratingscount">
            <JSONPath>$.items[0].volumeInfo.ratingsCount</JSONPath>
        </Variable>
        <Variable name="avgrating">
            <JSONPath>$.items[0].volumeInfo.averageRating</JSONPath>
        </Variable>
        <Variable name="pdf">
            <JSONPath>$.items[0].accessInfo.pdf.isAvailable</JSONPath>
        </Variable>
    </JSONPayload>
    <VariablePrefix>responsejson</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

使用统计信息收集器政策将数据写入 Google Analytics（分析）服务

使用 Stats Collector 政策将变量中的数据写入 Edge API Analytics。统计信息收集政策具有以下形式：

<StatisticsCollector>
<DisplayName>Statistics Collector-1</DisplayName>
    <Statistics>
        <Statistic name="statName" ref="varName" type="dataType">defVal</Statistic>
       …
    </Statistics>
</StatisticsCollector>

其中：

  • statName 可指定您在自定义报告中用于引用统计数据的名称。
  • varName 指定包含要收集的分析数据的变量的名称。 此变量可以内置在 Edge 中，也可以使用“提取变量”政策创建的自定义变量。

  • dataType 将记录的数据的数据类型指定为字符串、整数、浮点数、长整型、双精度或布尔值。

    对于字符串类型的数据，您可以将统计数据作为自定义报告的维度引用。对于数值数据类型（整数/浮点型/长/双精度），您可以在自定义报告中将统计数据作为维度或指标进行引用。

  • defValue 可以选择为自定义变量提供默认值，如果变量无法解析或变量未定义，系统会将默认值发送到 API Analytics。

在以下示例中，您将使用统计信息收集器政策来收集“提取变量”政策创建的变量的数据。您还可以收集传递到每个 API 调用的查询参数的值。使用预定义的数据流变量引用查询参数：

request.queryparam.queryParamName

对于名为“q”的查询参数，将其引用为：

request.queryparam.q

在 Edge 界面中将此政策添加到您的 API 代理中；或者，如果您使用 XML 构建 API 代理，请在 /apiproxy/policies 下添加一个名为 AnalyzeBookResults.xml, 的文件，其中包含以下内容：

<StatisticsCollector name="AnalyzeBookResults">
 <Statistics>
        <Statistic name="totalitems" ref="responsejson.totalitems" type="integer">0</Statistic>
        <Statistic name="ratingscount" ref="responsejson.ratingscount" type="integer">0</Statistic>
        <Statistic name="avgrating" ref="responsejson.avgrating" type="float">0.0</Statistic>
        <Statistic name="pdf" ref="responsejson.pdf" type="boolean">true</Statistic>
        <Statistic name="booktitle" ref="request.queryparam.q" type="string">none</Statistic>
 </Statistics>
</StatisticsCollector>

将政策附加到 ProxyEndpoint 响应流

为使政策能够正常使用，必须将政策附加到 API 代理流中的适当位置。在此用例中，必须在收到来自 Google Book API 的响应之后、将响应发送到发出请求的客户端之前执行政策。因此，请将政策附加到 ProxyEndpoint 响应 PreFlow。

以下 ProxyEndpoint 配置示例先执行名为 ExtractVars 的政策以解析响应消息。然后，名为 AnalyzeBookResults 的政策将这些值转发给 API Analytics：

<ProxyEndpoint name="default">
    ><PreFlow name="PreFlow">
        <Request/>
        <Response>
            <Step>
                <Name>Extract-Vars</Name>
            </Step>
            <Step>
                <Name>AnalyzeBookResults</Name>
            </Step>
        </Response>
    </PreFlow>
 <HTTPProxyConnection>
  <!-- Base path used to route inbound requests to this API proxy -->
  <BasePath>/mybooksearch</BasePath>
  <!-- The named virtual host that defines the base URL for requests to this proxy -->
  <VirtualHost>default</VirtualHost>
 </HTTPProxyConnection>
 <RouteRule name="default">
 <!-- Connects the proxy to the target defined under /targets -->
  <TargetEndpoint>default</TargetEndpoint>
 </RouteRule>
</ProxyEndpoint>

部署 API 代理

进行这些更改后，您需要部署已配置的 API 代理。

填充分析数据

部署 API 代理后，请调用代理以在 API Analytics 中填充数据。为此，请运行以下命令，其中每个命令均使用不同的书名：

《白鲸记》(Moby Dick)：

curl https://org_name-env_name.apigee.net/mybooksearch?q=mobey%20dick

《达芬奇密码》(The Da Vinci Code)：

curl https://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

《消失的爱人》(Gone Girl)：

curl https://org_name-env_name.apigee.net/mybooksearch?q=gone%20girl

《权力的游戏》(Game of Thrones)：

curl https://org_name-env_name.apigee.net/mybooksearch?q=game%20of%20thrones

查看分析数据

Edge 提供了两种查看自定义分析数据的方式：

  • Edge 界面支持自定义报告，您可以通过报告以图形图表查看数据。
  • 借助 Metrics API，您可以通过对 Edge API 进行 REST 调用来检索分析数据。您可以使用 API 并采用可嵌入到门户或自定义应用中的自定义微件形式构建您自己的可视化图表。

使用 Edge 界面生成统计信息报告

利用自定义报告，您可以深入到特定 API 统计信息，也可以查看想要查看的确切数据。您可以使用 Edge 内置的任何metrics和维度来创建自定义报告。此外，您还可以使用通过 StatisticsCollector 政策提取的任何分析数据。

在创建 StatisticsCollector 政策时，您可以指定所收集数据的数据类型。对于字符串类型的数据，在自定义报告中以维度的形式引用统计数据。对于数值类型的数据（整数/浮点型/长整型/双精度型），在自定义报告中以维度或指标的形式引用统计数据。如需了解详情，请参阅管理自定义报告。

使用 Edge 界面生成自定义报告：

  1. 访问“自定义报告”页，如下所述。

    边缘

    如需使用 Edge 界面访问“自定义报告”页面，请执行以下操作：

    1. 登录 apigee.com/edge。
    2. 在左侧导航栏中选择分析 > 自定义报告 > 报告。

    传统 Edge (Private Cloud)

    如需使用传统版 Edge 界面访问“自定义报告”页面，请执行以下操作：

    1. 登录 http://ms-ip:9000，其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。

    2. 在顶部导航栏中依次选择分析 > 报告。

  2. 在“自定义报告”页中，点击添加自定义报告。
  3. 指定报告名称，例如 mybookreport。

  4. 选择一个内置指标（如流量）和一个聚合函数（如 Sum）。

    或者，选择一个通过使用 StatisticsCollector 政策创建的数值数据统计信息。例如，选择 ratingscount 和聚合函数 Sum。

  5. 选择一个内置维度（如 API 代理），或选择通过使用 StatisticsCollector 政策创建的任意字符串或数值统计信息。

    例如，选择 booktitle。您的报告现在将按 booktitle 显示 ratingscount 的总和：

    自定义书籍报告
  6. 选择保存。该报告会显示在所有自定义报告的列表中。

  7. 要运行报告，请选择报告名称。默认情况下，报告会显示过去一小时的数据。

  8. 要设置时间范围，请选择右上角的日期显示以打开日期选择器弹出窗口。

  9. 选择过去 7 天。报告会更新，以显示每个书名的评分总和：

    书籍报告图表

使用 Edge API 获取统计信息

使用 Edge 指标 API 获取有关自定义分析数据的统计信息。在下面的请求示例中：

  • /stats 后面的网址资源指定所需的维度。在此示例中，您将获取维度 booktitle 的数据。
  • select 查询参数，用于指定要检索的metrics。此请求会根据 ratingscount 的总和返回分析。

  • timeRange 参数指定所返回数据的时间间隔。时间范围的格式为：

    MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

完整的 API 调用是：

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00" /
-u email:password

您应该会在表单中看到响应：

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "5352.0"
              ]
            }
          ],
          "name": "gone girl"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "4260.0"
              ]
            }
          ],
          "name": "davinci code"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1836.0"
              ]
            }
          ],
          "name": "game of thrones"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1812.0"
              ]
            }
          ],
          "name": "mobey dick"
        }
      ],
      "name": "prod"
    }
  ],
  "metaData": {
    "errors": [],
    "notices": [
      "query served by:9b372dd0-ed30-4502-8753-73a6b09cc028",
      "Table used: uap-prod-gcp-us-west1.edge.edge_api_raxgroup021_fact",
      "Source:Big Query"
    ]
  }
}

Edge 指标 API 有许多选项。例如，您可以按升序或降序对结果进行排序。在以下示例中，您使用升序排序：

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&sort=ASC" /
-u email:password

您也可以通过指定相关维度的值来过滤结果。在以下示例中，针对《消失的爱人》(Gone Girl) 和《达芬奇密码》(The Da Vinci Code)，按结果对报告进行过滤：

$ curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&filter=(booktitle%20in%20'gone%20girl'%2C%20'davinci%20code')" /
-u email:password

借助解决方案构建器，您可以通过简单易用的管理界面对话框创建自定义分析变量。

建议您阅读上一部分“收集自定义分析数据”，其中介绍了提取变量和统计信息收集器政策如何协同工作以将自定义变量提供给 Edge API Analytics。如您所见，界面遵循相同的模式，但提供了一种便捷方式供您通过界面完整地配置内容。如果您希望，则可以使用界面来试用 Google Books API 示例，而不是手动修改和附加政策。

借助 Solution Builder 对话框，您可以直接在界面中配置分析变量。此工具会为您生成政策并将其附加到 API 代理。这些政策会从请求或响应中提取感兴趣的变量，并将提取的变量传递给 Edge API Analytics。

Solution Builder 会创建新的 ExtractVariables 政策和 StatisticsCollector 政策，并为其指定独一无二的名称。在给定代理修订版本中创建上述政策后，Solution Builder 不允许您返回更改这些政策。如需进行更改，请直接在政策编辑器中修改生成的政策。

  1. 在 Edge 界面中前往代理的“概览”页面。
  2. 点击开发。
  3. 在“开发”页面上，从“工具”菜单中选择自定义分析集合。此时会显示一个 Solution Builder 对话框。
  4. 在 Solution Builder 对话框中，先配置 ExtractVariables 和 StatisticsCollector 这两个政策。然后配置这些政策的附加位置。
  5. 指定您要提取的数据：
    • 位置类型：选择您要收集的数据类型以及这些数据的收集位置。您可以从请求端或响应端选择数据。例如，请求：查询参数或响应：XML 正文。
    • 位置来源：识别您要收集的数据。例如，查询参数中的名称或响应正文中 XML 数据的 XPath。
  6. 指定 StatisticsCollector 政策将用于识别所提取数据的变量名称（和类型）。请参阅本主题中的命名限制。

    您使用的名称会显示在 Custom Report Builder 界面的维度或指标的下拉菜单中。
  7. 选择要在 API 代理流中附加生成的 ExtractVariables 政策和 StatisticsCollector 政策的位置。如需获取指导，请参阅将政策附加到 ProxyEndpoint 响应流。为使政策能够正常使用，必须将政策附加到 API 代理流中的适当位置。您需要在流程中捕获的变量处于范围（已填充）的阶段附加政策。
  8. 点击添加收集器以添加更多自定义变量。

  9. 完成后，点击构建解决方案。

  10. 保存并部署代理。

现在，您可以按照上述说明为数据生成自定义报告。