文档中心

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

最近更新时间：2024.04.16 14:45:14

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

说明

我们全新设计了数据统计 API。推荐您使用新版 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 分钟左右。

请求说明

请求方式：POST
请求地址：https://cdn.volcengineapi.com/?Action=DescribeEdgeTopStatisticalData&Version=2021-03-01

请求参数

Query

参数名称	数据类型	是否必选	参数说明
Action	String	是	接口名称。当前 API 的名称为 `DescribeEdgeTopStatisticalData`。
Version	String	是	接口版本。当前 API 的版本为 `2021-03-01`。

Body

参数名称	数据类型	是否必选	参数说明	示例
StartTime	Long	是	指定一个开始时间。时间格式是 Unix 时间戳，精度是秒。`StartTime` 必须早于或者等于 `EndTime`。您必须同时指定 `StartTime` 和 `EndTime`，或者都不指定。如果您不指定这 2 个参数，默认统计最近 24 小时的数据。	`1641844915`
EndTime	Long	是	指定一个结束时间。时间格式是 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=referer`，`Item=ua` 或 `Item=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 两个时间段的汇总统计数据。

响应正文

参数名称	数据类型	参数说明	示例
TopDataDetails	Object[]	表示排序后的统计数据对象。

请求示例

POST https://cdn.volcengineapi.com/?Action=DescribeEdgeTopStatisticalData&Version=2021-03-01
{
    "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
            },
            ...
        ]
    }
}

错误码

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

使用限制

请求说明

请求参数

Query

Body

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

独立访客 IP 的统计逻辑

响应正文

请求示例

返回示例

错误码

内容分发网络

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

使用限制

请求说明

请求参数

Query

Body

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

独立访客 IP 的统计逻辑

响应正文

请求示例

返回示例

错误码