如何使用Harmony SDK列舉檔案 - Object Storage Service

本文介紹如何使用OSS Harmony SDK列舉指定儲存空間（Bucket）下的所有檔案。

注意事項

關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。
要列舉檔案，您必須有oss:ListObjects許可權。具體操作，請參見為RAM使用者授予自訂的權限原則。

範例程式碼

您可以通過以下範例程式碼，使用ListObjectsV2介面列舉指定Bucket下的檔案。

import Client, { RequestError } from '@aliyun/oss';

// 建立OSS用戶端執行個體
const client = new Client({
  // 請替換為STS臨時訪問憑證的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 請替換為STS臨時訪問憑證的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 請替換為STS臨時訪問憑證的Security Token
  securityToken: 'yourSecurityToken',
  // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

/**
 * 列出Bucket中的對象。
 * 使用listObjectsV2方法列出指定Bucket中的對象及其元資訊。
 */
const listObjectsV2 = async () => {
  try {
    // 調用listObjectsV2方法列出指定Bucket中的對象及其元資訊
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // Bucket名稱，請替換為您實際使用的Bucket名稱
    });

    // 列印列出的對象及其元資訊
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕獲請求過程中的異常資訊
    if (err instanceof RequestError) {
      // 如果是已知類型的錯誤，則列印錯誤碼、錯誤訊息、請求ID、狀態代碼、EC碼等資訊
      console.log('code: ', err.code); // 錯誤碼
      console.log('message: ', err.message); // 錯誤訊息
      console.log('requestId: ', err.requestId); // 請求ID
      console.log('status: ', err.status); // HTTP狀態代碼
      console.log('ec: ', err.ec); // 錯誤碼
    } else {
      // 列印其他未知類型的錯誤
      console.log('unknown error: ', err);
    }
  }
};

// 調用listObjectsV2函數執行列出Bucket中對象的操作
listObjectsV2();

常見使用情境

列舉指定Prefix的檔案

import Client, { RequestError } from '@aliyun/oss';

// 建立OSS用戶端執行個體
const client = new Client({
  // 請替換為RAM使用者的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 請替換為RAM使用者的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 填寫Bucket所在的地區。例如，華東1（杭州）的Region為'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',
});


/**
 * 列出Bucket中以指定首碼開頭的對象。
 * 使用listObjectsV2方法並指定prefix參數來過濾對象。
 */
const listObjectsV2WithPrefix = async () => {
  try {
    // 調用listObjectsV2方法列出指定Bucket中以指定首碼開頭的對象
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // Bucket名稱，請替換為您實際使用的Bucket名稱
      prefix: 'objectNamePrefix', // 對象名稱首碼，請替換為您實際的首碼
    });

    // 列印列出的對象及其元資訊
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕獲請求過程中的異常資訊
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // 錯誤碼
      console.log('message: ', err.message); // 錯誤訊息
      console.log('requestId: ', err.requestId); // 請求ID
      console.log('status: ', err.status); // HTTP狀態代碼
      console.log('ec: ', err.ec); // 錯誤碼
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// 調用listObjectsV2WithPrefix函數執行列出以指定首碼開頭的對象的操作
listObjectsV2WithPrefix();

列舉指定Delimiter的檔案

import Client, { RequestError } from '@aliyun/oss';

// 建立OSS用戶端執行個體
const client = new Client({
  // 請替換為RAM使用者的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 請替換為RAM使用者的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 填寫Bucket所在的地區。例如，華東1（杭州）的Region為'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',
});


/**
 * 列出Bucket中的對象並使用分隔字元。
 * 使用listObjectsV2方法並指定delimiter參數來類比檔案夾結構。
 */
const listObjectsV2WithDelimiter = async () => {
  try {
    // 調用listObjectsV2方法列出指定Bucket中的對象，並使用分隔字元類比檔案夾結構
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // Bucket名稱，請替換為您實際使用的Bucket名稱
      delimiter: '/', // 分隔字元，通常用於類比檔案夾結構
    });

    // 列印列出的對象及其元資訊
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕獲請求過程中的異常資訊
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // 錯誤碼
      console.log('message: ', err.message); // 錯誤訊息
      console.log('requestId: ', err.requestId); // 請求ID
      console.log('status: ', err.status); // HTTP狀態代碼
      console.log('ec: ', err.ec); // 錯誤碼
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// 調用listObjectsV2WithDelimiter函數執行列出對象並使用分隔字元的操作
listObjectsV2WithDelimiter();

分頁列舉所有檔案

import Client, { RequestError } from '@aliyun/oss';

// 建立OSS用戶端執行個體
const client = new Client({
  // 請替換為RAM使用者的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 請替換為RAM使用者的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 填寫Bucket所在的地區。例如，華東1（杭州）的Region為'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',
});


/**
 * 分頁列出Bucket中的對象。
 * 使用listObjectsV2方法並結合continuationToken參數實現分頁列出對象。
 */
const listObjectsV2WithContinuationToken = async () => {
  try {
    let continuationToken: string | undefined; // 分頁標記，初始為空白
    let isTruncated = true; // 是否還有更多個物件需要列出

    // 迴圈列出對象，直到沒有更多個物件為止
    while (isTruncated) {
      const res = await client.listObjectsV2({
        bucket: 'yourBucketName', // Bucket名稱，請替換為您實際使用的Bucket名稱
        continuationToken, // 分頁標記，用於擷取下一頁資料
      });

      // 列印當前頁的對象及其元資訊
      console.log(JSON.stringify(res));

      // 更新分頁狀態
      isTruncated = res.data.isTruncated; // 是否還有更多個物件
      continuationToken = res.data.nextContinuationToken; // 下一頁的分頁標記
    }
  } catch (err) {
    // 捕獲請求過程中的異常資訊
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // 錯誤碼
      console.log('message: ', err.message); // 錯誤訊息
      console.log('requestId: ', err.requestId); // 請求ID
      console.log('status: ', err.status); // HTTP狀態代碼
      console.log('ec: ', err.ec); // 錯誤碼
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// 調用listObjectsV2WithContinuationToken函數執行分頁列出對象的操作
listObjectsV2WithContinuationToken();

列舉檔案並擷取所有者資訊

import Client, { RequestError } from '@aliyun/oss';

// 建立OSS用戶端執行個體
const client = new Client({
  // 請替換為RAM使用者的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 請替換為RAM使用者的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 填寫Bucket所在的地區。例如，華東1（杭州）的Region為'oss-cn-hangzhou'
  region: 'oss-cn-hangzhou',
});

/**
 * 列出Bucket中的對象並擷取對象的所有者資訊。
 * 使用listObjectsV2方法並指定fetchOwner參數來擷取對象的所有者資訊。
 */
const listObjectsV2WithFetchOwner = async () => {
  try {
    // 調用listObjectsV2方法列出指定Bucket中的對象，並擷取對象的所有者資訊
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // Bucket名稱，請替換為您實際使用的Bucket名稱
      fetchOwner: true, // 是否擷取對象的所有者資訊
    });

    // 列印列出的對象及其元資訊
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕獲請求過程中的異常資訊
    if (err instanceof RequestError) {
      console.log('code: ', err.code); // 錯誤碼
      console.log('message: ', err.message); // 錯誤訊息
      console.log('requestId: ', err.requestId); // 請求ID
      console.log('status: ', err.status); // HTTP狀態代碼
      console.log('ec: ', err.ec); // 錯誤碼
    } else {
      console.log('unknown error: ', err);
    }
  }
};

// 調用listObjectsV2WithFetchOwner函數執行列出對象並擷取所有者資訊的操作
listObjectsV2WithFetchOwner();