使用异步自定义报告 API

本页面适用于 ApigeeApigee Hybrid

查看 Apigee Edge 文档。

Apigee Analytics 提供一组丰富的互动式信息中心、自定义报告生成器和相关功能。但是,这些功能旨在提供互动性:您可提交 API 或界面请求,然后请求会被阻止,直到分析服务器提供响应。

但是,如果完成分析请求所需的时间过长,则请求超时。如果查询请求需要处理大量数据(例如,数百 GB),则可能会由于超时而失败。

通过异步查询处理,您可以查询非常大的数据集,并在以后检索结果。如果您发现互动查询超时,可以考虑使用离线查询。适合使用异步查询处理的情况包括:

  • 分析和生成跨越很长时间间隔的报告。
  • 使用各种分组维度以及增加查询复杂性的其他限制条件来分析数据
  • 在发现某些用户或组织的数据量大幅增加时管理查询。

本文档介绍了如何使用 API 启动异步查询。您也可以按照运行自定义报告中的说明使用界面。

将 Reports API 与界面进行比较

创建和管理自定义报告介绍如何使用 Apigee 界面创建和运行自定义报告。您可以同步或异步运行此类报告。

使用界面生成自定义报告的大部分概念都适用于使用 API。也就是说,在使用 API 创建自定义报告时,您需要指定 Apigee 中内置的指标维度过滤器

使用 API 生成的报告与使用界面生成的报告之间的主要区别在于,前者会写入 CSV 或 JSON(以换行符分隔)文件,而后者会显示在界面中。

查询的时间限制

Apigee 对异步查询的时间范围强制执行 365 天的上限。

如何创建异步分析查询

您可以在三个步骤内进行异步分析查询:

  1. 提交查询。

  2. 获取查询状态。

  3. 检索查询结果。

第 1 步:提交查询

您必须向 Queries API 发送 POST 请求。此 API 会告知 Apigee 在后台处理您的请求。如果查询成功提交,API 将返回 201 状态和一个 ID,您将在后续步骤中使用此 ID 引用该查询。

例如:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @json-query-file

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

请求的正文是查询的 JSON 说明。在 JSON 正文中,指定用于定义报告的指标维度过滤器

下面展示了一个 json-query-file 文件示例:

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"
}

如需查看请求正文语法的完整说明,请参阅下面的请求正文简介

示例响应:

请注意,查询 ID 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd 会包含在响应中。除了 HTTP 状态 201 以外,enqueuedstate 也表示请求成功。

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

第 2 步:获取查询状态

如需请求查询的状态,请向 Queries API 发送 GET 请求。您需提供 POST 调用返回的查询 ID。例如:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

响应示例:

如果查询仍在进行中,您会收到如下响应,其中 staterunning

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

查询成功完成后,您会看到如下所示的响应,其中 state 设置为 completed

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

第 3 步:检索查询结果

查询状态为 completed 后,您可以使用以下两种方法检索查询结果:

  • getResulturl(推荐):这是一种新方法,可返回一个网址,供您查看查询结果。此方法对查询结果没有大小限制。
  • getResult:这是下载包含查询结果的 zip 文件的较旧方法。此方法会对查询结果施加 32 MB 的大小限制。

以下标签页显示了使用任一方法检索查询结果的 API 调用。如上所述,查询 ID 为 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID/resulturl" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

以下是调用的示例响应:

{
  "urls": [
    "uri": "https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7",
  "md5": "23db6982caef9e9152f1a5b2589e6ca3",
  "sizeBytes": 1024
  ]
}

响应包含具有以下字段的列表 urls[]

  • uri:一个字符串,即报告的 JSON 数据的签名网址。您可以通过该网址查看报告。
  • md5:JSON 数据的 MD5 哈希。
  • sizeBytes:返回文件的大小(以字节为单位)。

如需查看 JSON 格式的示例结果,请参阅查询结果简介

getResult

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID/result" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

如需检索下载的文件,您需要配置所使用的工具,以便将下载的文件保存到您的系统。例如:

  • 如果您使用 cURL,则可以使用 -O -J 选项,如上所示。
  • 如果您使用 Postman,则需要选择保存并下载按钮。在这种情况下,系统会下载一个名为 response 的 ZIP 文件。
  • 如果您使用的是 Chrome 浏览器,系统会自动接受下载。

如果请求成功,并且存在非零结果集,则结果将作为压缩的 JSON(以换行符分隔)文件下载到客户端。已下载文件的名称将是 OfflineQueryResult-.zip

例如:OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

ZIP 文件包含 JSON 结果的 .gz 归档文件。如需访问 JSON 文件,请解压缩下载文件,然后使用 gzip 命令提取 JSON 文件:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

请求正文简介

本部分介绍您可以在查询的 JSON 请求正文中使用的每个参数。如需详细了解可在查询中使用的指标和维度,请参阅分析参考文档

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_display_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}
属性 说明 是否必需?
metrics

指标数组。您可以为每个指标包括的一个查询指定一个或多个指标。只有指标名称是必填的:

  • name:(必填)指标表中所定义的指标名称。
  • function:(可选)聚合函数为 avgminmaxsum

    并非所有指标都支持所有聚合函数。指标中的文档包含一个列明了指标名称和指标所支持函数(avgminmaxsum)的表。

  • alias:(可选)包含输出中指标数据的属性的名称。如果省略,则默认为指标名称与聚合函数的名称的组合。
  • operator:(可选)在计算其值后将针对指标执行的操作。与 value 属性搭配使用。支持的操作包括:+ - / % *
  • value:(可选)应用于按指定的 operator 计算的指标的值。

