获取访问统计的细分数据--内容分发网络-火山引擎

文档中心

立即注册

导航

获取访问统计的细分数据

最近更新时间：2024.09.13 15:27:23首次发布时间：2024.04.16 14:36:30

API 说明

基于火山引擎内容分发网络（CDN）收到的用户请求，该 API 对一个指标统计各时间点的指标细分数据。

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

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

数据时效性：指标数据可能会有 5 分钟左右的延时。

说明

如果您刚开始使用 CDN 的统计 API，请务必先阅读以下文档，这将有助于您理解该 API 文档。

使用限制

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

请求说明

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

请求参数

Query

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

Body

参数名称	数据类型	是否必选	参数说明	示例
Metric	String	是	表示一个指标。该参数有以下取值： `traffic`：表示内容分发网络向用户传输的数据量，单位是 bytes。 `bandwidth`：表示基于内容分发网络向用户传输的数据量而计算的带宽，单位是 bps。 `requests`：表示内容分发网络收到的用户请求数量。 `qps`：表示内容分发网络收到的用户请求的 QPS。 `response_time`：表示内容分发网络响应用户请求所耗费的平均时间，单位是毫秒（ms）。 `avg_speed`：表示内容分发网络向用户传输数据时的平均速度，单位是 Bps。 `status_all`：对于所有内容分发网络对用户请求的响应，该参数表示以下各类别的状态码数量：所有状态码的数量。 2xx 状态码的数量。 3xx 状态码的数量。 4xx 状态码的数量。 5xx 状态码的数量。每个状态码的数量。 `status_2xx`：表示 2xx 状态码的数量以及该类别下每个状态码的数量。 `status_3xx`：表示 3xx 状态码的数量以及该类别下每个状态码的数量。 `status_4xx`：表示 4xx 状态码的数量以及该类别下每个状态码的数量。 `status_5xx`：表示 5xx 状态码的数量以及该类别下每个状态码的数量。关于每个指标的详情以及统计方式，参见指标的定义以及统计方式。	`traffic`
StartTime	Long	是	表示统计时间段的开始时间，格式是 Unix 时间戳，精度是秒。`StartTime` 必须早于或者等于 `EndTime`。同时，`StartTime` 与 `EndTime` 所表示的统计时间段不能超过 31 天。	`1710259200`
EndTime	Long	是	表示统计时间段的结束时间，格式是 Unix 时间戳，精度是秒。	`1710836303`
Interval	String	否	表示一个时间粒度。该 API 基于 `Interval` 将 `StartTime` 和 `EndTime` 所表示的统计时间段拆分成一系列的时间区间，然后对每个时间区间统计 `Metric` 数据。关于 `Interval`参数是如何用来拆分统计时间段，参考统计时间段说明。该参数有以下取值： `1min`：表示时间粒度是 1 分钟。 `5min`：表示时间粒度是 5 分钟。 `hour`：表示时间粒度是 1 小时。 `day`：表示时间粒度是 1 天。您可以指定的时间粒度受 `StartTime` 和 `EndTime` 所表示的时间范围的影响。如果时间范围 <= 1 天，您可以指定的时间粒度有 `1min`、`5min`、`hour`。如果 1 天 < 时间范围 <= 3 天，您可以指定的时间粒度有 `5min`、`hour`、`day`。如果 3 天 < 时间范围 <= 31 天，您可以指定的时间粒度有 `hour`、`day`。该参数的默认值是 `5min`。如果默认值不匹配时间范围，API 请求会失败。	`hour`
Project	String	否	表示一个项目。如果您指定了 `Domain`，该 API 对所有您指定的加速域名统计 `Metric` 数据。如果您指定了 `Project` ，但未指定 `Domain`，该 API 对您指定的项目统计 `Metric` 数据。参见项目数据是如何统计的。如果您既未指定 `Project` ，也未指定 `Domain`，该 API 对所有加速域名统计 `Metric` 数据。	`my_project`
Domain	String	否	表示一个或多个加速域名，用于对用户请求进行过滤。该 API 对您指定的每个加速域名统计 `Metric` 数据。您最多可以指定 50 个加速域名。多个加速域名之间使用逗号（,）分隔。如果不指定 `Domain`，表示不使用该参数对请求进行过滤。如果您指定了 `Project`，您指定的加速域名必须是属于该 `Project` 的。说明当子用户调用该 API 时，请留意以下说明：子用户只能指定其有权限访问的加速域名。子用户可以调用 ListCdnDomains 获取其有权限访问的加速域名。如果不指定该参数，表示所有该子用户有权限访问的那些加速域名。	`www.example.com,www.test.com,img.example.com`
Location	String	否	表示国家和地区的代码，用于对用户请求进行过滤。您可以指定一个或者多个代码，CDN 对来自这些国家和地区的用户请求统计 `Metric` 数据。多个国家和地区代码之间使用逗号（,）分隔。您最多可以指定 30 个国家和地区。如果您指定了 `Location`，就不能指定 `Province`，反之亦然。如果您不指定 `Location`，表示不使用该参数对请求进行过滤。您可以调用 DescribeCdnRegionAndIsp 获取代码与国家和地区的对应表。	`CHN,AZE`
Province	String	否	表示中国省级行政区的代码，用于对用户请求进行过滤。您可以指定一个或者多个代码，CDN 对来自这些省级行政区的用户请求统计 `Metric` 数据。多个代码之间使用逗号（,）分隔。您最多可以指定 10 个代码。如果您不指定 `Province`，表示不使用该参数对请求进行过滤。您可以调用 DescribeCdnRegionAndIsp 获取代码与中国省级行政区的对应表。	`AH,BJ,CQ,FJ`
Isp	String	否	表示请求所使用的中国网络运营商的代码，用于对用户请求进行过滤。例如，`CT` 表示中国电信。您可以指定一个或者多个代码，CDN 对使用这些网络运营商的用户请求统计 `Metric` 数据。多个代码之间使用逗号（,）分隔。您最多可以指定 5 个代码。当 `Location` 是 `CHN` 或者您指定了 `Province` 时，您才能指定 `Isp`。当您不指定 `Isp` 时，表示不使用该参数对请求进行过滤。您可以调用 DescribeCdnRegionAndIsp 获取代码与网络运营商的对应表。	`CT,CM,CU,GWBN`
Protocol	String	否	表示请求使用的一个应用层协议，用于对用户请求进行过滤。该参数的可用值如下： `http`：表示 HTTP 协议。 `https`：表示 HTTPS 协议。 `quic`：表示 QUIC 协议。如果不指定 `Protocol`，表示不使用该参数对请求进行过滤。	`https`
IpVersion	String	否	表示请求使用的一个网络层协议，用于对用户请求进行过滤。该参数的可用值如下： `IPv4`：表示 IPv4 协议。 `IPv6`：表示 IPv6 协议。如果不指定 `IpVersion`，表示不使用该参数对请求进行过滤。	`IPv4`

