有奖征文:轻量对象存储LighthouseCOS用户实践> HOT

简介

本文档提供关于列出对象操作相关的 API 概览以及 SDK 示例代码。
API
操作名
操作描述
查询对象列表
查询存储桶下的部分或者全部对象
查询对象及其历史版本列表
查询存储桶下的部分或者全部对象及其历史版本信息

查询对象列表

功能说明

查询存储桶下的部分或者全部对象。
注意
在 COS 中,列出的对象键为 project/,表示是一个内容为空的对象,展示方式上模拟了传统文件夹。相关介绍可参见 文件夹和目录

使用示例

示例一:列出目录 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",
"Delimiter": "",
"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
- 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
对象的存储类型,枚举值为:STANDARD、STANDARD_IA、ARCHIVE、DEEP_ARCHIVE,详情参见 存储类型 文档
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
- 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
- NextMarker
假如返回条目被截断,则返回 NextMarker 表示下一个条目的起点
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
对象存储类型。枚举值请参见 存储类型 文档,例如 STANDARD_IA,ARCHIVE
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