API 说明

API 名称：DescribeCdnData。
API 域名：cdn.volcengineapi.com。
API 描述：基于指定的时间段和时间粒度，对一个或多个域名统计访问请求指标的数据。指标数据是按统计时间段统计的。
数据稳定性：受边缘节点网络波动的影响，监控数据的统计可能会发生变化。大多数情况下，监控数据的统计会在数据产生后的 12 小时内稳定下来。

使用限制

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

数据保留期限：系统保留最近 92 天的访问数据。您不能查询 92 天以前的访问数据。

数据时效性：访问数据的延迟约为 5 分钟。

公共参数

在调用该 API 时，您在请求中必须包含公共参数。在这些公共参数中，以下两个查询参数的取值说明如下：

请求鉴权

每个请求中必须包含鉴权信息。该鉴权信息用以验证请求者的身份。参见请求鉴权。

请求正文参数

在您调用该 API 时，请求正文中可以包含的参数如下。

统计时间段说明

StartTime、EndTime、Interval 这三个参数决定了该 API 对哪些时间段做数据统计。每个统计时间段的开始时间点的数据包含在统计结果中，结束时间点的数据不包含。数学表示类似 [07:04:00 - 07:05:00)。
该 API 按照以下规则决定数据统计的时间段：

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

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

• 如果 EndTime 匹配 Interval，那么最后一个统计时间段的开始时间是 EndTime。

  • 示例 1：Interval 是 5min, EndTime 是 14:15:00。此时，最后一个统计时间段是 [14:15:00 - 14:20:00)。

  • 示例 2：Interval 是 hour, EndTime 是 14:00:00。此时，最后一个统计时间段是 [14:00:00 - 15:00:00)。

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

统计示例

我们以带宽为例，展示 1 小时粒度的带宽统计步骤。
假设您指定的时间段是 3:03:00 - 5:58:00，指定的时间粒度是 1 小时。此时，该时间段的带宽统计步骤如下：

1. 确定统计时间段。基于时间粒度，该 API 将指定的时间段划分成 3 个统计时间段，分别为：[3:00:00 - 4:00:00)、[4:00:00 - 5:00:00)、[5:00:00 - 6:00:00)。

2. 对每个统计时间段统计带宽。以 [3:00:00 - 4:00:00) 为例，该统计时间段的带宽是按照以下步骤统计的：

   1. 以 5 分钟为粒度，将 [3:00:00 - 4:00:00) 进一步划分成 12 个时间段，分别为：[3:00:00 - 3:05:00)、[3:05:00 - 3:10:00)、[3:10:00 - 3:15:00)、[3:15:00 - 3:20:00)、[3:20:00 - 3:25:00)、[3:25:00 - 3:30:00)、[3:30:00 - 3:35:00)、[3:35:00 - 3:40:00)、[3:40:00 - 3:45:00)、[3:45:00 - 3:50:00)、[3:50:00 - 3:55:00)、[3:55:00 - 4:00:00)。

   2. 对这 12 个时间段中的每个时间段计算带宽。带宽的计算公式是：流量 * 8 / 300。经过计算，我们假设这 12 个时间段的带宽分别为：12、12、12、12、10、10、75、10、8、8、8、8。

   3. 计算这些带宽的最大值作为 [3:00:00 - 4:00:00) 这个统计时间段的带宽。计算结果：该统计时间段的带宽是 75 bps。

3. 经过计算，我们假设 [4:00:00 - 5:00:00) 的带宽是 50，[5:00:00 - 6:00:00) 的带宽是 40。该 API 返回类似以下的结果：

   3:00:00 : 75
4:00:00 : 50
5:00:00 : 40

响应正文

示例

请求示例

POST https://cdn.volcengineapi.com/?Version=2021-03-01&Action=DescribeCdnData
{
    "StartTime": 1631635200,
    "EndTime": 1631642400,
    "Metric": "flux",
    "Domain": "www.example.com,www.example2.com",
    "Interval": "5min"
}

响应示例

{
    "ResponseMetadata": {
        "RequestId": "021632476592198fe8000000001115165",
        "Action": "DescribeCdnData",
        "Version": "2021-03-01",
        "Service": "CDN",
        "Region": "cn-north-1"
    },
    "Result": {
        "Resources": [
            {
                "Name": "www.example.com",
                "Metrics": [
                    {
                        "Metric": "flux",
                        "Values": [
                            {
                                "Timestamp": 1631635200,
                                "Value": 138.0000    //域名无数据时Value值将会做补0处理
                            },
                            ...
                        ]
                    }
                ]
            },
            {
                "Name": "www.example2.com",
                "Metrics": [
                    {
                        "Metric": "flux",
                        "Values": [
                            {
                                "Timestamp": 1631635200,
                                "Value": 116.0000
                            },
                            ...
                        ]
                    }
                ]
            },
            {
                "Name": "total",
                "Metrics": [
                    {
                        "Metric": "flux",
                        "Values": [
                            {
                                "Timestamp": 1631635200,
                                "Value": 254.0000
                            },
                            ...
                        ]
                    }
                ]
            }
        ]
    }
}

错误代码

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