本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
Apigee 会记录跨 API 的多种运营和业务数据。根据此类数据得出的指标对于运营监控和业务监控非常有用。例如，借助 Apigee Analytics，您可以确定哪些 API 的表现良好或不佳、哪些开发者的流量贡献最大，以及哪些应用给您的后端服务带来了大多数问题。
为了便于轻松访问此指标数据，请在需要自动执行某些分析函数（例如使用自动化客户端或脚本定期检索指标）时使用 Metrics API。您还可以使用 API 以自定义微件的形式构建自己的可视化图表，并将其嵌入门户或自定义应用中。
如需了解如何在 Apigee 界面中使用 Analytics，请参阅 Apigee Analytics 概览。
Metrics API 简介
可通过两种方式使用 Metrics API：
- 获取一段时间内（例如一小时、一天或一周）组织和环境的指标。此方法会返回整个组织和环境的原始指标。
例如，您可以获取上一周的下列数据：
- 政策错误的数量
- 平均响应时间
- 总流量
获取一段时间内组织和环境的相关指标（按维度整理）。
例如，您在上周可以使用维度按 API 产品、API 代理和开发者电子邮件地址（也可以是 AppGroup ID）对指标进行分组，以获取：
- 每个 API 产品的政策错误数量
- 每个 API 代理的平均响应时间
- 每个开发者电子邮件的总流量
为了管理返回的结果，Metrics API 支持以下功能：
如需了解详情，请参阅 Metrics API 参考文档。
Metrics API 使用入门
Metrics API 的请求网址如下：
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]
例如，要获取按 API 代理分组的指标，请使用以下网址调用 Apigee API：
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00
省略该维度即可返回指定时间段内整个组织和环境的原始指标：
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00
指定要返回的指标
使用
select查询参数指定要检索的指标和可选的聚合函数，格式为：?select=metric
或者：
?select=aggFunction(metric)
其中：
- metric 指定要返回的数据。例如，API 请求数、缓存命中数或政策错误数。如需了解列明了与
select查询参数搭配使用的指标名称表，请参阅指标。 aggFunction 指定针对指标运行的可选聚合函数。例如，您可以将以下聚合函数与处理延迟时间指标结合使用：
avg：返回平均处理延迟时间。min：返回最小处理延迟时间。max：返回最大处理延迟时间。sum：返回所有处理延迟时间的总和。-
p50：返回处理延迟时间的第 50 百分位。 -
p95：返回处理延迟时间的第 95 百分位。 -
p99：返回处理延迟时间的第 99 百分位。
并非所有指标都支持所有聚合函数。指标中的文档包含一个列明了指标名称和指标所支持函数（
sum、avg、min、max）的表。
例如，要返回每秒平均事务数（即 API 代理请求数），请运行以下命令：
?select=tps
请注意，此示例不需要聚合函数。下一个示例使用聚合函数返回缓存命中的总和：
?select=sum(cache_hit)
您可以为单个 API 调用返回多个指标。如需获取政策错误数总和指标和平均请求大小指标，请使用以逗号分隔的指标列表设置
select查询参数：?select=sum(policy_error),avg(request_size)
指定时间段
Metrics API 可以返回指定时间段的数据。使用
timeRange（最长 6 个月）查询参数指定时间段，格式如下：?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
请注意
HH:MM之前的%20。timeRange参数要求在HH:MM之前使用采用网址编码的空格字符或+字符，例如MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM。例如：
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
请勿使用 24:00 作为时间，因为该时间会绕至 00:00。请改用 23:59。
如何调用 Metrics API 的示例
本部分提供了如何使用 Metrics API 的示例。如需查看其他示例，请参阅 Metrics API 示例。
返回一个月内调用 API 的总次数
如需返回一个月内针对您组织中的所有 API 进行的总调用次数，请使用如下所示的调用：
curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
按照获取 OAuth 2.0 访问令牌中的说明，将
$TOKEN设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的curl选项，请参阅使用 curl。如需了解所使用的环境变量，请参阅为 Apigee API 请求设置环境变量。以下提供了一个响应示例：
{ "environments": [ { "metrics": [ { "name": "sum(message_count)", "values": [ "7.44944088E8" ] } ], "name": "prod" } ], ... }返回每个 API 代理在两天内收到的消息总数
在此示例中，您返回了所有 API 代理在两天内收到的请求数量的指标。
select查询参数在维度apiproxy中为指标message_count定义了聚合函数sum。报告会返回世界协调时间 (UTC) 2018 年 6 月 20 日到 2018 年 6 月 21 日期间所有 API 针对所接收流量的请求消息吞吐量：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
按照获取 OAuth 2.0 访问令牌中的说明，将
$TOKEN设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的curl选项，请参阅使用 curl。如需了解所使用的环境变量，请参阅为 Apigee API 请求设置环境变量。以下提供了一个响应示例：
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(message_count)", "values" : [ { "timestamp" : 1498003200000, "value" : "1100.0" } ] } ], "name" : "target-reroute" } ], "name" : "test" } ]... }此响应表明，在 2018 年 6 月 20 日至 2018 年 6 月 21 日期间，在测试环境中运行且名为“target-reroute”的 API 代理接收了 1100 条消息。
要获取其他维度的指标，请指定不同的维度作为 URI 参数。例如，您可以指定
developer_app维度来检索开发者应用的指标。以下 API 调用会返回指定时间段内来自任何应用的总吞吐量（接收到的消息）：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \ -H "Authorization: Bearer $TOKEN"
以下提供了一个响应示例：
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "886.0" } ] } ], "name": "Test-App" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "6645.0" } ] } ], "name": "johndoe_app" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "1109.0" } ] } ], "name": "marys_app" } ]... }按相对排名对结果进行排序
很多时候，您获取指标时只希望获得一部分数据集的结果。通常情况下，您需要获取“前 10 名”结果，例如“前 10 个最慢的 API”“前 10 个最活跃的应用”。为此，您可以使用
topk查询参数作为请求的一部分。例如，您可能想知道谁是顶级开发者（通过吞吐量来衡量），或者性能最差（即“最慢”）的目标 API 是什么（通过延迟时间衡量）。
topk（表示“top k”实体）用于报告与给定指标的最高值关联的实体。这允许您为说明特定条件的实体列表过滤涉指标。例如，要查找上周哪个目标网址出错最多，请将
topk参数附加到该请求中，并将其值设置为1：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \ -H "Authorization: Bearer $TOKEN"
按照获取 OAuth 2.0 访问令牌中的说明，将
$TOKEN设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的curl选项，请参阅使用 curl。如需了解所使用的环境变量，请参阅为 Apigee API 请求设置环境变量。以下提供了一个响应示例：
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(is_error)", "values": [ { "timestamp": 1494201600000, "value": "12077.0" } ] } ], "name": "http://api.company.com" } ]... }此请求的结果是一组指标，这组指标显示出错最多的目标网址为
http://api.company.com。您还可以使用
topk参数对经历最高吞吐量的 API 进行排序。以下示例检索了排名最靠前的 API 的指标，该指标由上周的最高吞吐量定义：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \ -H "Authorization: Bearer $TOKEN"
以下提供了一个响应示例：
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1494720000000, "value": "5750.0" }, { "timestamp": 1494633600000, "value": "5752.0" }, { "timestamp": 1494547200000, "value": "5747.0" }, { "timestamp": 1494460800000, "value": "5751.0" }, { "timestamp": 1494374400000, "value": "5753.0" }, { "timestamp": 1494288000000, "value": "5751.0" }, { "timestamp": 1494201600000, "value": "5752.0" } ] } ], "name": "testCache" } ], "name": "test" } ]... }过滤结果
如需查看更细化的数据，您可以过滤结果以限制返回的数据。使用过滤条件时，必须使用维度作为过滤条件属性。
例如，假设您需要从后端服务（通过请求的 HTTP 动词过滤）中检索错误计数。您的目标是了解每个后端服务有多少 POST 和 PUT 请求生成了错误。为此，您可以使用维度
target_url和过滤条件request_verb：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \ -H "Authorization: Bearer $TOKEN"
按照获取 OAuth 2.0 访问令牌中的说明，将
$TOKEN设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的curl选项，请参阅使用 curl。如需了解所使用的环境变量，请参阅为 Apigee API 请求设置环境变量。以下提供了一个响应示例：
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(is_error)", "values" : [ { "timestamp" : 1519516800000, "value" : "1.0" } ] } ], "name" : "testCache" } ], "name" : "test" } ]... }分页结果
在生产环境中，发送给 Apigee Analytics API 的某些请求会返回非常大的数据集。为了便于在基于界面的应用上下文中显示大型数据集，API 本身便支持分页功能。
如需对结果进行分页，请使用
offset和limit查询参数以及sortby排序参数，以确保项排序的一致性。例如，以下请求可能会返回大型数据集，因为它检索了上周所有 API 在产品环境中出现的所有错误的指标。
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \ -H "Authorization: Bearer $TOKEN"
按照获取 OAuth 2.0 访问令牌中的说明，将
$TOKEN设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的curl选项，请参阅使用 curl。如需了解所使用的环境变量，请参阅为 Apigee API 请求设置环境变量。如果基于界面的应用可以在每个页面上合理地显示 50 个结果，那么您可以将限制设置为 50。由于 0 计为第一项，因此以下调用会按降序返回 0-49 项（默认值为
sort=DESC）。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \ -H "Authorization: Bearer $TOKEN"
对于结果的第二“页”，请使用偏移量查询参数，如下所示。请注意，限制和偏移量是相同的。因为 0 计为第一项。限值为 50 且偏移量为 0 时，会返回 0-49 项。偏移量为 50 时，会返回 50-99 项。
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \ -H "Authorization: Bearer $TOKEN"