You need to enable JavaScript to run this app.
导航
内容分发网络
  • 文档首页
    • /内容分发网络/API 参考/数据统计接口（旧版）/获取访问统计的汇总数据
获取访问统计的汇总数据
最近更新时间：2024.04.16 14:45:14首次发布时间：2022.01.17 12:07:42
我的收藏

说明

我们全新设计了数据统计 API。推荐您使用以下新版 API：

API 说明

API 名称：DescribeEdgeNrtDataSummary。
API 域名：cdn.volcengineapi.com。
API 描述：对一个或多个域名统计指定时间段的访问请求指标的数据。
数据稳定性：受边缘节点网络波动的影响，监控数据的统计可能会发生变化。大多数情况下，监控数据的统计会在数据产生后的 12 小时内稳定下来。

指标名称指标描述筛选维度
流量表示内容分发网络响应访问请求所传输的流量。该 API 对指定时间段的总流量进行统计。支持按省份、ISP、应用层协议、网络层协议对这些指标进行筛选。

带宽

表示内容分发网络响应访问请求所产生的带宽，单位是 bps。指定时间段的带宽的统计步骤如下：

  1. 确定统计时间段。参见 DescribeCdnData 文档中的统计时间段说明。

  2. 基于指定的时间粒度，对每个统计时间段统计带宽。带宽按以下公式计算：

    • 流量 * 8 / 统计时间段的时间。时间的单位是秒。

  3. 计算这些统计时间段带宽的最大值。

参见统计示例。

请求数表示访问请求的数量。该 API 对指定时间段的访问请求总数进行统计。

QPS

表示访问请求的 QPS。指定时间段的 QPS 的统计步骤如下：

  1. 确定统计时间段。参见 DescribeCdnData 文档中的统计时间段说明。

  2. 基于指定的时间粒度，对每个统计时间段统计 QPS。QPS 按以下公式计算：

    • 请求数 / 统计时间段的时间。时间的单位是秒。

  3. 计算这些统计时间段 QPS 的最大值。

参见统计示例。

平均响应时间

表示内容分发网络响应访问请求的平均时间，单位是毫秒。单个请求的响应时间是从内容分发网络收到请求开始计算，直到内容分发网络将完整的文件发送给了用户。指定时间段的平均响应时间的统计步骤如下：

  1. 确定统计时间段。参见 DescribeCdnData 文档中的统计时间段说明。

  2. 基于指定的时间粒度，对每个统计时间段统计平均响应时间。平均响应时间按以下公式计算：

    • 所有请求的响应时间总和 / 请求数。响应时间的单位是毫秒。

  3. 基于这些统计时间段的平均响应时间，计算平均值。

参见统计示例。

说明

平均响应时间是在内容分发网络侧统计的。客户端侧的平均响应时间会受客户端与内容分发网络之间的网络质量影响。

平均下载速度

表示响应状态码是 2xx 的请求的平均下载速度，单位是 Byte/s。

基于指定的时间粒度，每个统计时间段的平均下载速度按以下方式统计：

  • 平均下载速度 = 每个请求的下载速度汇总 / 请求数量
    • 单个请求的下载速度 = 内容分发网络响应该请求的总字节数 / 内容分发网络响应该请求的时间。时间的单位是秒。

说明

平均下载速度是在内容分发网络侧统计的。客户端侧的平均下载速度会受客户端与内容分发网络之间的网络质量影响。

命中率

