文档首页/ 对象存储服务 OBS/ SDK参考/ Harmony（公测）/ 对象相关接口(HarmonyOS SDK)/ 基础操作/ 批量下载(HarmonyOS SDK)
更新时间：2026-08-28 GMT+08:00
查看PDF
分享

批量下载(HarmonyOS SDK)

功能说明

本示例用于将 OBS 桶内满足指定前缀的对象批量下载到本地目录。先通过 listObjects 列举满足前缀的对象，再利用 Promise.all 分批并发执行 getObject 请求，将对象下载到本地指定路径。

接口约束

  • 您必须是桶拥有者或拥有下载对象的权限，才能下载对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:GetObject权限，如果使用桶策略则需授予GetObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。
  • listObjects 单次最多返回 1000 个对象，对象数量超过 1000 时需通过 Marker 分页列举，直至 IsTruncated 为 false。
  • 使用 SaveFilePath 下载对象采用流式写入，内存占用为常数级，适合大文件批量下载。
  • 并发数不宜过大，避免占用过多内存与带宽，建议根据设备性能和网络情况设置。

方法定义

本接口为组合调用示例，基于 listObjects 与 getObject 接口实现批量下载。

1
2
 
listObjects(input: ListObjectsInput): Response<ListObjectsOutput>
getObject(input: GetObjectInput): Response<GetObjectOutput>

请求参数

本接口为组合调用示例，基于 getObject 接口实现批量操作，请求参数与 getObject 接口一致，详细参数说明请参见GetObjectInput参数表。

代码示例

本示例用于将 examplebucket 桶内前缀为 backup/ 的对象批量下载到本地目录 /path/to/localdir/，并发数设置为 3。

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
 
// 引入依赖包
import ObsClient, { ListObjectsInput, GetObjectInput } from '@obs/esdk-obs-harmony';
import { process } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { fileIo as fs } from '@kit.CoreFileKit';

const processManager = new process.ProcessManager();

// 创建ObsClient实例
const obsClient = new ObsClient({
  // 推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险
  // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
  AccessKeyId: processManager.getEnvironmentVar("ACCESS_KEY_ID"),
  SecretAccessKey: processManager.getEnvironmentVar("SECRET_ACCESS_KEY"),
  // 【可选】如果使用临时AK/SK和SecurityToken访问OBS，同样建议您尽量避免使用硬编码，以降低信息泄露风险。您可以通过环境变量获取访问密钥AK/SK，也可以使用其他外部引入方式传入
  // SecurityToken: processManager.getEnvironmentVar("SECURITY_TOKEN"),
  // Server填写Bucket对应的Endpoint, 这里以华北-北京四为例，其他地区请按实际情况填写
  Server: "https://obs.cn-north-4.myhuaweicloud.com",
});

interface DownloadResult {
  key: string;
  success: boolean;
  error?: string;
}

// 列举满足前缀的全部对象Key(自动分页)
async function listAllObjects(bucket: string, prefix: string): Promise<string[]> {
  const keys: string[] = [];
  let marker = "";
  do {
    const result = await obsClient.listObjects({
      Bucket: bucket,
      Prefix: prefix,
      Marker: marker,
      MaxKeys: 1000,
    });
    if (result.CommonMsg.Status >= 300) {
      hilog.error(0x0001, 'OBS-Harmony', "ListObjects failed, Status: %d, Code: %s", result.CommonMsg.Status, result.CommonMsg.Code);
      break;
    }
    const contents = result.InterfaceResult?.Contents ?? [];
    for (const item of contents) {
      keys.push(item.Key);
    }
    marker = result.InterfaceResult?.IsTruncated ? (result.InterfaceResult?.NextMarker ?? "") : "";
  } while (marker !== "");
  return keys;
}

async function batchDownload() {
  const bucket = "examplebucket";
  const prefix = "backup/";
  // 本地下载目录，需预先创建（SDK 不会自动创建父目录）
  const localDir = "/path/to/localdir/";
  const concurrentCount = 3;

  const objectKeys = await listAllObjects(bucket, prefix);
  hilog.info(0x0001, 'OBS-Harmony', "Listed %d objects under prefix %s", objectKeys.length, prefix);

  const results: DownloadResult[] = [];
  for (let i = 0; i < objectKeys.length; i += concurrentCount) {
    const batch = objectKeys.slice(i, i + concurrentCount);
    const batchResults = await Promise.all(
      batch.map(async (objectKey) => {
        try {
          // 用完整 objectKey 作为相对路径保留目录结构，避免同名对象互相覆盖
          const localPath = localDir + objectKey;
          // 确保本地父目录存在（SDK 不会自动创建）
          await fs.mkdir(localPath.substring(0, localPath.lastIndexOf("/")), true);
          const result = await obsClient.getObject({
            Bucket: bucket,
            Key: objectKey,
            SaveFilePath: localPath,
          });
          if (result.CommonMsg.Status < 300) {
            hilog.info(0x0001, 'OBS-Harmony', "Download success: %s", objectKey);
            return { key: objectKey, success: true } as DownloadResult;
          } else {
            hilog.error(0x0001, 'OBS-Harmony', "Download failed: %s, Status: %d, Code: %s", objectKey, result.CommonMsg.Status, result.CommonMsg.Code);
            return { key: objectKey, success: false, error: result.CommonMsg.Message } as DownloadResult;
          }
        } catch (error) {
          hilog.error(0x0001, 'OBS-Harmony', "Download exception: %s", objectKey);
          const err = error as BusinessError;
          return { key: objectKey, success: false, error: err.message } as DownloadResult;
        }
      })
    );
    results.push(...batchResults);
  }

  const successCount = results.filter(r => r.success).length;
  const failedCount = results.length - successCount;
  hilog.info(0x0001, 'OBS-Harmony', "Batch download complete: %d/%d success, %d failed", successCount, results.length, failedCount);
}

batchDownload();

相关链接

  • 关于批量下载所调用的下载对象-获取对象内容的API说明，请参见获取对象内容。
  • 下载对象过程中返回的错误码含义、问题原因及处理措施可参考OBS错误码。
父主题： 基础操作

相关文档