You need to enable JavaScript to run this app.
导航
获取热门对象的统计排名
最近更新时间:2024.07.10 17:17:48首次发布时间:2024.04.16 14:36:31

API 说明

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

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

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

数据时效性:热门对象是基于按小时粒度统计的指标数据。因此,数据统计可能会有 2 小时左右的延时。例如,对于 09:00 至 10:00 这个时间段的热门对象,您可以在 11:00 左右获取到准确的结果。

使用限制

节流限制:您每秒最多可以提交 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 按 ItemMetric 数据进行汇总并对这些汇总数据进行排序。该参数有以下取值:

  • region:表示请求客户端所在的国家或地区。
  • url:表示请求 URL 中的路径。
  • referer:表示请求中的 Referer 域名。
  • ua:表示请求中的 User-Agent 字符串。
  • clientip:表示客户端的 IP 地址。

说明

  • Itemua 时,您还需要指定 UaType 作为一个补充分组条件。
  • Itemregion 时,您还需要指定 Area 作为一个补充分组条件。
region
Metric
String

表示一个指标。该参数的可用值受 Item 的影响。

  • Itemrefereruaclientip 时,该参数有以下取值:

    • traffic:表示内容分发网络向用户传输的数据量,单位是 bytes。
    • requests:表示内容分发网络收到的用户请求的数量。
  • Itemurl 时,该参数有以下取值:

    • traffic
    • requests
    • status_2xx:在内容分发网络对用户请求的响应中,该参数表示 2xx 状态码的数量。
    • status_3xx:表示 3xx 状态码的数量。
    • status_4xx:表示 4xx 状态码的数量。
    • status_5xx:表示 5xx 状态码的数量。
  • Itemregion 时,该参数有以下取值。

    • clientip:表示独立客户端 IP 地址的数量。

    Itemregion 时,该参数有默认值 clientip,并且可以不指定。

traffic
StartTime
Long

表示统计时间段的开始时间,格式是 Unix 时间戳,精度是秒。StartTime 必须早于或者等于 EndTime。同时,StartTime 和 EndTime 所表示的统计时间段不能超过 31 天。

说明

  • StartTimeEndTime 指定了统计时间段。但是实际统计时间段的开始时间和结束时间都是小时级别的。

    例子:StartTime 表示的时间是 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 字符串中的一个对象类型。当 Itemua 时,该参数必须指定,作为一个补充分组条件。当 Item 不是 ua 时,该参数无效。

该参数有以下取值:

  • browser:表示 User-Agent 字符串中的浏览器类型。
  • system:表示 User-Agent 字符串中的操作系统类型。
  • equipment:表示 User-Agent 字符串中客户端设备的类型。
system
Area
String

表示一个地域类型。该参数仅当 Itemregion 时有效,作为一个补充分组条件,用于获取客户端 IP 地址数量的地区分布。该参数有以下取值:

  • Global:表示全球国家和地区。
  • China:表示中国省级行政区。

说明

  • 如果您不指定 MetricArea 可以不被指定。
    • 如果不指定 Area,该 API 将返回按国家、地区、中国省级行政区域分布的独立客户端 IP 地址数量。
  • 如果您指定了 MetricArea 必须指定。
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
            }
        ]
    }
}

错误码

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