内容分发网络的缓存架构包含边缘层和回源层。回源层可以理解为二级缓存。边缘层靠近用户，回源层靠近源站。如果一个访问请求命中任意一个缓存层，就认为是缓存命中。命中率有以下两个指标：

  • 请求命中率：该指标的计算公式是 请求命中率 = 命中缓存的请求数 / 总请求数。该 API 对指定时间段的请求命中率进行统计。 需要留意的是，内容分发网络启用了分片文件缓存。假设一个请求命中了请求文件在缓存中的某个分片。此时，虽然内容分发网络会向源站获取其余分片，该请求依然会被认为是缓存命中。

  • 流量命中率： 该指标的计算公式是 流量命中率 =（边缘下行流量 - 回源流量）/ 边缘下行流量。边缘下行流量指的是内容分发网络边缘层向所有客户端传输的总流量。回源流量指的是源站向内容分发网络传输的总流量。指定时间段的流量命中率按以下方式进行统计：

    1. 确定统计时间段。参见 DescribeCdnData 文档中的统计时间段说明。

    2. 对每个统计时间段统计流量命中率。

    3. 计算这些统计时间段的流量命中率的平均值。

不支持对该指标进行筛选

状态码表示内容分发网络响应访问请求的状态码数量。该 API 对指定时间段的状态码总数进行统计。支持按省份、ISP、应用层协议、网络层协议和指定的状态码对该指标进行筛选。

使用限制

节流限制：您每秒最多可以发送 20 个 API 请求。

数据保留期限：系统保留最近 92 天的访问数据。您不能查询 92 天以前的访问数据。

数据时效性：访问数据的延迟约为 5 分钟。

公共参数

在调用该 API 时，您在请求中必须包含公共参数。在这些公共参数中，以下两个查询参数的取值说明如下：

参数名称数据类型必选参数说明
Actionstring是表示 API 的名称。该参数的取值是 DescribeEdgeNrtDataSummary。
Versionstring是表示 API 的版本。该参数的取值是 2021-03-01。

请求鉴权

每个请求中必须包含鉴权信息。该鉴权信息用以验证请求者的身份。参见请求鉴权。

请求正文参数

在您调用该 API 时，请求正文中可以包含的参数如下。

参数名称
数据类型
必选
参数说明
示例
StartTime
int64
否
指定一个开始时间。时间格式是 Unix 时间戳，精度是秒。StartTime 必须早于或者等于 EndTime。

您必须同时指定 StartTime 和 EndTime，或者都不指定。如果您不指定这 2 个参数，默认统计最近 24 小时的数据。

StartTime、EndTime、Interval 这三个参数决定了该 API 基于哪些时间段的数据做聚合。参见 DescribeCdnData 文档中的统计时间段说明。
1641844915
EndTime
int64
否
指定一个结束时间。时间格式是 Unix 时间戳，精度是秒。
1641845373
Metric
string
是
指定一个指标。该参数的可用值如下：
  • flux：表示访问数据的总流量，单位是 Byte。
  • bandwidth：表示访问数据的带宽峰值，单位是bps。
  • pv：表示访问的总请求数。单位是个。
  • qps：表示访问请求 QPS 峰值。单位是个/秒。
  • response_time：表示访问请求的平均响应时间。单位是毫秒。如果该参数值是 0，则表示没有相应的指标数据。
  • avg_speed：表示响应状态码是 2xx 的请求的平均下载速度。
  • hitrate：表示平均流量命中率。单位是%。参数值保留 4 位小数。
  • pvhitrate：表示平均请求命中率。单位是%。参数值保留 4 位小数。
  • status_all：表示所有边缘节点响应状态码的数量以及各状态码组中状态码的数量。每个状态码组包含同一数字开头的状态码。
  • status_2xx：表示数字 2 开头的每个状态码的数量。
  • status_3xx：表示数字 3 开头的每个状态码的数量。
  • status_4xx：表示数字 4 开头的每个状态码的数量。
  • status_5xx：表示数字 5 开头的每个状态码的数量。
flux
Domain
string
否
指定一个或多个加速域名。最多可指定 50 个加速域名。多域名场景下可使用 Aggregate 参数进行聚合统计或分域名统计。

多个加速域名使用逗号（,）分隔。逗号后面不能加空格。

如果不指定该参数，则包含账号下的所有域名。

子账号调用说明：
如果是子账号调用该 API，需要注意以下几点：
  • 子账号指定了 Domain 参数。但是在指定的加速域名中存在该子账号无权限访问的域名。此时 API 调用会失败并且报您没有权限执行该操作错误。
  • 子账号未指定 Domain 参数。此时则包含该子账号有权限访问的所有域名。
