使用异步自定义报告 API

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

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

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

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

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

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

将 Reports API 与界面进行比较

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

使用界面生成自定义报告的大部分概念都适用于使用 API。也就是说，使用 API 创建自定义报告时，可以指定 Edge 中内置的指标、维度和过滤器，以及您使用 StatisticsCollector 政策创建的任何自定义指标。

在界面和 API 中生成的报告之间的主要区别在于，使用 API 生成的报告会写入 CSV 或 JSON（以换行符分隔）文件，而不是在界面中显示的直观报告。

Apigee Hybrid 中的限制

Apigee Hybrid 对结果数据集设置了 30 MB 大小限制。

如何创建异步分析查询

您可以利用三个步骤创建异步分析查询：

1. 提交查询。

2. 获取查询状态。

3. 检索查询结果。

第 1 步：提交查询

您必须向 /queries API 发送 POST 请求。此 API 会告知 Edge 在后台处理您的请求。如果查询成功提交，API 将返回 201 状态和一个 ID，您将在后续步骤中使用此 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 正文中，指定用于定义报告的指标、维度和过滤器。

下面展示了一个 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":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

过滤器表达式语法

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

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

限制条件和默认值

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

查询结果简介

下面是 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

在请求正文中指定以下搜索条件。

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

例如，以下请求会针对指定的 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