用量查询API

对象存储用量查询API为用户提供详细的用量和计费数据的编程访问能力，旨在帮助合作伙伴和渠道商在子账号或单独Bucket层面自动化监控用量。

概述

该API可获取多种用量指标，包括：

• 存储用量：标准、低频访问及归档存储类别。
• 请求数：读请求和写请求。
• 数据检索：低频访问和归档存储层的流量。
• 流量和带宽：CDN回源流量、出口流量及跨区域复制流量。
• 文件操作：文件操作的总次数。

Endpoint 详情

所有请求均需通过 POST 方法发送到生产环境 Endpoint。

• 请求方法：POST
• 生产环境 URL：https://wos.cdnetworks.com/api/usage/statistics

注意：生产环境必须使用 HTTPS。通过 HTTP 方式发起的请求将被重定向，且可能导致请求失败。

API 请求流程

1. 前提条件：生成一个密钥 apikey，并提供给我们的支持团队进行后台配置。
2. 认证：为您的请求构建必要的 Date 和 Authorization 请求头。
3. 请求：根据所需的查询参数构建您的 JSON 请求体。
4. 执行：向生产环境的终端节点发送 POST 请求。
5. 响应：解析 JSON 格式的响应以获取您的用量数据。

认证

此高级接口采用自定义 HMAC-SHA256 认证机制。每个 API 请求都必须包含 Date 和 Authorization 头部。

如需使用该高级接口，您需要准备一个 username 和一个 apikey。apikey 是您自行生成的密钥。要启用 API 访问权限，您必须将该密钥提供给我们的支持团队，以便进行后台配置。

认证步骤

1. 获取当前时间：请按照 RFC1123 规范格式化当前时间（例如：Thu, 21 Jul 2025 07:54:00 GMT）。此字符串将在 Date 头部中使用。
2. 计算签名：请使用您的 apikey 作为密钥，以 Date 字符串作为消息，生成 HMAC-SHA256 签名。结果需进行 Base64 编码。
   • 公式：password = Base64(HMAC-SHA256(UTF-8(apikey), UTF-8(Date)))
3. 构建Authorization字符串：
   • 创建格式为 username:password 的字符串。
   • 对完整的username:password字符串进行Base64编码。
4. 设置Authorization头部：最终的头部值为字符串Basic，后接前一步生成的Base64编码字符串。
   • 格式：Authorization: Basic <Base64(username:password)>

数据单位

API根据指标类型以特定单位返回使用数据：

• 存储指标（storageSize）：以兆字节（MB）为单位返回，使用以 1024 为基数（二进制计算），即 1 MB = 1024 KB。
• 流量和带宽指标（outTraffic、innerBandwidth 等）：流量以兆字节（MB）为单位返回，带宽以兆位每秒（Mbps）为单位返回，计算采用以 1000 为基数（十进制）。
• 请求与操作计数：以整数形式返回。

Headers

Header	是否必填	描述
Authorization	是	通过上述流程生成的身份认证令牌。
Date	是	当前时间，采用 RFC1123 格式（例如：Thu, 21 Jul 2025 07:54:00 GMT）。
Content-Type	是	必须设置为 application/json。

请求体参数