关于更多子账号权限信息，参考权限管理概述。
www.example.com
Interval
string
否
指定一个时间粒度。基于这个粒度，对访问数据进行汇总统计。

StartTime、EndTime、Interval 这三个参数决定了该 API 基于哪些时间段的数据做聚合。参见 DescribeCdnData 文档中的统计时间段说明。

该参数的可用值如下：
  • 1min：表示以 1 分钟为时间粒度。
  • 5min：表示以 5 分钟为时间粒度。
您可以指定的时间粒度与StartTime 和 EndTime 指定的时间范围的关系如下：
  • 如果时间范围 <= 1 天，您可以指定的时间粒度有 1min、5min。
  • 如果时间范围 <= 92 天，您可以指定的时间粒度是 5min。
该参数的默认值是 5min。
1min
Area
string
否
指定一个区域，统计 IP 归属地为这些区域的访问数据汇总。该参数的可用值如下：
  • China：表示中国区域。
  • Global：表示全球区域。
在统计非中国区数据时，如果指定了 Global 和 Region，则不能使用 Isp 对数据进行筛选。

如果不指定该参数，表示仅通过 Region 筛选。具体参见 Region 参数。

您不能使用该参数筛选命中率相关指标。
China
Region
string
否
指定一个国家、地区和中国省份的代码，统计 IP 归属地为该区域的访问数据汇总。国家，地区和省份代码可通过调用 DescribeCdnRegionAndIsp 获取。

如果 Metric 是 flux 或者 bandwidth，您可以指定最多 5 个，以逗号（,）分隔的国家、地区和中国省份代码。如果您指定了多个国家、地区和中国省份，会存在以下限制：
  • 您不能指定 Isp 参数。
  • 您不能指定 Domain 参数或在 Domain 参数中最多只能指定一个域名。
如果您指定了 Area 参数，有以下几种情况：
  • 当 Area = China 时，Region 参数有以下几种情况：
    • 如果指定 Region 参数，Region 参数只能是中国的省份。表示仅统计该省份的数据。
    • 如果不指定 Region 参数，表示统计的是中国所有省份的汇总数据。
  • 当 Area = Global 时，有以下几种情况：
    • 如果指定 Region 参数，Region 参数可以是某个国家，地区或者中国的某个省份。表示统计该国家，该地区或者该中国省份的数据。例如，当 Region = CHN 时，统计的是中国所有省份的汇总数据。
    • 如果不指定 Region 参数，表示统计的是所有国家和地区的汇总数据。
当不指定 Area 参数时，有以下几种情况：
  • 如果不指定 Region 参数，表示统计的是所有国家和地区的汇总数据。
  • 如果 Region = CHN，表示统计的是中国所有省份的汇总数据。
  • 如果 Region 参数是其他某个国家，地区或者中国的某个省份，表示统计该国家，该地区或者该中国省份的数据。
您不能使用该参数筛选命中率相关指标，当BillingRegion不为CHN时该参数无效。
BJ
Isp
string
否
指定一个的 ISP 的代码，统计使用该 ISP 线路的访问数据汇总。ISP 代码可通过调用 DescribeCdnRegionAndIsp 获取。如果不指定该参数，表示包含所有 ISP。

如果 Metric 是 flux 或者 bandwidth，您可以指定最多 5 个，以逗号（,）分隔的 ISP 代码。如果您指定了多个 ISP 代码，会存在以下限制：
  • 您不能指定 Region 参数。
  • 您不能指定 Domain 参数或在 Domain 参数中最多只能指定一个域名。
