文档中心

获取热门对象的统计排名

最近更新时间：2024.05.06 14:11:21

首次发布时间：2024.04.16 14:36:31

API 说明

基于内容分发网络收到的用户请求，该 API 按热门对象类型对一系列的指标数据进行汇总，并对这些汇总数据按从大到小排序，最后返回这些热门对象。热门对象类型包括请求客户端所在的国家和地区、请求 URL、Referer 域名、UA 字符串中的对象、独立客户端 IP 地址的数量。

在调用该 API 时，您需要指定一个指标，一个热门对象类型，一个统计时间段和一个时间粒度。您还可以指定多个过滤条件对用户请求进行过滤。您最多能查询过去 92 天的数据。

数据稳定性：受网络波动影响，边缘节点上的指标数据可能会发生变化。大多数情况下，在内容分发网络记录原始数据后的 12 小时内，对应的指标数据会逐步稳定下来。

使用限制

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

请求说明

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

请求参数

Query

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

Body

参数名称	数据类型	是否必选	参数说明	示例
Item	String	是	表示一个热门对象的类型作为分组和排序条件。该 API 按 `Item` 对 `Metric` 数据进行汇总并对这些汇总数据进行排序。该参数有以下取值： `region`：表示请求客户端所在的国家或地区。 `url`：表示请求 URL 中的路径。 `referer`：表示请求中的 `Referer` 域名。 `ua`：表示请求中的 `User-Agent` 字符串。 `clientip`：表示客户端的 IP 地址。说明当 `Item` 是 `ua` 时，您还需要指定 `UaType` 作为一个补充分组条件。当 `Item` 是 `region` 时，您还需要指定 `Area` 作为一个补充分组条件。	`region`
Metric	String	是	表示一个指标。该参数的可用值受 `Item` 的影响。当 `Item` 是 `referer`、`ua` 或 `clientip` 时，该参数有以下取值： `traffic`：表示内容分发网络对用户请求的响应所消耗的流量，单位是 Byte。 `requests`：表示内容分发网络收到的用户请求的数量。当 `Item` 是 `url` 时，该参数有以下取值： `traffic` `requests` `status_2xx`：在内容分发网络对用户请求的响应中，该参数表示 2xx 状态码的数量。 `status_3xx`：表示 3xx 状态码的数量。 `status_4xx`：表示 4xx 状态码的数量。 `status_5xx`：表示 5xx 状态码的数量。当 `Item` 是 `region` 时，该参数有以下取值。 `clientip`：表示独立客户端 IP 地址的数量。当 `Item` 是 `region` 时，该参数有默认值 `clientip`，并且可以不指定。	`traffic`
StartTime	Long	是	表示统计时间段的开始时间，格式是 Unix 时间戳，精度是秒。`StartTime` 必须早于或者等于 `EndTime`。同时，`StartTime` 和 `EndTime` 所表示的统计时间段不能超过 31 天。说明 `StarTime` 和 `EndTime` 指定了统计时间段。但是实际统计时间段的开始时间和结束时间都是小时级别的。例子：`StarTime` 表示的时间是 15:07，`EndTime` 表示的时间是 15:21，那么实际的统计时间段是 [15:00,16:00）。需要留意的是，如果 `EndTime` 正好是整点，则实际的统计时间段还要再往后延长 1 小时。假设 `StartTime` 表示的时间是 15:07，`EndTime` 表示的时间是 16:00，那么实际的统计时间段是 [15:00,17:00)。	`1710950400`
EndTime	Long	是	表示统计时间段的结束时间，格式是 Unix 时间戳，精度是秒。	`1710998170`
Domain	String	是	表示一个加速域名，用于对用户请求进行过滤。说明当子用户调用该 API 时，请留意以下说明：子用户只能指定一个其有权限访问的加速域名。子用户可以调用 ListCdnDomains 获取其有权限访问的加速域名。	`www.example.com`
UaType	String	否	表示 User-Agent 字符串中的一个对象类型。当 `Item` 是 `ua` 时，该参数必须指定，作为一个补充分组条件。当 `Item` 不是 `ua` 时，该参数无效。该参数有以下取值： `browser`：表示 `User-Agent` 字符串中的浏览器类型。 `system`：表示 `User-Agent` 字符串中的操作系统类型。 `equipment`：表示 `User-Agent` 字符串中客户端设备的类型。	`system`
Area	String	否	表示一个地域类型。该参数仅当 `Item` 是 `region` 时有效，作为一个补充分组条件，用于获取客户端 IP 地址数量的地区分布。该参数有以下取值： `Global`：表示全球国家和地区。 `China`：表示中国省级行政区。说明如果您不指定 `Metric`，`Area` 可以不被指定。如果不指定 `Area`，该 API 将返回按国家、地区、中国省级行政区域分布的独立客户端 IP 地址数量。如果您指定了 `Metric`，`Area` 必须指定。	`global`

返回参数

参数名称	数据类型	参数说明	示例
Item	String	表示请求参数 `Item` 所指定的热门对象类型。	`region`
Metric	String	表示请求参数 `Metric` 所指定的指标。	`traffic`
RankingDataList	Object[]	表示一组热门对象详情的列表。
UaType	String	表示请求参数中 `UaType` 所指定的对象类型。如果请求参数中不包含 `UaType`，该参数不会在返回结果中出现。	`system`

请求示例

POST https://cdn.volcengineapi.com/?Action=DescribeStatisticalRanking&Version=2021-03-01
{
    "Area": "China",
    "Domain": "www.example.com",
    "StartTime": 1710950400,
    "EndTime": 1710998170,
    "Item": "region",
    "Metric": "traffic"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202403212143118BE5C18DF185F3E6169A",
        "Action": "DescribeStatisticalRanking",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-01"
    },
    "Result": {
        "Item": "region",
        "Metric": "traffic",
        "RankingDataList": [
            {
                "ItemKey": "GS",
                "ItemKeyCN": "甘肃",
                "Value": 777
            },
            {
                "ItemKey": "ZJ",
                "ItemKeyCN": "浙江",
                "Value": 348
            },
            {
                "ItemKey": "NM",
                "ItemKeyCN": "内蒙古",
                "Value": 271
            },
            {
                "ItemKey": "NX",
                "ItemKeyCN": "宁夏",
                "Value": 83
            },
            {
                "ItemKey": "CQ",
                "ItemKeyCN": "重庆",
                "Value": 78
            },
            {
                "ItemKey": "OTHERS",
                "ItemKeyCN": "OTHERS",
                "Value": 39
            },
            {
                "ItemKey": "SH",
                "ItemKeyCN": "上海",
                "Value": 36
            },
            {
                "ItemKey": "XZ",
                "ItemKeyCN": "西藏",
                "Value": 19
            },
            {
                "ItemKey": "MO",
                "ItemKeyCN": "澳门",
                "Value": 2
            },
            {
                "ItemKey": "TW",
                "ItemKeyCN": "台湾",
                "Value": 2
            }
        ]
    }
}