You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/SDK 参考/Harmony/对象接口/列举对象 V2/列举多版本对象（Harmony SDK）
列举多版本对象（Harmony SDK）
最近更新时间：2024.12.23 17:29:49首次发布时间：2024.12.23 17:29:49
我的收藏
有用
有用
无用
无用

该接口用于列举桶中的多版本对象。每次请求返回桶的部分多版本对象（单次请求最多 1000 个），可以使用请求参数作为选择标准来返回桶中对象的子集。

注意事项

列举多版本对象前，您需要具有 tos:ListBucket 权限，具体操作请参见 IAM 策略概述。

参数说明

参数

描述

prefix

本次查询结果的前缀。

delimiter

对对象名称进行分组的字符。

maxKeys

返回列举对象的最大数，默认值为 1000，取值范围为（0，1000]。

encodingType

对返回的内容进行编码并指定编码的类型。取值说明如下：

  • undefined：默认值，无编码。
  • 'url'：使用 URL 编码。

keyMarker

列举多版本对象的起始位置。设定从该值之后按字母排序返回对象列表。通常为上次请求返回的 NextKeyMarker 值。

versionIdMarker

与 keyMarker 配合使用，设定从该值之后按字典排序返回对版本对象列表。从上次列举结果中 NextVersionIDMarker 获取。

示例代码

简单列举

以下代码用于列举 bucketName 存储桶中最多 1000 个多版本对象。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

function printObjectVersions(data: ListObjectVersionsOutput) {
  console.log('Versions.length:', data.Versions.length);
  for (const obj of data.Versions) {
    console.log('Obj Key:', obj.Key);
    console.log('Obj Version ID:', obj.VersionId);
    console.log('Obj Last Modified:', obj.LastModified);
    console.log('Obj Is Latest Version:', obj.IsLatest);
  }
  console.log('DeleteMarkers.length:', data.DeleteMarkers.length);
  for (const deleteMarker of data.DeleteMarkers) {
    console.log('Delete Maker Key:', deleteMarker.Key);
    console.log('Delete Maker Version ID:', deleteMarker.VersionId);
    console.log('Delete Maker Last Modified:', deleteMarker.LastModified);
    console.log('Delete Maker Is Latest Version:', deleteMarker.IsLatest);
  }
}

async function main() {
  try {
    // 获取 bucket 中最多 1000 个对象
    const res = await client.listObjectVersions({
      Bucket: bucketName,
      MaxKeys: 1000,
    });
    printObjectVersions(res);
  } catch (error) {
    handleError(error);
  }
}

main()

列举指定前缀的所有对象

以下代码用于列举 bucketName 存储桶 prefix 前缀的所有多版本对象。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

function printObjectVersions(data: ListObjectVersionsOutput) {
  console.log('Versions.length:', data.Versions.length);
  for (const obj of data.Versions) {
    console.log('Obj Key:', obj.Key);
    console.log('Obj Version ID:', obj.VersionId);
    console.log('Obj Last Modified:', obj.LastModified);
    console.log('Obj Is Latest Version:', obj.IsLatest);
  }
  console.log('DeleteMarkers.length:', data.DeleteMarkers.length);
  for (const deleteMarker of data.DeleteMarkers) {
    console.log('Delete Maker Key:', deleteMarker.Key);
    console.log('Delete Maker Version ID:', deleteMarker.VersionId);
    console.log('Delete Maker Last Modified:', deleteMarker.LastModified);
    console.log('Delete Maker Is Latest Version:', deleteMarker.IsLatest);
  }
}

const bucketName = 'harmonyos-sdk-test-bucket';
async function main() {
  try {
    // 列举指定前缀的所有多版本对象
    const prefix = '*** Provide your object key prefix ***';
    let keyMarker = ''
    let versionIdMarker = '';
    while (true) {
      const res = await client.listObjectVersions({
        Bucket: bucketName,
        MaxKeys: 1000,
        Prefix: prefix,
        KeyMarker: keyMarker,
        VersionIDMarker: versionIdMarker,
      });
      printObjectVersions(res);
      if (!res.IsTruncated) {
        break;
      }

      keyMarker = res.NextKeyMarker ?? '';
      versionIdMarker = res.NextVersionIdMarker ?? '';
    }
  } catch (error) {
    handleError(error);
  }
}

