CDN > API 文档 > 用量统计

用量统计

最近更新时间: 2026-03-25 14:06:26

1. 快速查阅区

1.1核心接口概览

接口功能	请求方法	接口路径	核心参数	成功响应
计量带宽查询	POST	`/v2/tune/bandwidth`	domains、startDate、endDate、granularity	`{"code":200,"data":{...}}`
计量流量查询	POST	`/v2/tune/flux`	domains、startDate、endDate、granularity	`{"code":200,"data":{...}}`
监控带宽查询	POST	`/v2/tune/monitoring/bandwidth`	domains、startDate、endDate、granularity	`{"code":200,"data":{...}}`
监控流量查询	POST	`/v2/tune/monitoring/flow`	domains、startDate、endDate、granularity	`{"code":200,"data":{...}}`

1.2 核心约束

请求域名: fusion.qiniuapi.com
鉴权方式: QBox 鉴权（详见鉴权指南）
QPS限制: 5-10 QPS
数据保留: 计量数据180天,监控数据90天
时间跨度: startDate 和 endDate 查询跨度 ≤ 31 天，超出返回 400082

1.3 参数关键差异

domains 为 string 类型 (分号分隔)，不是数组，传数组会报 400 错误。
与运营统计的 domains 为 array 类型不同，务必区分。

2. 公共请求参数

参数名	类型	必填	说明	示例值
domains	string	是	域名列表，分号分隔，最多 50 个	`"a.com;b.com"`
startDate	string	是	开始日期，格式 yyyy-MM-dd	`"2026-02-01"`
endDate	string	是	结束日期，格式 yyyy-MM-dd，跨度 ≤ 31 天	`"2026-02-10"`
granularity	string	否	时间粒度，不传默认 5min	`"5min"` / `"hour"` / `"day"`
Type	string	否	指定带宽/流量类型，根据接口查询内容设定	`""` / `"bandwidth"｜"flux"`

3. 公共响应格式

响应内容

{
  "code": <code>,
  "error": <error>,
  "time": <time>,
  "data": {
    ...
    <Domain_i>: {
      "china": <Domain_i_China>,
      "oversea": <Domain_i_Oversea>
    },
    ...
  }
}

响应参数

参数名	类型	说明
code	int	响应状态码
error	string	响应错误描述
time	[]string	时间点数组，如2026-01-02 00:00:00
data	map	响应数据
Domain_i	string	域名
Domain_i_China	[]int	Domain_i 国内带宽/流量数据，与 time 一一对应
Domain_i_Oversea	[]int	Domain_i 海外带宽/流量数据，与 time 一一对应

4. 详细接口说明

4.1 计量带宽查询

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/bandwidth
数据用途: 账单核对，计量维度带宽数据 (bps)

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/bandwidth' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-01","endDate":"2026-02-10","granularity":"5min"}'

响应示例

成功 (HTTP 200):

{
    "code": 200,
    "error": "",
    "time": [
        "2026-02-01 00:00:00",
        "2026-02-01 00:05:00"
    ],
    "data": {
        "test.example.com": {
            "china": [
                1252,
                4431
            ],
            "oversea": [
                678,
                414
            ]
        }
    }
}

4.2 计量流量查询

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/flux
数据用途: 账单核对，计量维度流量数据 (byte)

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/flux' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-01","endDate":"2026-02-10","granularity":"day"}'

4.3 监控带宽查询

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/monitoring/bandwidth
数据用途: 实时监控，分钟级带宽数据，时效性优先

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/monitoring/bandwidth' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-10","endDate":"2026-02-10","granularity":"5min"}'

4.4 监控流量查询

基本信息

请求方法: POST
接口地址: https://fusion.qiniuapi.com/v2/tune/monitoring/flow
数据用途: 实时监控，分钟级流量数据，时效性优先

请求示例

curl -X POST 'https://fusion.qiniuapi.com/v2/tune/monitoring/flow' \
  -H 'Host: fusion.qiniuapi.com' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: QBox <AK>:<Sign>' \
  -d '{"domains":"test.example.com","startDate":"2026-02-10","endDate":"2026-02-10","granularity":"5min"}'

5. 常见问题

5.1 专属错误码

错误码	描述	场景	解决方案
400	domains 类型错误	传了数组而非字符串	domains 必须为 string，分号分隔
400080	开始时间格式错误	startDate 非 yyyy-MM-dd	修正日期格式
400081	结束时间格式错误	endDate 非 yyyy-MM-dd	修正日期格式
400082	无效的时间范围	startDate 大于 endDate、跨度超 31 天、或超出数据保留期	调整时间范围
400032	无效域名	域名未接入 CDN	确认域名已创建且上线

5.2 最佳实践

domains 格式: 字符串用分号分隔，不是数组，最多 50 个
时间范围: 跨度不超过 31 天，建议按天/按周查询
多域名聚合: 一次查询多域名时，响应按域名分组返回
缓存策略: 计量数据变化低频，建议本地缓存 5-10 分钟

参考: 鉴权详见鉴权指南，错误码详见公共错误码&通用约束。

以上内容是否对您有帮助？