operatorvalue 属性定义对指标执行的后处理操作。例如,如果您指定指标 response_processing_latency,则指标会返回平均响应处理延迟时间,单位为毫秒。如需将单位转换为秒,请将 operator 设置为 "/",并将 value 设置为 ”1000.0“

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

如需了解详情,请参阅分析指标、维度和过滤条件参考

dimensions 用于对指标进行分组的维度数组。如需了解详情,请参阅支持的维度列表。您可以指定多个维度。
timeRange 查询的时间范围。

您可以使用以下预定义字符串来指定时间范围:

  • last60minutes
  • last24hours
  • last7days

或者,您可以将 timeRange 指定为采用 ISO 格式说明开始和结束时间戳的结构:yyyy-mm-ddThh:mm:ssZ。例如:

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}
limit 结果中可返回的最大行数。
filter 可用于过滤数据的布尔表达式。过滤器表达式可以使用 AND/OR 字词进行组合,并且应使用括号进行完全限定,以免产生歧义。如需详细了解可用于过滤的字段,请参阅分析指标、维度和过滤器参考文档。如需详细了解用于构建过滤表达式的令牌,请参阅过滤表达式语法
groupByTimeUnit 用于对结果集进行分组的时间单位。有效值包括:secondminutehourdayweekmonth

如果查询包含 groupByTimeUnit,则结果是基于指定的时间单位的聚合,并且生成的时间戳不包含毫秒级精度。如果查询省略了 groupByTimeUnit,则生成的时间戳包含毫秒级精度。

outputFormat 输出格式。有效值包括:csvjson。默认为 json(对应于以换行符分隔的 JSON)。

注意:使用 csvDelimiter 属性为 CSV 输出配置分隔符。

csvDelimiter 如果将 outputFormat 设置为 csv,则为 CSV 文件中使用的分隔符。默认为 ,(逗号)字符。支持的分隔符包括英文逗号 (,)、竖线 (|) 和制表符 (\t)。

过滤器表达式语法

本参考部分介绍可用于在请求正文中构建过滤器表达式的令牌。例如,以下表达式使用“ge”令牌(大于或等于):

"filter":"(message_count ge 0)"
令牌 说明 示例
in 添加到列表中
(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

注意:字符串必须用引号引起来。

notin 从列表中移除
(response_status_code notin 400,401,500,501)
eq 等于 (==)
(response_status_code eq 504)

(apiproxy eq 'non-prod')
ne 不等于 (!=)
(response_status_code ne 500)

(apiproxy ne 'non-prod')
gt 大于 (>)
(response_status_code gt 500)
lt 小于 (<)
(response_status_code lt 500)
ge 大于或等于 (>=)
(target_response_code ge 400)
le 小于或等于 (<=)
(target_response_code le 300)
like 如果字符串格式与提供的格式匹配,则返回 true。

右侧示例与以下示例匹配:

- 包含“buy”一词的任何值

- 以“item”结尾的任何值

- 以“Prod”开头的任何值

- 任何以 4 开头的值,注意 response_status_code 是数值

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')
not like 如果字符串格式与提供的格式匹配,则返回 false。
(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')
and 可让您使用“and”逻辑来包含多个过滤条件表达式。该过滤器包括满足所有条件的数据。
(target_response_code gt 399) and (response_status_code ge 400)
or 可让您使用“or”逻辑来评估不同的潜在过滤条件表达式。过滤器包括满足至少一个条件的数据。
(response_size ge 1000) or (response_status_code eq 500)

限制条件和默认值

下面列出了异步查询处理功能的限制条件和默认值。

限制 默认 说明
查询调用限制 请参阅说明 每小时可向 /queries Apigee API 最多发出七次调用以启动异步报告。如果超过调用配额,API 将返回 HTTP 429 响应。
有效查询限制 10 一个组织/环境最多可以有 10 个有效查询。
查询执行时间阈值 6 小时 超过 6 小时的查询将被终止。
查询时间范围 请参阅说明 查询允许的最长时间范围是 365 天。
维度和指标限制 25 您可在查询载荷中指定的维度和指标数量上限。

查询结果简介

下面是 JSON 格式的结果示例。如何查看结果取决于您用于检索查询结果的方法:

  • 如果您使用 getResulturl 方法,则可以在结果的 uri 字段中提供的网址中查看结果。此方法对查询结果没有大小限制。
  • 如果您使用 getResult 方法,结果将下载为 zip 文件。

    getResult 方法对查询结果施加 32 MB 的大小限制。如果结果超过 32 MB,则查询将返回 400 状态代码,并显示消息“查询结果大于 32 MB”。如需避免此限制,请使用检索查询结果中所述的方法 getReulturl

结果由以换行符分隔的 JSON 行组成,如以下示例所示:

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

您可以从网址中提取结果,直到代码库中数据过期为止。 请参阅限制条件和默认值

示例

示例 1:消息计数的总和

查询过去 60 分钟内消息计数的总和。

查询

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @last60minutes.json

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

来自 last60minutes.json 的请求正文

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

示例 2:自定义时间范围

使用自定义时间范围进行查询。

查询

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @custom-timerange.json

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

来自 custom-timerange.json 的请求正文

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

示例 3:每分钟事务数

在指标上查询每分钟事务数 (tpm)。

查询

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @tpm.json

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

来自 tpm.json 的请求正文

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

结果示例

从结果文件摘录:

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

示例 4:使用过滤器表达式

通过使用布尔运算符的过滤条件表达式进行查询。

查询

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @filterCombo.json

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

来自 filterCombo.json 的请求正文

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

示例 5:在指标参数中传递表达式

使用作为指标参数一部分传入的表达式进行查询。您只能使用简单的单运算符表达式。

查询

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @metricsExpression.json

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

来自 metricsExpression.json 的请求正文

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}