参数	是否必需	描述
startDate	是	查询周期的开始日期。格式为：YYYY-MM-DD。
endDate	是	查询周期的结束日期。格式为：YYYY-MM-DD。
statisticsType	是	要查询的用量数据类型。请参见下方“Statistics Types”部分获取有效选项。
storageRegion	否	存储区域的逗号分隔列表（例如：CN,US,SG）。如未填写，返回所有区域的数据。
storageType	否	存储类型。可选值：Standard、InfrequentAccess、Archive。仅支持同时指定一种类型。
bucket	否	以逗号分隔的Bucket名称列表。不传则返回所有可访问Bucket的数据。
isGroupByBucket	否	设置为 1 时，按Bucket维度返回用量数据；不传或设置为 0 时，返回汇总总量。
groupBy	否	数据的时间粒度。可选值：day（默认）或 hour。 • day：每日返回一个值。对于storageSize，为每日峰值；对于流量和请求数，为每日累计总量。 • hour：所有指标类型均按小时明细返回。
timeZone	否	查询时区。 • 支持值：GMT-12 至 GMT+12（如 GMT+8、GMT-5）。 • 默认值：GMT+8。 • 说明：响应数据将基于指定时区计算，时区无效时返回400错误。
bandwidthAlgorithm	否	带宽计算方式。仅当statisticsType为innerBandwidth或outBandwidth时生效。可选值： • ninetyFivePeak（默认）：95值峰值。 • avgPeak：每日峰值平均。 • fourthPeak：第4大峰值。 • firstPeak：最大峰值。

统计类型（statisticsType）

分类	statisticsType取值	描述
存储与请求	storageSize	存储在Bucket中的数据量，按存储类型（标准、低频、归档）分类。数据每小时更新一次。注意：存储容量基于1024进制计算（1 TB = 1024 GB）。
	numberOfRequests	API请求次数。包括读取（GET，HEAD）和写入（POST，PUT，DELETE）请求。写入请求还包括如生命周期删除和存储类型转换等操作。无论请求成功还是失败，均计入统计。
数据读取与删除	infrequentAccessRestore	由访问低频存储中的文件所产生的数据获取回源流量。
	infrequentDelete	在达到低频存储30天最小存储周期之前被删除的数据量。
	archiveRestore	归档存储中的文件解冻（恢复）后所产生的数据获取回源流量。
	archiveDelete	在达到归档存储60天最小存储周期之前被删除的数据量。
流量和带宽	innerTraffic	在CDNetworks CDN产品（如内容加速、媒体加速）以Object Storage作为源站时产生的CDN回源量。流量基于1000进制计算（1 TB = 1000 GB）。
	outTraffic	从Object Storage下载数据至公网所产生的出网流量。流量基于1000进制计算（1 TB = 1000 GB）。
	innerBandwidth	CDN回源带宽。返回值取决于请求中指定的bandwidthAlgorithm参数，默认取值为95峰值。
	outBandwidth	出口带宽至公网。返回值取决于请求中指定的 bandwidthAlgorithm。默认返回峰值为95值。
	crossRegionTraffic	由跨区域复制所产生的源桶出口流量。流量按千进制计算（1 TB = 1000 GB）。
操作	fileOpNumber	执行的文件操作总数。

使用示例

示例 1：查询汇总存储用量

该请求用于查询美国和新加坡区域标准存储的每日峰值存储总量。

请求：

curl -X POST \
  https://wos.cdnetworks.com/api/usage/statistics \
  -H 'Authorization: Basic YOUR_AUTH_STRING' \
  -H 'Date: Thu, 21 Jul 2025 07:54:00 GMT' \
  -H 'Content-Type: application/json' \
  -d '{
    "startDate": "2025-07-10",
    "endDate": "2025-07-11",
    "storageRegion": "US,SG",
    "storageType": "Standard",
    "statisticsType": "storageSize"
}'

响应：

{
    "code": "200",
    "message": "OK",
    "statisticsType": "storageSize",
    "data": [
        {
            "dataTime": "2025-07-10",
            "storage": "5120"
        },
        {
            "dataTime": "2025-07-11",
            "storage": "5180"
        }
    ]
}

注意：storage 的数值表示每日峰值云存储，单位为兆字节（MB）。

示例 2：按桶查询请求数

此请求按桶统计每日的读写请求数。

请求：

curl -X POST \
  https://wos.cdnetworks.com/api/usage/statistics \
  -H 'Authorization: Basic YOUR_AUTH_STRING' \
  -H 'Date: Thu, 21 Jul 2025 07:54:00 GMT' \
  -H 'Content-Type: application/json' \
  -d '{
    "startDate": "2025-07-10",
    "endDate": "2025-07-11",
    "statisticsType": "numberOfRequests",
    "isGroupByBucket": "1"
}'

