列举对象 V2（Node.js SDK）--对象存储-火山引擎

文档中心

立即注册

导航

列举对象 V2（Node.js SDK）

最近更新时间：2024.02.04 18:31:10首次发布时间：2023.12.19 18:47:29

本文介绍如何通过 listObjectsType2 列举指定桶下的所有对象、指定前缀文件、指定目录下的文件和子目录。

注意事项

ListObjects 接口已经修订为 ListObjectsType2，强烈建议开发者使用 ListObjectsType2。为保障向后兼容性，TOS 继续支持 ListObjects 接口。
使用列举对象 V2，您必须具有 tos:ListBucket 权限，具体操作，请参见 IAM 策略概述。

参数说明

ListObjectsType2 支持的参数如下:

参数	描述
Prefix	本次查询结果的前缀。
Delimiter	对对象名称进行分组的字符。
StartAfter	此次列举对象的起点。
ContinuationToken	指定列举操作需要从此 token 开始。可从上次列举结果中的 NextContinuationToken 中获取。
MaxKeys	返回列举对象的最大数，默认值为 1000。取值：大于 0 小于等于 1000。
EncodingType	对返回的内容进行编码并指定编码的类型。取值说明如下： `undefined`：默认值，无编码。 `'url'`：进行 url 编码。

示例代码

简单列举

以下代码用于列举指定存储桶获取最多 10 个对象。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
async function main() {
  try {
    // 获取 bucket 中最多 10 个对象
    const { data } = await client.listObjectsType2({
      bucket: bucketName,
      maxKeys: 1000,
    });
    for (const obj of data.Contents) {
      // 对象 Key
      console.log('Object Key:', obj.Key);
      // 对象最后修改时间
      console.log('Object LastModified:', obj.LastModified);
      // 对象 Etag
      console.log('Object ETag:', obj.ETag);
      // 对象大小
      console.log('Object Size:', obj.Size);
      // 对象 Owner
      console.log('Object Owner:', obj.Owner);
      // 对象存储类型
      console.log('Object StorageClass:', obj.StorageClass);
      // 对象 CRC64
      console.log('Object HashCrc64ecma:', obj.HashCrc64ecma);
    }
  } catch (error) {
    handleError(error);
  }
}

main();

分页列举

以下代码用于分页列举指定存储桶中的对象。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
async function main() {
  try {
    // 获取 bucket 中前 1000 个对象
    const { data } = await client.listObjectsType2({
      bucket: bucketName,
      maxKeys: 1000,
    });
    printObjectContents(data.Contents);

    // 分页列举后 1000 个对象
    const { data: data2 } = await client.listObjectsType2({
      bucket: bucketName,
      maxKeys: 1000,
      continuationToken: data.NextContinuationToken,
    });
    printObjectContents(data2.Contents);
  } catch (error) {
    handleError(error);
  }
}

function printObjectContents(contents) {
  console.log('Contents Length:', contents.length);

  for (const obj of contents) {
    // 对象 Key
    console.log('Object Key:', obj.Key);
    // 对象最后修改时间
    console.log('Object LastModified:', obj.LastModified);
    // 对象 Etag
    console.log('Object ETag:', obj.ETag);
    // 对象大小
    console.log('Object Size:', obj.Size);
    // 对象 Owner
    console.log('Object Owner:', obj.Owner);
    // 对象存储类型
    console.log('Object StorageClass:', obj.StorageClass);
    // 对象 CRC64
    console.log('Object HashCrc64ecma:', obj.HashCrc64ecma);
  }
}

main();

列举指定前缀的所有对象

以下代码用于列举指定存储桶指定前缀的所有对象。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
async function main() {
  try {
    const prefix = '*** Provide your object key prefix ***';
    for (let truncated = true, continuationToken = ''; truncated; ) {
      const { data } = await client.listObjectsType2({
        bucket: bucketName,
        maxKeys: 1000,
        continuationToken: continuationToken,
        prefix,
      });
      printObjectContents(data.Contents);

      truncated = data.IsTruncated;
      continuationToken = data.NextContinuationToken;
    }
  } catch (error) {
    handleError(error);
  }
}

