API 说明
基于火山引擎内容分发网络(CDN)收到的用户请求,该 API 对一个指标统计其汇总数据。
要调用该 API,您需要指定一个指标,一个统计时间段和一个时间粒度。您还可以指定多个过滤条件(包括计费区域)对用户请求进行过滤。您最多能查询过去 92 天的数据。
数据稳定性:受网络波动影响,边缘节点上统计的指标数据可能会发生变化。大多数情况下,指标数据会在 12 小时内逐步稳定下来。因此,该 API 返回的指标数据并非账单中显示的用量,仅供参考。实际用量请以账单为准。
数据时效性:指标数据可能会有 5 分钟左右的延时。
说明
如果您是刚开始使用数据统计的 API,请务必先阅读以下文档,这将有助于您理解该 API 文档。
使用限制
节流限制:您每秒最多可以提交 20 个 API 请求。
请求说明
- 请求方式:POST
- 请求地址:https://cdn.volcengineapi.com/?Action=DescribeEdgeSummary&Version=2021-03-01
请求参数
Query
参数名称 | 数据类型 | 是否必选 | 参数说明 |
|---|
Action | String | 是 | 接口名称。当前 API 的名称为 DescribeEdgeSummary。 |
Version | String | 是 | 接口版本。当前 API 的版本为 2021-03-01。 |
Body
参数名称 | 数据类型 | 是否必选 | 参数说明 | 示例 |
|---|
Metric | String | 是 | 表示一个指标。该参数有以下取值:
traffic:表示 CDN 向用户传输的数据量,单位是 bytes。
bandwidth:表示基于 CDN 向用户传输的数据量而计算的带宽峰值,单位是 bps。
requests:表示 CDN 收到的用户请求数量。
qps:表示 CDN 收到的用户请求的 QPS 峰值。
traffic_hitrate:表示 CDN 的流量命中率,以数值形式显示。例如,0.9999 表示 99.99%。
response_time:表示 CDN 响应用户请求所耗费的平均时间,单位是毫秒(ms)。
avg_speed:表示 CDN 响应用户请求时的平均数据传输速度,单位是 Bps。该指标的数据是对响应状态码是 2xx 的用户请求统计的。
transfer_speed:表示 CDN 响应用户请求时的平均数据传输速度,单位是 Bps。该指标的数据是对所有用户请求统计的。
status_all:在 CDN 对用户请求的响应中,该参数表示以下类别的状态码数量:
- 所有状态码的数量。
- 2xx 状态码的数量。
- 3xx 状态码的数量。
- 4xx 状态码的数量。
- 5xx 状态码的数量。
- 每个状态码的数量。
status_2xx:表示 2xx 状态码的数量以及该类别下每个状态码的数量。
status_3xx:表示 3xx 状态码的数量以及该类别下每个状态码的数量。
status_4xx:表示 4xx 状态码的数量以及该类别下每个状态码的数量。
status_5xx:表示 5xx 状态码的数量以及该类别下每个状态码的数量。
关于每个指标的详情以及统计方式,参见 指标的定义以及统计方式。 | traffic
|
StartTime | Long | 是 | 表示统计时间段的开始时间,格式是 Unix 时间戳,精度是秒。StartTime 必须早于或者等于 EndTime。同时,StartTime 与 EndTime 所表示的统计时间段不能超过 31 天。 | 1710259200
|
EndTime | Long | 是 | 表示统计时间段的结束时间,格式是 Unix 时间戳,精度是秒。 | 1710836303
|
Interval | String | 否 | 表示一个时间粒度。该 API 基于 Interval 将 StartTime 和 EndTime 所表示的统计时间段拆分成一系列的时间区间,然后对每个时间区间统计 Metric 数据。
关于 Interval 参数是如何用来拆分统计时间段,参考 统计时间段说明。
该参数有以下取值:
1min:表示时间粒度是 1 分钟。
5min:表示时间粒度是 5 分钟。
hour:表示时间粒度是 1 小时。
day:表示时间粒度是 1 天。
您可以指定的时间粒度受 StartTime 和 EndTime 所表示的时间范围的影响。
- 如果时间范围 <= 1 天,您可以指定的时间粒度有
1min、5min、hour。
- 如果 1 天 < 时间范围 <= 3 天,您可以指定的时间粒度有
5min、hour、day。
- 如果 3 天 < 时间范围 <= 31 天,您可以指定的时间粒度有
hour、day。
该参数的默认值是 5min。如果默认值不匹配时间范围,API 请求会失败。 | 5min
|
Project | String | 否 | 表示一个项目。
- 如果您指定了
Domain,该 API 对所有您指定的加速域名统计 Metric 数据。
- 如果您指定了
Project ,但未指定 Domain,该 API 对您指定的项目统计 Metric 数据。参见 项目数据是如何统计的。
- 如果您既未指定
Project ,也未指定 Domain,该 API 对所有加速域名统计 Metric 数据。
| my_project
|
Domain | String | 否 | 表示一个或多个加速域名,用于对用户请求进行过滤。该 API 对您指定的每个加速域名统计 Metric 数据。您最多可以指定 50 个加速域名。多个加速域名之间使用逗号(,)分隔。如果不指定 Domain,表示不使用该参数对请求进行过滤。
如果您指定了 Project,您指定的加速域名必须是属于该 Project 的。
说明
当子用户调用该 API 时,请留意以下说明:
- 子用户只能指定其有权限访问的加速域名。子用户可以调用 ListCdnDomains 获取其有权限访问的加速域名。
- 如果不指定该参数,表示所有该子用户有权限访问的那些加速域名。
| www.example.com,www.test.com,img.example.com
|
BillingRegion | String | 否 | 表示一个或多个计费区域,用于对用户请求进行过滤。该 API 对来自这些计费区域的用户请求统计 Metric 数据。多个计费区域之间使用逗号(,)分隔。该参数有以下取值:
CHN:表示中国内地。
EU:表示欧洲区。
NA:表示北美区。
SA:表示南美区。
MEA:表示中东区和非洲区。
AP1:表示亚太一区。
AP2:表示亚太二区。
AP3:表示亚太三区。
如果不指定 BillingRegion,表示不使用该参数对请求进行过滤。 | CHN,EU
|
项目数据是如何统计的
在对一个项目统计指标数据时,CDN 统计的是项目内加速域名的数据。
- 如果统计时间段内有一个加速域名转出该项目,该项目的指标数据不会包含转出后该加速域名的数据。
- 如果统计时间段内有一个加速域名转入该项目,该项目的指标数据会包含转入后该加速域名的数据。
示例
考虑以下场景:
- 您指定的统计时间段是某天的 8:00-10:00。
- 加速域名X 在 9:00 从另一个项目转移到项目A。加速域名Y 一直在项目A 中。
在这个场景中,如果您对项目A 统计指标数据,则指标数据涵盖:
- 加速域名X 在 9:00 至 10:00 之间的指标数据。
- 加速域名Y 在 8:00 至 10:00 之间的指标数据。
返回参数
参数名称 | 数据类型 | 参数说明 | 示例 |
|---|
| Object[] | 表示该 API 返回的结果数据。 |
|
请求示例
POST https://cdn.volcengineapi.com/?Action=DescribeEdgeSummary&Version=2021-03-01
{
"Domain": "www.example.com,www.test.com,img.example.com",
"StartTime": 1710259200,
"EndTime": 1710835599,
"Interval": "5min",
"Metric": "bandwidth",
"Project": "my_project",
"BillingRegion": "CHN,EU"
}
返回示例
{
"ResponseMetadata": {
"RequestId": "2024031920490843CBB23C0BC82C021B5E",
"Action": "DescribeEdgeSummary",
"Version": "2021-03-01",
"Service": "CDN",
"Region": "cn-north-1"
},
"Result": {
"MetricDataList": [
{
"Metric": "bandwidth",
"Value": 8312
}
]
}
}
错误码
如果响应正文的 ResponseMetadata 字段中包含 Error 字段,则表示 API 请求失败。更多关于错误码的信息,参见错误码。