Response:

{
    "code": "200",
    "message": "OK",
    "statisticsType": "numberOfRequests",
    "data": [
        {
            "dataTime": "2025-07-10",
            "readRequests": {
                "bucket1": "15000",
                "bucket2": "25000"
            },
            "writeRequests": {
                "bucket1": "3000",
                "bucket2": "5000"
            }
        },
        {
            "dataTime": "2025-07-11",
            "readRequests": {
                "bucket1": "16500",
                "bucket2": "27500"
            },
            "writeRequests": {
                "bucket1": "3200",
                "bucket2": "5300"
            }
        }
    ]
}

错误代码

状态码	错误信息	原因
400	Date In Headers Is Invalid	请求头中的 Date 字段缺失或格式不正确。
400	StartDate Invalid, Valid Format Is YYYY-MM-DD	startDate 参数格式错误，正确格式为 YYYY-MM-DD。
400	StatisticsType Invalid	statisticsType 参数的取值不是允许的选项。
401	Authorization Invalid	Authorization 头部缺失、错误或格式不正确。
403	StartDate Can't Be Greater Than EndDate	startDate 不能晚于 endDate。
404	Bucket xx Not Found	指定的 bucket 不存在。

Python 示例代码

import datetime
import hmac
import base64
import requests
import json
from hashlib import sha256


class UsageApiDemo:
    def get_gmt_date(self):
        """生成当前时间的RFC1123格式。"""
        gmt_format = '%a, %d %b %Y %H:%M:%S GMT'
        return datetime.datetime.utcnow().strftime(gmt_format)


    def get_auth_string(self, username, apikey, date_str):
        """生成完整的‘Authorization’头部内容。"""
        # 步骤1：创建HMAC-SHA256签名。
        signature = hmac.new(apikey.encode('utf-8'), date_str.encode('utf-8'), sha256).digest()


        # 步骤2：对签名进行Base64编码生成“password”。
        password = base64.b64encode(signature).decode('utf-8')


        # 第3步：创建'username:password'字符串并进行Base64编码。
        combined_str = f"{username}:{password}"
        encoded_auth_str = base64.b64encode(combined_str.encode('utf-8')).decode('utf-8')


        # 第4步：在最终的Header值前加上'Basic '。
        return f"Basic {encoded_auth_str}"


    def send_request(self, url, headers, body_params):
        """发送POST请求至API并打印响应。"""
        try:
            response = requests.post(url, data=json.dumps(body_params), headers=headers)
            response.raise_for_status()  # 针对异常状态码抛出异常


            print(f"状态码: {response.status_code}")
            print("响应内容:")
            print(json.dumps(response.json(), indent=4))


        except requests.exceptions.RequestException as e:
            print(f"发生错误: {e}")


if __name__ == '__main__':
    # --- 用户配置 ---
    USERNAME = 'your_username'
    APIKEY = 'your_apikey'
    API_HOST = 'https://wos.cdnetworks.com'
    API_URI = '/api/usage/statistics'


    # --- 构建请求 ---
    api_demo = UsageApiDemo()


    # 1. 获取日期
    date_header = api_demo.get_gmt_date()


    # 2. 获取授权信息
    auth_header = api_demo.get_auth_string(USERNAME, APIKEY, date_header)


    # 3. 定义请求头
    request_headers = {
        'Date': date_header,
        'Authorization': auth_header,
        'Content-Type': 'application/json'
    }


    # 4. 定义 Body
    request_body = {
        "startDate": "2025-04-01",
        "endDate": "2025-04-02",
        "statisticsType": "storageSize",
        "storageType": "Standard"
    }


    # 5. 发送请求
    full_url = API_HOST + API_URI
    api_demo.send_request(full_url, request_headers, request_body)