全部文档
当前文档
最近更新时间：2026-04-21 14:47:25
用户可以通过KS3提供的QueryKs3TopData计量接口查询业务分析数据，包括以Object、Referer、IP、UA、Domain为统计维度，依据流量或请求次数排序的TOP200数据。使用该接口需要是桶拥有者或具有KS3BillFullAccess权限。
1. 该接口对应对象存储控制台“报表中心”的“业务分析”模块，您也可以登录对象存储控制台查看相应数据。
2. 该接口可能存在数据同步延迟。为确保您查询到的数据是最新的，建议在每日上午9:30之后进行数据查询。
3. 该接口仅支持查询昨日及更早的数据，当日数据暂不支持查询。
计量API访问地址为：ks3bill.api.ksyun.com，支持HTTP和HTTPS访问。
主账号和具有对象存储计量权限的子账号，可以访问计量API，计量API支持GET方法发送请求。
参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
Service | String | 是 | 服务名称，固定值：ks3bill |
Action | String | 是 | 操作接口名，固定值：QueryKs3TopData |
Version | String | 是 | 接口版本号，固定值：v1 |
Signature | String | 是 | 计量API使用V4签名方式，具体参见签名机制 |
参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
StartTime | String | 是 | 查询用量开始时间：yyyyMMddHHmm。
 1. StartTime和EndTime必须在同一个月。 2. 精确到分钟级别。 |
EndTime | String | 是 | 查询用量结束时间（与开始时间同月，不支持跨月查询）：yyyyMMddHHmm。
1. StartTime和EndTime必须在同一个月。 2. 精确到分钟级别。 |
DateType | String | 是 | 仅支持按天粒度查询，固定值：Day。 |
Bucketname | String | 是 | 存储空间名称，最多支持同时查询5个存储桶的用量明细，以逗号分隔。 |
Transfer | String | 否 | 可以查询单个或多个统计项的流量情况，以逗号分隔。可填参数：Object、Referer、IP、UA、Domain，返回TOP200数据。 |
Request | String | 否 | 可以查询单个或多个统计项的请求次数情况，以逗号分隔。可填参数：Object、Referer、IP、UA、Domain，返回TOP200数据。 |
TopDataSource | String | 否 | 指定流量或请求次数对应的统计来源，仅支持选择外网下行、CDN回源，不选该参数默认返回外网下行+内网下行数值，取值如下：
|
TopDataStorageClass | String | 否 | 指定流量或请求次数对应的存储类型，支持选择标准、低频、归档类型，不选择该参数时默认返回标准+低频+归档类型数据，取值如下：
|
参数名称 | 描述 | 类型 |
|---|---|---|
Data | 包含一个或多个Bucket的容器。
| container |
Buckets | 包含Bucket信息的容器。
| container |
Name | Bucket的名称。
| String |
StartTime | 数据开始时间。
| String |
EndTime | 数据结束时间。
| String |
Transfer | Object、Referer、IP、UA、Domain产生的流量。
| 数组 |
Request | Object、Referer、IP、UA、Domain产生的请求次数。
| 数组 |
RequestId | 由KS3指定的唯一值，可用于解决KS3出现的问题。 | String |
GET /?Action=QueryKs3TopData&StartTime=202603230000&EndTime=202603242300&DateType=Day&Bucketname=testbucket&Transfer=Object,IP&Request=Object,IP&Service=ks3bill&Version=v1 HTTP/1.1
Host: ks3bill.api.ksyun.com
X-Amz-Date: 20211124T070940Z
Authorization: {SignatureValue}{
"Code": "OK",
"Message": "OK",
"Data": {
"Buckets": [
{
"Name": "testbucket",
"StartTime": "2026-03-23 00:00:00",
"EndTime": "2026-03-23 23:59:59",
"Transfer": {},
"Request": {}
},
{
"Name": "testbucket",
"StartTime": "2026-03-24 00:00:00",
"EndTime": "2026-03-24 23:00:00",
"Transfer": {
"Object": [
{
"object": "/v2-d1d4877f398cf32ed95b8bf1f30c52ff_r%20%281%29.jpg",
"traffic": "2701668.68"
}
],
"Ip": [
{
"ip": "111.124.202.153",
"traffic": "1350834.34"
},
{
"ip": "111.124.202.154",
"traffic": "1350834.34"
}
]
},
"Request": {
"Object": [
{
"object": "/v2-d1d4877f398cf32ed95b8bf1f30c52ff_r%20%281%29.jpg",
"times": "4.0"
}
],
"Ip": [
{
"ip": "111.124.202.153",
"times": "2.0"
},
{
"ip": "111.124.202.154",
"times": "2.0"
}
]
}
}
]
},
"RequestId": "1d87faf1-bdf8-473c-b4b6-3c1ecb0df308"
}主账号或者具有权限的子用户可以调用计量API，查询计量相关信息。
子用户配置权限的方法如下：
登录金山云访问控制控制台，为子用户添加策略。点击左侧子用户，选择要授权的子用户，点击添加权限，将系统策略“KS3BillFullAccess“授权给子用户。
错误码 | 错误信息 | 状态码 | 描述 |
|---|---|---|---|
SignatureDoesNotMatch | The Signature is not matched. | 400 | 签名不匹配 |
InvalidArgument | Invalid length of StartTime or EndTime. | 400 | 无效的日期格式 |
InvalidArgument | Invalid StartTime. | 400 | StartTime不合法 |
InvalidArgument | Invalid EndTime. | 400 | EndTime不合法 |
InvalidArgument | StartTime and EndTime should be in the same month. | 400 | StartTime和EndTime应在同一个月 |
InvalidArgument | The EndTime should be later than the StartTime. | 400 | 结束时间应晚于开始时间 |
InvalidArgument | The number of specified buckets can not exceed 5. | 400 | 最多支持查询5个桶的用量明细 |
InvalidArgument | Invalid DateType. | 400 | DateType不合法 |
InvalidAccessKey | Invalid Accesskey. | 400 | 无效的AccessKey |
纯净模式