简介
本文介绍对象存储 COS 通过 JavaScript SDK 实现列出对象功能的示例代码和描述。
注意事项
若您要使用列出对象功能,需要先具有目标桶的读取权限:在您进行 授权策略 时,action 需要设置为
cos:GetBucket
,更多授权请参见 支持CAM的业务接口。若您要使用列出对象历史版本功能,需要先具有目标桶的读取权限:在您进行 授权策略 时,action 需要设置为
cos:GetBucketObjectVersions
,更多授权请参见 支持CAM的业务接口。前期准备
查询对象列表
功能说明
查询存储桶下的部分或者全部对象。
注意:
使用案例:列出目录 a 的所有文件
cos.getBucket({Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶,必须字段Region: 'COS_REGION', // 存储桶所在地域,例如ap-beijing,必须字段Prefix: 'a/', // Prefix表示列出的object的key以prefix开始,非必须}, function(err, data) {console.log(err || data.Contents);});
返回值格式:
{"Name": "examplebucket-1250000000","Prefix": "a/","Marker": "","MaxKeys": "1000","IsTruncated": "false","Contents": [{"Key": "a/3mb.zip","LastModified": "2018-10-18T07:08:03.000Z","ETag": "\\"05a9a30179f3db7b63136f30aa6aacae-3\\"","Size": "3145728","Owner": {"ID": "1250000000","DisplayName": "1250000000"},"StorageClass": "STANDARD"}],"StatusCode": 200,"Headers": {}}
使用案例:列出目录 a 的文件,不深度遍历
cos.getBucket({Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶,必须字段Region: 'COS_REGION', // 存储桶所在地域,例如ap-beijing,必须字段Prefix: 'a/', // Prefix表示列出的object的key以prefix开始,非必须Delimiter: '/', // Deliter表示分隔符, 设置为/表示列出当前目录下的object, 设置为空表示列出所有的object,非必须}, function(err, data) {console.log(err || data.CommonPrefixes);});
返回值格式:
{"Name": "examplebucket-1250000000","Prefix": "a/","Marker": "","MaxKeys": "1000","Delimiter": "/","IsTruncated": "false","CommonPrefixes": [{"Prefix": "a/1/"}],"Contents": [{"Key": "a/3mb.zip","LastModified": "2018-10-18T07:08:03.000Z","ETag": "\\"05a9a30179f3db7b63136f30aa6aacae-3\\"","Size": "3145728","Owner": {"ID": "1250000000","DisplayName": "1250000000"},"StorageClass": "STANDARD"}],"StatusCode": 200,"Headers": {}}
使用案例:目录下所有文件
var listFolder = function(marker) {cos.getBucket({Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶,必须字段Region: 'COS_REGION', // 存储桶所在地域,例如ap-beijing,必须字段Prefix: 'a/', // Prefix表示列出的object的key以prefix开始,非必须Marker: marker,MaxKeys: 1000,}, function(err, data) {if (err) {return console.log('list error:', err);} else {console.log('list result:', data.Contents);// 列表文件很多的情况下 注意性能影响if (data.IsTruncated === 'true') listFolder(data.NextMarker);else return console.log('list complete');}});};listFolder();
参数说明
入参说明
参数名 | 参数描述 | 类型 | 是否必填 |
Bucket | 存储桶的名称,命名规则为 BucketName-APPID,此处填写的存储桶名称必须为此格式 | String | 是 |
Region | String | 是 | |
Prefix | 对象键前缀匹配,限定返回中只包含指定前缀的对象键 | String | 否 |
Delimiter | 定界符。为一个分隔符号,用于对对象键进行分组。一般是传 / 。所有对象键从 Prefix 或从头(如未指定 Prefix)到首个 delimiter 之间相同部分的路径归为一类,定义为 Common Prefix,然后列出所有 Common Prefix | String | 否 |
Marker | 起始对象键标记,列出从 Marker 开始 MaxKeys 条目,默认顺序为 UTF-8 字典序 | String | 否 |
MaxKeys | 单次返回最大的条目数量,默认1000,最大为1000 | String | 否 |
EncodingType | 规定返回值的编码方式,可选值:url,代表返回的对象键为 URL 编码(百分号编码)后的值,例如“腾讯云”将被编码为 %E8%85%BE%E8%AE%AF%E4%BA%91 | String | 否 |
回调函数说明
function(err, data) { ... }
参数名 | 参数描述 | 类型 |
err | Object | |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
data | 请求成功时返回的对象,如果请求发生错误,则为空 | Object |
- headers | 请求返回的头部信息 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- RequestId | 请求 id | String |
- Name | 存储桶的名称,格式为 BucketName-APPID,例如 examplebucket-1250000000 | String |
- Prefix | 对象键前缀匹配,从该标记之后(不含)按照 UTF-8 字典序返回对象键条目 | String |
- Marker | 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 Marker 开始 | String |
- MaxKeys | 单次响应请求内返回结果的最大的条目数量 | String |
- Delimiter | 定界符 | String |
- IsTruncated | 响应请求条目是否被截断,值为 'true' 或者 'false' | String |
- NextMarker | 假如返回条目被截断,则返回 NextMarker 表示下一个条目的起点 | String |
- CommonPrefixes | 将 Prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix | ObjectArray |
- - Prefix | 单条 Common Prefix 的前缀 | String |
- EncodingType | 返回值的编码方式,作用于 Delimiter,Marker,Prefix,NextMarker,Key | String |
- Contents | 对象元数据信息列表 | ObjectArray |
- - Key | 对象键,即对象的名称 | String |
- - ETag | 根据对象内容计算出的 MD5 算法校验值, 例如 "22ca88419e2ed4721c23807c678adbe4c08a7880" ,注意前后携带双引号 | String |
- - Size | 对象大小,单位 Byte | String |
- - LastModified | 对象最后修改时间,为 ISO8601 格式,例如2019-05-24T10:56:40Z | String |
- - Owner | 对象持有者信息 | Object |
- - - ID | 对象持有者的完整 ID,格式为 qcs::cam::uin/[OwnerUin]:uin/[OwnerUin] ,例如 qcs::cam::uin/100000000001:uin/100000000001 ,其中100000000001为 uin | String |
- - - DisplayName | 对象持有者的名称 | String |
- - StorageClass | String |
查询对象历史版本列表
功能说明
查询开启版本控制的存储桶下的部分或者全部对象。
使用案例
查询对象历史版本列表
function listObjectVersions() {cos.listObjectVersions({Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶,必须字段Region: 'COS_REGION', // 存储桶所在地域,例如ap-beijing,必须字段Prefix: 'a/', // Prefix表示列出的object的key以prefix开始,非必须},function (err, data) {console.log(err || data);},);}listObjectVersions();
参数说明
入参说明
参数名 | 参数描述 | 类型 | 是否必填 |
Bucket | 存储桶的名称,命名规则为 BucketName-APPID,此处填写的存储桶名称必须为此格式 | String | 是 |
Region | String | 是 | |
Prefix | 对象键前缀匹配,限定返回中只包含指定前缀的对象键 | String | 否 |
Delimiter | 定界符。为一个分隔符号,用于对对象键进行分组。一般是传 / 。所有对象键从 Prefix 或从头(如未指定 Prefix)到首个 delimiter 之间相同部分的路径归为一类,定义为 Common Prefix,然后列出所有 Common Prefix | String | 否 |
KeyMarker | 起始对象键标记。列出从 Marker 开始 MaxKeys 条目,默认顺序为 UTF-8 字典序 | String | 否 |
MaxKeys | 单次返回最大的条目数量,默认1000,最大为1000 | String | 否 |
VersionIdMarker | 起始版本 ID 标记,从该标记之后(不含)返回对象版本条目,如果上一次 List 结果的 NextVersionIdMarker 为空,则该参数也指定为空 | String | 否 |
EncodingType | 规定返回值的编码方式,可选值:url,代表返回的对象键为 URL 编码(百分号编码)后的值,例如“腾讯云”将被编码为 %E8%85%BE%E8%AE%AF%E4%BA%91 | String | 否 |
回调函数说明
function(err, data) { ... }
参数名 | 参数描述 | 类型 |
err | Object | |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
data | 请求成功时返回的对象,如果请求发生错误,则为空 | Object |
- headers | 请求返回的头部信息 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- RequestId | 请求 id | String |
- EncodingType | 编码格式,对应请求中的 encoding-type 参数,且仅当请求中指定了 encoding-type 参数才会返回该节点 | String |
- Name | 存储桶的名称,格式为 <BucketName-APPID>,例如 examplebucket-1250000000 | String |
- Prefix | 对象键前缀匹配,从该标记之后(不含)按照 UTF-8 字典序返回对象键条目 | String |
- KeyMarker | 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 Marker 开始 | String |
- VersionIdMarker | 起始版本 ID 标记,从该标记之后(不含)返回对象版本条目,对应请求中的 version-id-marker 参数 | String |
- MaxKeys | 单次响应请求内返回结果的最大的条目数量 | String |
- IsTruncated | 响应请求条目是否被截断,值为 'true' 或者 'false' | String |
- NextKeyMarker | 仅当响应条目有截断(IsTruncated 为 'true')才会返回该节点,该节点的值为当前响应条目中的最后一个对象键,当需要继续请求后续条目时,将该节点的值作为下一次请求的 key-marker 参数传入 | String |
- NextVersionIdMarker | 仅当响应条目有截断(IsTruncated 为 'true')才会返回该节点,该节点的值为当前响应条目中的最后一个对象的版本 ID,当需要继续请求后续条目时,将该节点的值作为下一次请求的 version-id-marker 参数传入。该节点的值可能为空,此时下一次请求的 version-id-marker 参数也需要指定为空 | String |
- Delimiter | 分隔符,对应请求中的 delimiter 参数,且仅当请求中指定了 delimiter 参数才会返回该节点 | String |
- CommonPrefixes | 从 prefix 或从头(如未指定 prefix)到首个 delimiter 之间相同的部分,定义为 Common Prefix。仅当请求中指定了 delimiter 参数才有可能返回该节点 | ObjectArray |
- - Prefix | 单条 Common Prefix 的前缀 | String |
- Versions | 对象版本条目 | Container |
- DeleteMarkers | 对象删除标记条目 | Container |
Container 节点 Versions 的内容:
节点名称(关键字) | 父节点 | 描述 | 类型 |
Key | data.Versions | 对象键 | string |
VersionId | data.Versions | 对象的版本 ID 当未启用版本控制时,该节点的值为空字符串 当启用版本控制时,启用版本控制之前的对象,其版本 ID 为 null 当暂停版本控制时,新上传的对象其版本 ID 为 null,且同一个对象最多只存在一个版本 ID 为 null 的对象版本 | string |
IsLatest | data.Versions | 当前版本是否为该对象的最新版本 | boolean |
LastModified | data.Versions | 当前版本的最后修改时间,为 ISO8601 格式,例如2019-05-24T10:56:40Z | date |
ETag | data.Versions | 对象的实体标签(Entity Tag),是对象被创建时标识对象内容的信息标签,可用于检查对象的内容是否发生变化 例如"8e0b617ca298a564c3331da28dcb50df"。此头部并不一定返回对象的 MD5 值,而是根据对象上传和加密方式而有所不同 | string |
Size | data.Versions | 对象大小,单位为 Byte | integer |
StorageClass | data.Versions | Enum | |
StorageTier | data.Versions | 当对象存储类型为智能分层存储时,指示对象当前所处的存储层,枚举值:FREQUENT(标准层),INFREQUENT(低频层)。仅当 StorageClass 为 INTELLIGENT_TIERING(智能分层)时才会返回该节点 | Enum |
Owner | data.Versions | 对象持有者信息 | Container |
Container 节点 Versions.Owner 的内容:
节点名称(关键字) | 父节点 | 描述 | 类型 |
ID | data.Versions.Owner | 对象持有者的 APPID | string |
DisplayName | data.Versions.Owner | 对象持有者的名称 | string |
Container 节点 DeleteMarkers 的内容:
节点名称(关键字) | 父节点 | 描述 | 类型 |
Key | data.DeleteMarkers | 对象键 | string |
VersionId | data.DeleteMarkers | 对象的删除标记的版本 ID | string |
IsLatest | data.DeleteMarkers | 当前删除标记是否为该对象的最新版本 | boolean |
LastModified | data.DeleteMarkers | 当前删除标记的删除时间,为 ISO8601 格式,例如2019-05-24T10:56:40Z | date |
Owner | data.DeleteMarkers | 对象持有者信息 | Container |
Container 节点 DeleteMarkers.Owner 的内容:
节点名称(关键字) | 父节点 | 描述 | 类型 |
ID | ListVersionsResult.DeleteMarker.Owner | 对象持有者的 APPID | string |
DisplayName | ListVersionsResult.DeleteMarker.Owner | 对象持有者的名称 | string |
API 操作
关于列出对象的 API 接口说明,请参见 List Objects 文档。
关于列出对象历史版本的 API 接口说明,请参见 List Object versions 文档。