控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

简介

本文档提供关于列出对象操作相关的 API 概览以及 SDK 示例代码。

API 操作名 操作描述
GET Bucket(List Objects) 查询对象列表 查询存储桶下的部分或者全部对象

功能说明

查询存储桶下的部分或者全部对象。

注意:

在 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": "",
    "Marker": "a/",
    "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