You need to enable JavaScript to run this app.
导航

获取访问统计的细分数据

最近更新时间2024.01.31 10:43:30

首次发布时间2021.07.15 11:09:03

API 说明

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

指标名称指标描述筛选维度

流量

表示内容分发网络响应访问请求所传输的流量。该 API 对每个统计时间段的流量进行统计。

支持按省份、ISP、应用层协议、网络层协议对这些指标进行筛选。

带宽

表示内容分发网络响应访问请求所产生的带宽,单位是 bps。

  • 如果指定的时间粒度是 1 分钟或 5 分钟,每个统计时间段的带宽按以下方式统计:

    • 流量 * 8 / 统计时间段的时间时间的单位是秒。
  • 如果指定的时间粒度是 1 小时或 1 天,每个统计时间段的带宽按以下方式统计:

    • 先以 5 分钟粒度统计一系列带宽数据,然后计算这些数据的最大值。

    参见统计示例

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

QPS

表示访问请求的 QPS。

  • 如果指定的时间粒度是 1 分钟或 5 分钟,每个统计时间段的 QPS 按以下方式统计:

    • 请求数 / 统计时间段的时间时间的单位是秒。
  • 如果指定的时间粒度是 1 小时或 1 天,每个统计时间段的 QPS 按以下方式统计:

    • 先以 5 分钟粒度统计一系列 QPS 数据,然后计算这些数据的最大值。

    参见统计示例

平均响应时间

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

  • 如果指定的时间粒度是 1 分钟或 5 分钟,每个统计时间段的平均响应时间按以下方式统计:

    • 所有请求的响应时间总和 / 请求数响应时间的单位是毫秒。
  • 如果指定的时间粒度是 1 小时或 1 天,每个统计时间段的平均响应时间按以下方式统计:

    • 先以 5 分钟粒度统计一系列平均响应时间的数据,然后计算这些数据的平均值。

    参见统计示例

说明

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

平均下载速度

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

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

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

说明

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

命中率

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

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

  • 流量命中率: 该指标的计算公式是 流量命中率 =(边缘下行流量 - 回源流量)/ 边缘下行流量。该 API 对每个统计时间段的流量命中率进行统计。边缘下行流量指的是内容分发网络边缘层向所有客户端传输的总流量。回源流量指的是源站向内容分发网络传输的总流量。

不支持对该指标进行筛选

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

使用限制

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

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

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

公共参数

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

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

请求鉴权

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

请求正文参数

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

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

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

StartTimeEndTimeInterval 这三个参数决定了该 API 对哪些时间段做数据统计。参见 统计时间段说明
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
指定一个时间粒度。基于这个粒度,对访问数据进行细分统计。

StartTimeEndTimeInterval 这三个参数决定了该 API 对哪些时间段做数据统计。参见 统计时间段说明

该参数的可用值如下:
  • 1min:表示以 1 分钟为时间粒度。
  • 5min:表示以 5 分钟为时间粒度。
  • hour:表示以 1 小时为时间粒度。
  • day:表示以 1 天为时间粒度。
您可以指定的时间粒度与StartTimeEndTime 指定的时间范围的关系如下:
  • 如果时间范围 <= 1 天,您可以指定的时间粒度有 1min5minhour
  • 如果时间范围 > 1 天并且 <= 31 天,您可以指定的时间粒度有 5minhourday
  • 如果时间范围 > 31 天并且 <= 92 天,您可以指定的时间粒度有 day
如果不指定该参数,该参数使用默认值 5min。如果默认值不匹配时间范围,API 请求会失败。
1min
Area
string
指定一个区域,统计 IP 归属地为这些区域的访问细分数据。该参数的可用值如下:
  • China:表示中国区域。
  • Global:表示全球区域。
在统计非中国区数据时,如果指定了 GlobalRegion,则不能使用 Isp 对数据进行筛选。

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

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

如果 Metricflux 或者 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 。

如果 Metricflux 或者 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 参数,API 返回的内容还包括所有指定域名的汇总指标。
  • 如果设置 Aggregate 参数值为 disaggregate,API 返回的内容不包括所有指定域名的汇总指标。
  • 如果设置 Aggregate 参数值为 aggregate,API 仅返回所有指定域名的汇总指标。
disaggregate

统计时间段说明

StartTimeEndTimeInterval 这三个参数决定了该 API 对哪些时间段做数据统计。每个统计时间段的开始时间点的数据包含在统计结果中,结束时间点的数据不包含。数学表示类似 [07:04:00 - 07:05:00)。
该 API 按照以下规则决定数据统计的时间段:

  • Interval 指定的时间粒度下,第一个统计时间段的开始时间是最接近 StartTime 的时间。该时间早于或者等于 StartTime

  • Interval 指定的时间粒度下,最后一个统计时间段的开始时间是最接近 EndTime 的时间。该时间早于或者等于 EndTime

  • 如果 EndTime 匹配 Interval,那么最后一个统计时间段的开始时间是 EndTime

    • 示例 1:Interval5min, EndTime 是 14:15:00。此时,最后一个统计时间段是 [14:15:00 - 14:20:00)。

    • 示例 2:Intervalhour, EndTime 是 14:00:00。此时,最后一个统计时间段是 [14:00:00 - 15:00:00)。

