tencent cloud

文档反馈

列出对象

最后更新时间:2022-02-18 16:08:50

    简介

    本文档提供关于列出对象操作相关的 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
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持