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

获取热点及访客的统计排名

最近更新时间2023.06.12 10:42:29

首次发布时间2021.11.18 11:16:57

API 说明

API 名称:DescribeEdgeTopStatisticalData
API 域名:cdn.volcengineapi.com
API 描述:基于指定的时间段,获取某个域名的热点数据和访客数量。该 API 对用户请求中的以下字段进行统计。

  • URL:按流量、请求数或状态码数量获取 TOP 1000 的请求 URL。
  • Referer:按流量或请求数获取 TOP 1000 的请求 Referer。
  • 客户端 IP:按流量或请求数获取 TOP 1000 的客户端 IP。
  • User-Agent:基于流量或请求数,获取客户端设备类型的排行、客户端浏览器排行以及客户端操作系统排行。
  • 区域。基于独立访客 IP 的数量,获取访客 IP 所归属的中国省份、国家和地区的排行。

数据稳定性:受边缘节点网络波动的影响,监控数据的统计可能会发生变化。大多数情况下,监控数据的统计会在数据产生后的 12 小时内稳定下来。

每个字段支持的统计排序的指标是不同的。具体内容如下。

可用于对请求 URL 进行统计排序的指标
在对请求 URL 进行统计排序时,该 API 会忽略 URL 中的参数。您可以指定以下指标对请求 URL 做统计排序:

  • 流量:表示请求所产生的流量。
  • 请求数:表示请求数。
  • 2XX 状态码:表示响应状态码的数量。这些响应状态码的范围是 200-299。
  • 3XX 状态码:表示响应状态码的数量。这些响应状态码的范围是 300-399。
  • 4XX 状态码:表示响应状态码的数量。这些响应状态码的范围是 400-499。
  • 5XX 状态码:表示响应状态码的数量。这些响应状态码的范围是 500-599。

可用于对请求 Referer,客户端 IP 和请求 User-Agent 进行统计排序的指标
您可以指定以下指标对这些字段做统计排序:

  • 流量:表示请求所产生的流量。
  • 请求数:表示请求数。

可用于对区域进行统计排序的指标
您可以指定以下指标对区域做统计排序:

  • 独立访客 IP 数量:表示各区域独立访客 IP 的数量。可通过 Area 参数进行筛选。筛选维度如下:
    • 中国:表示中国区域。返回中国各省份的独立访客 IP 的数量。
    • 全球:表示全球区域。返回全球各国家和地区的独立访客 IP 的数量。

使用限制

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

时间限制:域名访问数据保存近 92 天数据。您不能查询 92 天以前的域名访问数据。

数据时延:数据延迟约为 120 分钟左右。

公共参数

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

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

请求鉴权

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

请求正文参数

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

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

您必须同时指定 StartTimeEndTime,或者都不指定。如果您不指定这 2 个参数,默认统计最近 24 小时的数据。
1641844915
EndTime
int64
指定一个结束时间。时间格式是 Unix 时间戳,精度是秒。
1641845373
Domain
string
指定一个域名进行统计。
www.example.com
Item
string
指定一个统计字段。该参数的可用值如下:
  • region:表示发送请求的客户端的 IP 所归属的区域。
  • url:表示请求 URL。
  • referer:表示请求 Referer。
  • ua:表示请求 User-Agent。
  • clientip:表示客户端 IP。
url
UaType
string
Item=ua 时,该参数必填。指定 User-Agent 字符串中的一个数据维度,展示该维度的指标数据。该参数的可用值如下:
  • Equipment:表示客户端设备的类型。
  • Browser:表示客户端使用的浏览器。
  • System:表示客户端使用的操作系统。
Equipment
Metric
string
指定一个指标。基于该指标的统计数据,对 Item 进行排序。根据 Item 参数的值,Metric 参数的取值分以下几种情况:

item=url 时,您可以指定以下指标:
  • flux:表示请求所产生的总流量。单位是 Byte。
  • pv:表示总请求数。
  • status_2xx:表示响应状态码的总数。这些响应状态码的范围是 200-299。
  • status_3xx:表示响应状态码的总数。这些响应状态码的范围是 300-399。
  • status_4xx:表示响应状态码的总数。这些响应状态码的范围是 400-499。
  • status_5xx:表示响应状态码的总数。这些响应状态码的范围是 500-599。
Item=refererItem=uaItem=clientip 时,您可以指定以下指标:
  • flux:表示请求所产生的总流量。单位是 Byte。
  • pv:表示总请求数。
