文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>对象存储>SDK 文档>Node.js SDK>对象操作>列出对象

列出对象

最近更新时间：2024-08-14 14:20:21

我的收藏

简介

本文介绍对象存储 COS 通过 Node.js SDK 实现列出对象功能的示例代码和描述。

注意事项

若您要使用列出对象功能，需要先具有目标桶的读取权限：在您进行 授权策略 时，action 需要设置为 cos:GetBucket ，更多授权请参见 支持CAM的业务接口。
若您要使用列出对象历史版本功能，需要先具有目标桶的读取权限：在您进行 授权策略 时，action 需要设置为 cos:GetBucketObjectVersions ，更多授权请参见 支持CAM的业务接口。

前期准备

开始使用前，确保您已经完成了 SDK 初始化。

查询对象列表

功能说明

查询存储桶下的部分或者全部对象。
注意:
在 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
- 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
对象存储类型。枚举值请参见 存储类型 文档，例如 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

API 操作

关于列出对象的 API 接口说明，请参见 List Objects 文档。
关于列出对象历史版本的 API 接口说明，请参见 List Object versions 文档。
中国站
目录