main()

列举所有对象

以下代码用于列举 bucketName 桶内所有多版本对象。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

function printObjectVersions(data: ListObjectVersionsOutput) {
  console.log('Versions.length:', data.Versions.length);
  for (const obj of data.Versions) {
    console.log('Obj Key:', obj.Key);
    console.log('Obj Version ID:', obj.VersionId);
    console.log('Obj Last Modified:', obj.LastModified);
    console.log('Obj Is Latest Version:', obj.IsLatest);
  }
  console.log('DeleteMarkers.length:', data.DeleteMarkers.length);
  for (const deleteMarker of data.DeleteMarkers) {
    console.log('Delete Maker Key:', deleteMarker.Key);
    console.log('Delete Maker Version ID:', deleteMarker.VersionId);
    console.log('Delete Maker Last Modified:', deleteMarker.LastModified);
    console.log('Delete Maker Is Latest Version:', deleteMarker.IsLatest);
  }
}

const bucketName = 'harmonyos-sdk-test-bucket';
async function main() {
  try {
    // 列举指定前缀的所有多版本对象
    let keyMarker = ''
    let versionIdMarker = '';
    while (true) {
      const res = await client.listObjectVersions({
        Bucket: bucketName,
        MaxKeys: 1000,
        KeyMarker: keyMarker,
        VersionIDMarker: versionIdMarker,
      });
      printObjectVersions(res);
      if (!res.IsTruncated) {
        break;
      }

      keyMarker = res.NextKeyMarker ?? '';
      versionIdMarker = res.NextVersionIdMarker ?? '';
    }
  } catch (error) {
    handleError(error);
  }
}

main()

递归列举目录下的对象和子目录

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

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

以下代码用于递归列举bucketName存储桶根目录下的对象和子目录，列举时，会返回所有版本的对象，只返回最新版本的目录。

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: "Provide your ak", 
  accessKeySecret: "Provide your sk", 
  securityToken: 'Provide your securityToken',
  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);
  }
}

function printObjectVersions(data: ListObjectVersionsOutput) {
  console.log('Versions.length:', data.Versions.length);
  for (const obj of data.Versions) {
    console.log('Obj Key:', obj.Key);
    console.log('Obj Version ID:', obj.VersionId);
    console.log('Obj Last Modified:', obj.LastModified);
    console.log('Obj Is Latest Version:', obj.IsLatest);
  }
  console.log('DeleteMarkers.length:', data.DeleteMarkers.length);
  for (const deleteMarker of data.DeleteMarkers) {
    console.log('Delete Maker Key:', deleteMarker.Key);
    console.log('Delete Maker Version ID:', deleteMarker.VersionId);
    console.log('Delete Maker Last Modified:', deleteMarker.LastModified);
    console.log('Delete Maker Is Latest Version:', deleteMarker.IsLatest);
  }
}

async function main() {
  try {
    // 列举所有多版本对象
    let keyMarker = '';
    let versionIdMarker = '';
    while (true) {
      const res = await client.listObjectVersions({
        Bucket: bucketName,
        MaxKeys: 1000,
        KeyMarker: keyMarker,
        VersionIDMarker: versionIdMarker,
        Delimiter: '/',
      });

      // 打印根目录下的子目录
      console.log('Sub Dir Length:', res.CommonPrefixes.length);
      for (const prefix of res.CommonPrefixes) {
        console.log('Sub Dir:', prefix.Prefix);
      }
      // 打印根目录下的多版本对象
      printObjectVersions(res);

      if (!res.IsTruncated) {
        break;
      }
      keyMarker = res.NextKeyMarker ?? '';
      versionIdMarker = res.NextVersionIdMarker ?? '';
    }
  } catch (error) {
    handleError(error);
  }
}

main()

相关文档

关于列举多版本对象的 API 文档，请参见 ListObjectsVersions。