function printObjectContents(contents) {
  console.log('Contents Length:', contents.length);

  for (const obj of contents) {
    // 对象 Key
    console.log('Object Key:', obj.Key);
    // 对象最后修改时间
    console.log('Object LastModified:', obj.LastModified);
    // 对象 Etag
    console.log('Object ETag:', obj.ETag);
    // 对象大小
    console.log('Object Size:', obj.Size);
    // 对象 Owner
    console.log('Object Owner:', obj.Owner);
    // 对象存储类型
    console.log('Object StorageClass:', obj.StorageClass);
    // 对象 CRC64
    console.log('Object HashCrc64ecma:', obj.HashCrc64ecma);
  }
}

main();

分页列举桶内所有对象

以下代码用于列举指定存储桶中所有对象。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
async function main() {
  try {
    for (let truncated = true, continuationToken = ''; truncated; ) {
      const { data } = await client.listObjectsType2({
        bucket: bucketName,
        maxKeys: 1000,
        continuationToken: continuationToken,
      });
      printObjectContents(data.Contents);


      truncated = data.IsTruncated;
      continuationToken = data.NextContinuationToken;
    }
  } catch (error) {
    handleError(error);
  }
}

function printObjectContents(contents) {
  console.log('Contents Length:', contents.length);

  for (const obj of contents) {
    // 对象 Key
    console.log('Object Key:', obj.Key);
    // 对象最后修改时间
    console.log('Object LastModified:', obj.LastModified);
    // 对象 Etag
    console.log('Object ETag:', obj.ETag);
    // 对象大小
    console.log('Object Size:', obj.Size);
    // 对象 Owner
    console.log('Object Owner:', obj.Owner);
    // 对象存储类型
    console.log('Object StorageClass:', obj.StorageClass);
    // 对象 CRC64
    console.log('Object HashCrc64ecma:', obj.HashCrc64ecma);
  }
}

main();

TOS 只有对象的概念, 可通过创建一个大小为 0 并且以斜线 / 结尾的对象, 模拟目录的功能。
通过 delimiter和 prefix 两个参数可以模拟目录的功能:

首先设置 delimiter 为 / 同时设置 prefix 为空, 可返回根目录下的对象和子目录信息。
在设置 delimiter 为 / 同时设置 prefix 为子目录(subfiledir), 可返回子目录的对象和次级目录。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

const bucketName = 'node-sdk-test-bucket';
async function main() {
  try {
    // 列举目录下的文件和子目录
    for (let truncated = true, continuationToken = ''; truncated; ) {
      const { data } = await client.listObjectsType2({
        bucket: bucketName,
        maxKeys: 1000,
        continuationToken: continuationToken,
        delimiter: '/',
      });

      console.log('Sub Dir Length:', data.CommonPrefixes.length);
      for (const prefix of data.CommonPrefixes) {
        console.log('Sub Dir:', prefix.Prefix);
      }

      printObjectContents(data.Contents);
      truncated = data.IsTruncated;
      continuationToken = data.NextContinuationToken;
    }
  } catch (error) {
    handleError(error);
  }
}

function printObjectContents(contents) {
  console.log('Contents Length:', contents.length);

  for (const obj of contents) {
    // 对象 Key
    console.log('Object Key:', obj.Key);
    // 对象最后修改时间
    console.log('Object LastModified:', obj.LastModified);
    // 对象 Etag
    console.log('Object ETag:', obj.ETag);
    // 对象大小
    console.log('Object Size:', obj.Size);
    // 对象 Owner
    console.log('Object Owner:', obj.Owner);
    // 对象存储类型
    console.log('Object StorageClass:', obj.StorageClass);
    // 对象 CRC64
    console.log('Object HashCrc64ecma:', obj.HashCrc64ecma);
  }
}

main();

对象存储