item=region 时,您可以指定的指标是 clientip,表示各区域的独立访客 IP 的数量。
flux
Area
string
指定一个访客 IP 的归属区域。当 item=region 时,该参数有效。该参数的可用值如下:
  • China:表示中国区域。对中国各省份的数据进行排序。
  • Global:表示全球区域。对全球各国家和地区的数据进行排序。
如果不指定该参数,该参数使用默认值 China
China

请求 URL,请求 Referer,客户端 IP,请求 User-Agent 的统计逻辑

统计的最小时间粒度为 1 小时。系统会选择大于等于 StartTime 并且小于等于 EndTime 的时间范围,以小时为数据点,对字段进行统计排序。示例如下:

  • StartTime:2022-01-14 03:00:00,EndTime:2022-01-14 04:00:00。数据排序是基于 03:00:00 - 04:00:00 和 04:00:00 - 05:00:00 两个时间段的汇总统计数据。
  • StartTime:2022-01-14 03:20:00,EndTime:2022-01-14 04:20:00。数据排序是基于04:00:00 - 05:00:00 时间段的统计数据。
  • StartTime:2022-01-14 03:20:00 ,EndTime:2022-01-14 05:00:00。数据排序是基于 04:00:00 - 05:00:00 和 05:00:00 - 06:00:00 两个时间段的汇总统计数据。
  • StartTime:2022-01-14 03:00:00 ,EndTime:2022-01-14 04:20:00。数据排序是基于03:00:00 - 04:00:00 和 04:00:00 - 05:00:00 两个时间段的汇总统计数据。

独立访客 IP 的统计逻辑

独立访客 IP 的去重统计的最小时间粒度为 1 小时。同时也支持天粒度的去重统计,统计逻辑如下:

  • 如果 StartTime 与 EndTime 所指定的时间范围小于 24 小时,统计逻辑与请求 URL 的统计逻辑一致。 按小时对独立访客 IP 去重后再进行统计排序。
  • 如果 StartTime 与 EndTime 所指定的时间范围大于等于 24 小时,系统会对选择大于等于 StartTime 并且小于等于 EndTime 的时间范围,按天对独立访客 IP 去重后再进行统计排序。示例如下:
    • StartTime:2022-01-14 03:31:00,EndTime:2022-01-15 04:20:00,数据排序是基于 2022-01-15 00:00:00 - 2022-01-16 00:00:00 的统计数据。
    • StartTime:2022-01-14 00:00:00,EndTime:2022-01-15 04:20:00,数据排序是基于 2022-01-14 00:00:00 - 2022-01-15 00:00:00 和2022-01-15 00:00:00 - 2022-01-16 00:00:00 两个时间段的汇总统计数据。
    • StartTime:2022-01-14 00:20:00,EndTime:2022-01-15 00:00:00,数据排序是基于2022-01-15 00:00:00 - 2022-01-16 00:00:00 时间段的统计数据。
    • StartTime:2022-01-14 00:00:00,EndTime:2022-01-15 04:20:00,数据排序是基于 2022-01-14 00:00:00 - 2022-01-15 00:00:00 和 2022-01-15 00:00:00 - 2022-01-16 00:00:00 两个时间段的汇总统计数据。

响应正文

参数名称
数据类型
参数说明
示例
Domain
string
表示指定的域名。
www.example.com
TopDataDetails
TopDataDetail[]
表示排序后的统计数据对象。

示例

请求示例

POST https://cdn.volcengineapi.com/?Version=2021-03-01&Action=DescribeEdgeTopStatisticalData
{
    "Domain": "www.example.com",
    "StartTime": 1636559700,
    "EndTime": 1636560300,
    "Metric": "clientip",
    "Item":"region"
}

响应示例

{
{
    "ResponseMetadata": {
        "RequestId": "2022010610154701021215002105003008",
        "Action": "DescribeEdgeTopStatisticalData",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-1"
    },
    "Result": {
        "Item": "region",
        "Metric": "ClientIP",
        "Name": "www.example.com",
        "TopDataDetails": [
            {
                "ItemKey": "GD",
                "ItemKeyCN": "广东",
                "Value": 36
            },
            {
                "ItemKey": "BJ",
                "ItemKeyCN": "北京",
                "Value": 0
            },
            ...
        ]
    }
}

错误代码

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