You need to enable JavaScript to run this app.
导航
内容分发网络
  • 文档首页
    • /
  • 内容分发网络

获取独立访客的细分数据

最近更新时间：2024.04.16 15:17:50

首次发布时间：2021.11.18 11:17:36

我的收藏

说明

我们全新设计了数据统计 API。推荐您使用 新版 API。

基于指定的时间段和时间粒度，对一个域名统计独立访客 IP 的数量。独立访客 IP 数量是按统计时间段统计的。参见统计时间段说明。

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

每个统计时间段的独立访客 IP 数量按以下公式计算：

  • 先对独立访客 IP 进行去重，然后统计 IP 数量。

参见统计示例。

使用限制

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

时间限制：系统保留最近 92 天的独立访客 IP 数据。您不能查询 92 天以前的数据。

数据时延：数据延时约为 1 小时。

请求说明

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

请求参数

Query

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

Body

参数名称
数据类型
是否必选
参数说明
示例
StartTime
Long
是

指定一个开始时间。时间格式是 Unix 时间戳，精度是秒。StartTime 必须早于或者等于 EndTime。

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

StartTime、EndTime、Interval 这三个参数决定了该 API 对哪些时间段做数据统计。参见 统计时间段说明。
1641844915
EndTime
Long
是
指定一个结束时间。时间格式是 Unix 时间戳，精度是秒。
1641845373
Metric
String
是
指定一个指标。该参数的可用值如下：
clientIp：表示独立访客 IP 数量。单位是 个。
clientIp
Domain
String
否
指定一个域名进行统计。
www.example.com
Interval
String
否

指定一个时间粒度。基于这个粒度，统计独立访客 IP 的数量。

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

该参数的可用值如下：

  • hour：表示以 1 小时为时间粒度，按小时维度对访客 IP 去重后再统计。
  • day：表示以 1 天为时间粒度，按小时维度对访客 IP 去重后再统计。

您可以指定的时间粒度与StartTime 和 EndTime 指定的时间范围的关系如下：

  • 如果时间范围 <= 31 天，您可以指定的时间粒度有 day、hour。
  • 如果时间范围 > 31 天并且 <= 92 天，您可以指定的时间粒度有 day。
如果不指定该参数，该参数使用默认值 day。
day
Area
String
否

指定一个区域，统计IP 归属地为这些区域的独立访客 IP 的数量。该参数的可用值如下：

  • China：表示中国区域。
  • Global：表示全球区域。
如果不指定该参数，表示仅通过 Region 参数筛选。具体参见 Region 参数。
China
Region
String
否

指定一个国家、地区或者中国省份，统计 IP 归属地为这些区域的独立访客 IP 的数量。国家，地区和省份代码可通过 DescribeCdnRegionAndIsp 获取。

当指定 Area 参数时，有以下几种情况：

  • 当 Area = China 时，Region 参数有以下几种情况：
    • 如果指定 Region 参数，Region 参数只能是中国的省份。表示仅统计该省份的数据。
    • 如果不指定 Region 参数，表示统计的是中国所有省份的汇总数据。
  • 当 Area = Global 时，有以下几种情况：
    • 如果指定 Region 参数，Region 参数可以是某个国家，地区或者中国的某个省份。表示统计该国家，该地区或者该中国省份的数据。例如，当 Region = CHN 时，统计的是中国所有省份的汇总数据。
    • 如果不指定 Region 参数，表示统计的是所有国家和地区的汇总数据。

当不指定 Area 参数时，有以下几种情况：

  • 如果不指定 Region 参数，表示统计的是所有国家和地区的汇总数据。
  • 如果 Region = CHN，表示统计的是中国所有省份的汇总数据。
  • 如果 Region 参数是其他某个国家，地区或者中国的某个省份，表示统计该国家，该地区或者该中国省份的数据。
BJ
IpVersion
String
否

指定请求的一个网络层协议。该参数的可用值如下：

  • ipv4：表示 IPv4 访客的请求。
  • ipv6：表示 IPv6 访客的请求。
如果不指定该参数，表示包含所有支持的网络层协议。
ipv6

统计时间段说明

StartTime、EndTime、Interval 这三个参数决定了该 API 对哪些时间段做数据统计。该 API 按照以下规则决定数据统计的时间段：

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

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

每个统计时间段的开始时间点的数据包含在统计结果中，结束时间点的数据不包含。数学表示类似 [07:00:00 - 08:00:00)。

举例

说明

为了简化描述，以下例子中StartTime 和 EndTime 的说明仅指出了时间部分，省略了日期部分。

StartTimeEndTimeInterval统计时间段

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

与 StartTime 相同

hour

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

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

  • [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)

统计示例

假设您指定的时间段是 3:03:00 - 5:58:00，指定的时间粒度是 1 小时。此时，该时间段的独立访客 IP 数量的统计步骤如下：

  1. 确定统计时间段。基于时间粒度，该 API 将指定的时间段划分成 3 个统计时间段，分别为：[3:00:00 - 4:00:00)、[4:00:00 - 5:00:00)、[5:00:00 - 6:00:00)。
  2. 对每个统计时间段统计独立访客 IP 的数量。假设每个统计时间段有以下访客 IP。
    • [3:00:00 - 4:00:00)：17.247.28.49，161.47.134.73，17.247.28.49，54.171.67.177，17.247.28.49
    • [4:00:00 - 5:00:00)：19.47.8.77，238.139.139.237，238.139.139.237
    • [5:00:00 - 6:00:00)：17.247.28.49，161.47.134.73

经过计算，该 API 返回类似以下的结果：
3:00:00 : 3
4:00:00 : 2
5:00:00 : 2

说明

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

响应正文

参数名称
数据类型
参数说明
示例
Resources
Object[]
域名详细数据

请求示例

POST https://cdn.volcengineapi.com/?Action=DescribeEdgeStatisticalData&Version=2021-03-01
{
  "StartTime": 1636559700,
  "EndTime": 1636560300,
  "Metric": "clientIp",
  "Domain": "www.example.com",
  "Interval": "day"
}

返回示例

{
        "ResponseMetadata": {
                "RequestId": "2021111810395401022524314707A38C00",
                "Action": "DescribeEdgeStatisticalData",
                "Version": "2021-03-01",
                "Service": "CDN",
                "Region": "cn-north-1"
        },
        "Result": {
                "Resources": [
                {
                        "Metrics": [
                        {
                                "Metric": "ClientIP",
                                "Values": [
                                {
                                        "TimeStamp": 1636473600,
                                        "Value": 284272   //域名无数据时Value值将会做补0处理
                                },
                                {
                                        "TimeStamp": 1636560000,
                                        "Value": 281153
                                }
                                ]
                        }
                        ],
                        "Name": "www.example.com"
                }
                ]
        }
}

错误码

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