接口介绍
查询存储桶内所有对象。
接口约束
支持的线上资源池 ：上海7、南京3、南京5、杭州2、合肥2、九江、广州6、武汉4、福州25、厦门3、郴州2、海口2、北京5、雄安2、石家庄20、内蒙6、晋中、辽阳1、西安5、乌鲁木齐4、乌鲁木齐27、中卫5、兰州2、西宁2、拉萨3、昆明2、重庆2、成都4、贵州3、上海33、宁波边缘云、华东1、上海36、南昌5、青岛20、武汉41、长沙42、长沙37、南宁23、北京行业云20、华北2、西南1、上海32。
URI
GET /v4/oss/list-objects
请求参数
请求 Query 参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| bucket | 是 | String | 桶名 | bucket1 |
| regionID | 是 | String | 区域 ID | 332232eb-63aa-465e-9028-52e5123866f0 |
| delimiter | 否 | String | 定界符是您用来对键进行分组的字符 | / |
| marker | 否 | String | 指示从哪里开始列出。ZOS会在这个指定的对象之后开始列出。标记可以是桶中的任何对象 | test1.txt |
| maxKeys | 否 | Integer | 一次返回keys的最大数目（默认值和上限为1000） | 100 |
| prefix | 否 | String | 返回的key的前缀 | test |
文件夹及文件查询方法 ：
可以将 prefix 设为文件夹名，就可以列出该文件夹下递归的所有的文件和子文件夹。文件名在 contents 中列出。 如果再把 delimiter 设置为 “/” 时，返回值就只列出该文件夹下的文件和子文件夹，除文件名在 contents 中列出外，该文件夹下的子文件夹在 commonPrefixes 中列出，子文件夹下递归的文件和文件夹不被显示。
假设桶内对象为
d1/
f1
d1/d2/
d1/f2
d1/f3
d1/d2/ff1
d1/d2/d3/
d1/dd2/
需要查询 d1/ 目录下的文件时，传入 prefix=d1/，delimiter=/，返回结果简写如下：
contents:[
{"key": "d1/"},
{"key": "d1/f2"},
{"key": "d1/f3"}
],
commonPrefixes:[
{"prefix": "d1/d2/"},
{"prefix": "d1/dd2/"}
]
即，contents 会返回当前目录下的文件，commonPrefixes 返回当前目录下的文件夹
响应参数
| 参数 | 参数类型 | 说明 | 示例 |
|---|---|---|---|
| statusCode | Integer | 返回码 取值范围：800 成功 |
800 |
| message | String | 状态描述 | SUCCESS |
| description | String | 状态描述，一般为中文 | 成功 |
| returnObj | Object | 响应对象 | 见下级对象 |
| errorCode | String | 业务细分码（仅失败时具有此参数），为product.module.code三段式码 | openapi.userPermission.accessFailed |
表 returnObj
| 参数 | 参数类型 | 说明 | 示例 |
|---|---|---|---|
| isTruncated | Boolean | 指示返回的分段列表是否被截断。值为 true 表示列表已被截断。 | true |
| marker | String | 指示存储桶列表中的开始位置。如果标记是随请求一起发送的，则标记包含在响应中。 | test1.txt |
| contents | Array of Objects | 对象的容器 | 见下级对象 |
| nextMarker | String | 下一个 Marker | test100.txt |
| name | String | 桶名 | bucket1 |
| prefix | String | 返回的key的前缀 | test |
| delimiter | String | 定界符是您用来对键进行分组的字符 | / |
| maxKeys | Integer | 一次返回keys的最大数目 | 100 |
| commonPrefixes | Array of Objects | 在计算返回数时，所有键（最多 1,000 个）汇总在一个公共前缀中计为单个返回。仅当指定分隔符时，响应才能包含 commonPrefixes | 见下级对象 |
| encodingType | String | 对响应中的对象键进行编码并指定要使用的编码方法，目前允许的值只有 url | url |
表 contents
| 参数 | 参数类型 | 说明 | 示例 |
|---|---|---|---|
| ETag | String | ETag | 70ee1738b6b21e2c8a43f3a5ab0eee71 |
| key | String | 对象名 | test1.txt |
| lastModified | String | 最后更改时间, ISO-8601 格式的日期字符串 | 2022-10-18T02:24:40Z |
| owner | Objects | 见下级对象 | |
| size | Integer | 大小 | 11 |
| storageClass | String | 存储类 | STANDARD |
表 owner
| 参数 | 参数类型 | 说明 | 示例 |
|---|---|---|---|
| displayName | String | 展示名 | myname |
| ID | String | 用户 ID | 12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc |
表 commonPrefixes
| 参数 | 参数类型 | 说明 | 示例 |
|---|---|---|---|
| prefix | String | 前缀 | test |
请求示例
GET https://zos-global.ctapi.ctyun.cn/v4/oss/list-objects?bucket=bucket1®ionID=332232eb-63aa-465e-9028-52e5123866f0&delimiter=%2F&marker=test1.txt&maxKeys=100&prefix=test
响应示例
{
"returnObj": {
"contents": [
{
"ETag": "70ee1738b6b21e2c8a43f3a5ab0eee71",
"key": "test1.txt",
"lastModified": "2022-10-18T02:24:40Z",
"owner": {
"displayName": "myname",
"ID": "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
"size": 11,
"storageClass": "STANDARD"
},
{
"ETag": "9c8af9a76df052144598c115ef33e511",
"key": "test2.jpg",
"lastModified": "2022-10-18T02:24:40Z",
"owner": {
"displayName": "myname",
"ID": "12345example25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
},
"size": 713193,
"storageClass": "STANDARD"
}
],
"nextMarker": "test100.txt"
},
"message": "SUCCESS",
"description": "成功",
"statusCode": 800
}
状态码
| 状态码 | 描述 |
|---|---|
| 800 | 表示请求成功。 |
| 900 | 表示请求失败。 |
错误码
errorCode 枚举值，见错误码总表