您不能使用该参数筛选命中率相关指标，当BillingRegion不为CHN时该参数无效。
CT
BillingRegion
string
否
指定一个计费区域，统计指定计费区域的访问数据，计费区域是节点的 IP 归属的区域。默认的计费区域是中国内地。您可以提交工单启用 中国内地 以外的计费区域。该参数的可用值如下：
  • CHN：表示中国内地。
  • EU：表示欧洲区。
  • NA：表示北美区。
  • SA：表示南美区。
  • ME：表示中东区和非洲区。该参数值在未来会被弃用。请使用 MEA 代替。
  • MEA：表示中东区和非洲区。
  • AP1：表示亚太一区。
  • AP2：表示亚太二区。
  • AP3：表示亚太三区。
  • All：表示对每个计费区域分别统计访问数据。
不指定该参数时，统计的是所有计费区域的汇总数据。
CHN
Protocol
string
否
指定请求的一个应用层协议。该参数的可用值如下：
  • http：表示 HTTP 协议。
  • https：表示 HTTPS 协议。
  • quic：表示 QUIC 协议。
如果不指定该参数，表示包含所有支持的应用层协议。

您不能使用该参数筛选命中率相关指标。
http
IpVersion
string
否
指定请求的一个网络层协议。该参数的可用值如下：
  • ipv4：表示 IPv4 访客的请求。
  • ipv6：表示 IPv6 访客的请求。
如果不指定该参数，表示包含所有支持的网络层协议。

您不能使用该参数筛选命中率相关指标。
ipv6
Aggregate
string
否
指定是否汇总所有加速域名的指标。该参数适用于指定多个多加速域名进行统计的场景。该参数的可用值如下：
  • aggregate：汇总所有加速域名的指标。
  • disaggregate：不汇总加速域名的指标。
如果不指定 Domain 参数，表示对账号下所有加速域名进行汇总统计。此时系统强制设置 Aggregate 参数值为 aggregate。API 返回账号下所有域名的汇总指标。

如果指定 Domain 参数。此时：
  • 如果不指定 Aggregate 参数，Aggregate 参数的默认值是 disaggregate。
  • 如果设置 Aggregate 参数值为 disaggregate，API 仅返回每个指定域名的汇总指标。
  • 如果设置 Aggregate 参数值为 aggregate，API 仅返回所有指定域名的汇总指标。

统计示例

我们以带宽为例，展示 5 分钟粒度的带宽统计步骤。

假设您指定的时间段是 3:03:00 - 3:12:00，指定的时间粒度是 5 分钟。此时，该时间段的带宽统计步骤如下：

  1. 确定统计时间段。基于时间粒度，该 API 将指定的时间段划分成 3 个统计时间段，分别为：[3:00:00 - 3:05:00)、[3:05:00 - 3:10:00)、[3:10:00 - 3:15:00)。

  2. 对每个统计时间段统计带宽。带宽的计算公式是：流量 * 8 / 300。在内容分发网络统计这三个时间段的带宽后，我们假设带宽分别为 12、10、75。

  3. 对这 3 个统计时间段的带宽计算最大值。最后结果：您的指定时间段 3:03:00 - 3:12:00 的带宽是 75 bps。

响应正文

参数名称
数据类型
参数说明
示例
Resources
ResourceSummary[]

示例

请求示例

POST https://cdn.volcengineapi.com?Version=2021-03-01&Action=DescribeEdgeNrtDataSummary<其他公共请求参数>
{
    "StartTime": 1641263400,
    "EndTime": 1641265200,
    "Metric": "flux",
    "Domain":"www.example.com,www.example2.com"
}

响应示例

{
    "ResponseMetadata": {
        "RequestId": "202201051728010102121980160300003E",
        "Action": "DescribeEdgeNrtDataSummary",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-1"
    },
    "Result": {
        "Resources": [
            {
                "Metrics": [
                    {
                        "Metric": "Flux",
                        "Value": 330
                    }
                ],
                "Name": "`www.example.com`"
            },
            {
                "Metrics": [
                    {
                        "Metric": "Flux",
                        "Value": 101448.6
                    }
                ],
                "Name": "`www.example2.com`"
            }
        ]
    }
}

错误代码

如果响应正文包含 Error 字段，则表示 API 请求失败。关于更多错误码的信息，参见错误码。