项目数据是如何统计的

在对一个项目统计指标数据时，CDN 统计的是项目内加速域名的数据。

如果统计时间段内有一个加速域名转出该项目，该项目的指标数据不会包含转出后该加速域名的数据。
如果统计时间段内有一个加速域名转入该项目，该项目的指标数据会包含转入后该加速域名的数据。

示例

考虑以下场景：

您指定的统计时间段是某天的 8:00-10:00。
加速域名X 在 9:00 从另一个项目转移到项目A。加速域名Y 一直在项目A 中。

在这个场景中，如果您对项目A 统计指标数据，则指标数据涵盖：

加速域名X 在 9:00 至 10:00 之间的指标数据。
加速域名Y 在 8:00 至 10:00 之间的指标数据。

返回参数

参数名称	数据类型	参数说明	示例
MetricDataList	Object[]	表示该 API 返回的结果数据。

请求示例

POST https://cdn.volcengineapi.com/?Action=DescribeDistrictData&Version=2021-03-01
{
    "Domain": "www.example.com,www.test.com,img.example.com",
    "StartTime": 1710259200,
    "EndTime": 1710835599,
    "Interval": "day",
    "IpVersion": "IPv4",
    "Isp": "CT,CM,CU,GWBN",
    "Metric": "traffic",
    "Project": "my_project",
    "Protocol": "https",
    "Province": "AH,BJ,CQ,FJ"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2024031916110305F6D27733C2CA667E04",
        "Action": "DescribeDistrictData",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-01"
    },
    "Result": {
        "MetricDataList": [
            {
                "Metric": "bandwidth",
                "Values": [
                    {
                        "TimeStamp": 1710259200,
                        "Value": 587
                    },
                    {
                        "TimeStamp": 1710345600,
                        "Value": 6789
                    },
                    {
                        "TimeStamp": 1710432000,
                        "Value": 2346
                    },
                    {
                        "TimeStamp": 1710518400,
                        "Value": 876467
                    },
                    {
                        "TimeStamp": 1710604800,
                        "Value": 151536517
                    },
                    {
                        "TimeStamp": 1710691200,
                        "Value": 44
                    },
                    {
                        "TimeStamp": 1710777600,
                        "Value": 7890
                    }
                ]
            }
        ]
    }
}

错误码

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