更多示例
为了简化描述,以下例子中 StartTimeEndTime 的说明仅指出了时间部分,省略了日期部分。

StartTimeEndTimeInterval统计时间段

1665039840
该时间戳表示的时间是 07:04:00

StartTime 相同

1min

  • [07:04:00 - 07:05:00)

1665039959 该时间戳表示的时间是 07:06:00

  • [07:04:00 - 07:05:00)

  • [07:05:00 - 07:06:00)

  • [07:06:00 - 07:07:00)

1665039959 该时间戳表示的时间是 07:05:59

  • [07:04:00 - 07:05:00)

  • [07:05:00 - 07:06:00)

1665040380 该时间戳表示的时间是 07:13:00

5min

  • [07:00:00 - 07:05:00)

  • [07:05:00 - 07:10:00)

  • [07:10:00 - 07:15:00)

1665040500 该时间戳表示的时间是 07:15:00

  • [07:00:00 - 07:05:00)

  • [07:05:00 - 07:10:00)

  • [07:10:00 - 07:15:00)

  • [07:15:00 - 07:20:00)

1665048000 该时间戳表示的时间是 09:20:00

hour

  • [07:00:00 - 08:00:00)

  • [08:00:00 - 09:00:00)

  • [09:00:00 - 10:00:00)

1665050400 该时间戳表示的时间是 10:00:00

  • [07:00:00 - 08:00:00)

  • [08:00:00 - 09:00:00)

  • [09:00:00 - 10:00:00)

  • [10:00:00 - 11:00:00)

统计示例

我们以带宽为例,展示 1 小时粒度的带宽统计步骤。
假设您指定的时间段是 3:03:00 - 5:58:00,指定的时间粒度是 1 小时。此时,该时间段的带宽统计步骤如下:

  1. 确定统计时间段。基于时间粒度,该 API 将指定的时间段划分成 3 个统计时间段,分别为:[3:00:00 - 4:00:00)、[4:00:00 - 5:00:00)、[5:00:00 - 6:00:00)。

  2. 对每个统计时间段统计带宽。以 [3:00:00 - 4:00:00) 为例,该统计时间段的带宽是按照以下步骤统计的:

    1. 以 5 分钟为粒度,将 [3:00:00 - 4:00:00) 进一步划分成 12 个时间段,分别为:[3:00:00 - 3:05:00)、[3:05:00 - 3:10:00)、[3:10:00 - 3:15:00)、[3:15:00 - 3:20:00)、[3:20:00 - 3:25:00)、[3:25:00 - 3:30:00)、[3:30:00 - 3:35:00)、[3:35:00 - 3:40:00)、[3:40:00 - 3:45:00)、[3:45:00 - 3:50:00)、[3:50:00 - 3:55:00)、[3:55:00 - 4:00:00)。

    2. 对这 12 个时间段中的每个时间段计算带宽。带宽的计算公式是:流量 * 8 / 300。经过计算,我们假设这 12 个时间段的带宽分别为:12、12、12、12、10、10、75、10、8、8、8、8。

    3. 计算这些带宽的最大值作为 [3:00:00 - 4:00:00) 这个统计时间段的带宽。计算结果:该统计时间段的带宽是 75 bps。

  3. 经过计算,我们假设 [4:00:00 - 5:00:00) 的带宽是 50,[5:00:00 - 6:00:00) 的带宽是 40。该 API 返回类似以下的结果:

    3:00:00 : 75
    4:00:00 : 50
    5:00:00 : 40

说明

在实际的返回结果中,3:00:00,4:00:00,5:00:00 会以 Unix 时间戳格式显示,分别表示 3 个统计时间段的开始时间。

响应正文

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

示例

请求示例

POST https://cdn.volcengineapi.com/?Version=2021-03-01&Action=DescribeCdnData
{
    "StartTime": 1631635200,
    "EndTime": 1631642400,
    "Metric": "flux",
    "Domain": "www.example.com,www.example2.com",
    "Interval": "5min"
}

响应示例

{
    "ResponseMetadata": {
        "RequestId": "021632476592198fe8000000001115165",
        "Action": "DescribeCdnData",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-1"
    },
    "Result": {
        "Resources": [
            {
                "Name": "www.example.com",
                "Metrics": [
                    {
                        "Metric": "flux",
                        "Values": [
                            {
                                "Timestamp": 1631635200,
                                "Value": 138.0000    //域名无数据时Value值将会做补0处理
                            },
                            ...
                        ]
                    }
                ]
            },
            {
                "Name": "www.example2.com",
                "Metrics": [
                    {
                        "Metric": "flux",
                        "Values": [
                            {
                                "Timestamp": 1631635200,
                                "Value": 116.0000
                            },
                            ...
                        ]
                    }
                ]
            },
            {
                "Name": "total",
                "Metrics": [
                    {
                        "Metric": "flux",
                        "Values": [
                            {
                                "Timestamp": 1631635200,
                                "Value": 254.0000
                            },
                            ...
                        ]
                    }
                ]
            }
        ]
    }
}

错误代码

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