您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
Edge Analytics 提供一组丰富的交互式信息中心、自定义报告生成器和相关功能。但是,这些功能旨在提供互动性:您可提交 API 或界面请求,然后请求会被阻止,直到分析服务器提供响应。
但是,如果完成分析请求所需的时间过长,则请求超时。如果查询请求需要处理大量数据(例如,数百 GB),可能会因超时而失败。
通过异步查询处理,您可以查询非常大的数据集,并在以后检索结果。如果您发现互动查询超时,可以考虑使用离线查询。适合使用异步查询处理的情况包括:
- 分析和生成跨越很长时间间隔的报告。
- 使用各种分组维度以及增加查询复杂性的其他限制条件来分析数据
- 在发现某些用户或组织的数据量大幅增加时管理查询。
本文档介绍了如何使用 API 启动异步查询。您也可以按照运行自定义报告中的说明使用界面。
将 Reports API 与界面进行比较
创建和管理自定义报告介绍了如何使用 Edge 界面创建和运行自定义报告。您可以同步或异步运行此类报告。
使用界面生成自定义报告的大部分概念都适用于使用 API。也就是说,使用 API 创建自定义报告时,您可以指定 Edge 中内置的metrics、维度和过滤条件,以及使用 StatisticsCollector 政策创建的任何自定义指标。
在界面和 API 中生成的报告之间的主要区别在于,使用 API 生成的报告会写入 CSV 或 JSON(以换行符分隔)文件,而不是在界面中显示的直观报告。
Apigee Hybrid 中的限制
Apigee Hybrid 对结果数据集设置了 30 MB 大小限制。
如何创建异步分析查询
您可以利用三个步骤创建异步分析查询:
第 1 步:提交查询
您必须向 /queries API 发送 POST 请求。此 API 会指示 Edge 在后台处理您的请求。如果查询提交成功,该 API 会返回 201 状态和 ID,您将在后续步骤中引用该查询。
例如:
curl -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file -u orgAdminEmail:password
请求的正文是查询的 JSON 说明。在 JSON 正文中,指定用于定义报告的metrics、维度和过滤器。
下面展示了一个 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 以外,enqueued
的 state
也表示请求成功。
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 步:获取查询状态
进行 GET 调用以请求查询的状态。您需提供 POST 调用返回的查询 ID。例如:
curl -X GET -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd -u email:password
响应示例:
如果查询仍在进行中,您会收到如下响应,其中 state
为 running
:
{
"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
后,您可以使用 get results API 检索结果,其中查询 ID 仍然是 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
。
curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result -u email:password
如需检索下载的文件,您需要配置所使用的工具,以便将下载的文件保存到您的系统。例如:
如果您使用 cURL,则可以使用
-O -J
选项,如上所示。如果您使用 Postman,则需要选择保存并下载按钮。在这种情况下,系统会下载一个名为
response
的 ZIP 文件。如果您使用的是 Chrome 浏览器,系统会自动接受下载。
如果请求成功,并且存在非零结果集,则结果将作为压缩的 JSON(以换行符分隔)文件下载到客户端。已下载文件的名称将是:
OfflineQueryResult-<query-id>.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_dispaly_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
|
指标数组。您可以为每个指标包括的一个查询指定一个或多个指标。只有指标名称是必填的:
"metrics":[ { "name":"response_processing_latency", "function":"avg", "alias":"average_response_time_in_seconds", "operator":"/", "value":"1000" } ] 如需了解详情,请参阅分析指标、维度和过滤条件参考。 |
无 |
dimensions
|
用于对指标进行分组的维度数组。如需了解详情,请参阅支持的维度列表。您可以指定多个维度。 | 否 |
timeRange
|
查询的时间范围。
您可以使用下列预定义字符串来指定时间范围:
或者,您可以将 "timeRange": { "start": "2018-07-29T00:13:00Z", "end": "2018-08-01T00:18:00Z" } |
是 |
limit
|
结果中可返回的最大行数。 | 无 |
filter
|
可用于过滤数据的布尔表达式。过滤器表达式可以使用 AND/OR 字词进行组合,并且应使用括号进行完全限定,以免产生歧义。如需详细了解可用于过滤的字段,请参阅分析指标、维度和过滤器参考文档。如需详细了解用于构建过滤器表达式的令牌,请参阅过滤器表达式语法。 | 无 |
groupByTimeUnit
|
用于对结果集进行分组的时间单位。有效值包括:second 、minute 、hour 、day 、week 或 month 。
如果查询包含 |
无 |
outputFormat
|
输出格式。有效值包括:csv 或 json 。默认为 json (对应于以换行符分隔的 JSON)。注意:使用 |
否 |
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 Management API 以启动异步报告。如果超过调用配额,API 将返回 HTTP 429 响应。 |
有效查询限制 | 10 | 一个组织/环境最多可以有 10 个有效查询。 |
查询执行时间阈值 | 6 小时 | 超过 6 小时的查询将被终止。 |
查询时间范围 | 请参阅说明 | 查询允许的最长时间范围是 365 天。 |
维度和指标限制 | 25 | 您可在查询载荷中指定的维度和指标数量上限。 |
查询结果简介
下面是 JSON 格式的结果示例。输出包括由换行分隔符分隔的 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 -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @last60minutes.json -u orgAdminEmail:password
来自 last60minutes.json 的请求正文
{
"metrics":[
{
"name":"message_count",
"function":"sum"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":"last60minutes"
}
示例 2:自定义时间范围
使用自定义时间范围进行查询。
查询
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries" -d @last60minutes.json -u orgAdminEmail:password
来自 last60minutes.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 -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @tpm.json -u orgAdminEmail:password
来自 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 -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @filterCombo.json -u orgAdminEmail:password
来自 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 -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @metricsExpression.json -u orgAdminEmail:password
来自 metricsExpression.json 的请求正文
{
"metrics":[
{
"name":"message_count",
"function":"sum",
"operator":"/",
"value":"7"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":10,
"timeRange":"last60minutes"
}
如何生成异步获利报告查询
您可以按照本部分所述的步骤,针对一组特定条件捕获给定时间内的所有成功获利交易。
如同异步分析查询,您可以利用三个步骤创建异步获利报告查询:(1) 提交查询,(2) 获取查询状态,(3) 检索查询结果。
第 1 步提交查询如下所述。
第 2 步和第 3 步与异步分析查询完全相同。如需了解详情,请参阅如何创建异步分析查询。
如需提交针对异步获利报告的查询,请向 /mint/organizations/org_id/async-reports
发出 POST 请求。
(可选)您可以通过传递 environment
查询参数来指定环境。如果未指定,则查询参数默认为 prod
。例如:
/mint/organizations/org_id/async-reports?environment=prod
在请求正文中指定以下搜索条件。
名称 | 说明 | 默认 | 是否必需? |
appCriteria |
要包含在报告中的特定应用的 ID 和组织。如果未指定此属性,则会将所有应用纳入报告中。 | 不适用 | 否 |
billingMonth |
报告的结算月份,例如 JULY。 | 无 | 是 |
billingYear |
报告的结算年份,例如 2015。 | 不适用 | 是 |
currencyOption |
报告所用的货币。有效值包括:
如果选择欧元、英镑或美元,报告会根据交易日期的有效汇率显示采用同一个货币的所有交易。 |
不适用 | 否 |
devCriteria
|
要包含在报告中的特定开发者的开发者 ID 或电子邮件地址以及组织名称。如果未指定此属性,则会将所有开发者纳入报告中。 例如: "devCriteria":[{ "id":"RtHAeZ6LtkSbEH56", "orgId":"my_org"} ] |
无 | 否 |
fromDate
|
报告的开始日期,以世界协调时间 (UTC) 表示。 | 无 | 有 |
monetizationPakageIds |
要纳入报告的一个或多个 API 软件包的 ID。如果未指定此属性,则报告会包含所有 API 软件包。 | 不适用 | 否 |
productIds
|
要包含在报告中的一个或多个 API 产品的 ID。如果未指定此属性,则报告会包含所有 API 产品。 | 无 | 否 |
ratePlanLevels |
报告中要包含的价格方案的类型。有效值包括:
如果未指定此属性,则报告会包含特定于开发者的价格方案和标准价格方案。 |
不适用 | 否 |
toDate
|
报告的结束日期,以世界协调时间 (UTC) 表示。 | 不适用 | 是 |
例如,以下请求会针对指定的 API 产品和开发者 ID 生成 2017 年 6 月的异步获利报告。报告 fromDate
和 toDate
日期和时间是世界协调时间 (UTC)/格林尼治标准时间,可以包含时间。
curl -H "Content-Type:application/json" -X POST -d \ '{ "fromDate":"2017-06-01 00:00:00", "toDate":"2017-06-30 00:00:00", "productIds": [ "a_product" ], "devCriteria": [{ "id": "AbstTzpnZZMEDwjc", "orgId": "myorg" }] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \ -u orgAdminEmail:password