文档首页/ 对象存储服务 OBS/ SDK参考/ Harmony（公测）/ 对象相关接口(HarmonyOS SDK)/ 多段相关接口(HarmonyOS SDK)/ 列举分段上传任务(HarmonyOS SDK)
更新时间：2026-08-28 GMT+08:00
查看PDF
分享

列举分段上传任务(HarmonyOS SDK)

功能说明

列举指定桶中所有初始化后还未合并或还未取消的分段上传任务。

通过列举桶中的多段上传任务，您可以获得已初始化多段上传任务的列表，已初始化多段上传任务是指初始化后还未合并以及未取消的多段上传任务。每个请求将返回最多1000个多段上传任务，如果正在进行的多段上传任务超过1000个，您需要发送其他请求以检索剩余的多段上传任务。

接口约束

  • 您必须是桶拥有者或拥有列举分段上传任务的权限，才能列举分段上传任务。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:bucket:ListBucketMultipartUploads权限，如果使用桶策略则需授予ListBucketMultipartUploads权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。

方法定义

1
 
listMultipartUploads(input: ListMultipartUploadsInput): Response<ListMultipartUploadsOutput>

请求参数

表1 请求参数列表

参数名称

参数类型

是否必选

描述

input

ListMultipartUploadsInput

必选

参数解释：

列举分段上传任务接口入参，详见ListMultipartUploadsInput。
表2 ListMultipartUploadsInput

参数名称

参数类型

是否必选

描述

Bucket

string

必选

参数解释：

桶名。

约束限制：

  • 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。
  • 桶命名规则如下：
    • 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻（如：“my..bucket”）。
    • 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。
  • 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

默认取值：

无

Prefix

string

可选

参数解释：

限定返回的分段上传任务中的对象名必须带有prefix前缀。

例如，假设您拥有以下对象：logs/day1、logs/day2、logs/day3和ExampleObject.jpg。如果您将logs/指定为前缀，将返回以字符串“logs/”开头的三个对象所在的分段上传任务。如果您指定空的前缀且请求中没有其他过滤条件，将返回桶中的所有分段上传任务。

约束限制：

长度大于0且不超过1024的字符串。

默认取值：

无

MaxUploads

number

可选

参数解释：

列举分段上传任务的最大数目。

约束限制：

当该参数超出1000时，按照默认的1000进行处理。

取值范围：

1~1000，单位：个。

默认取值：

1000

Delimiter

string

可选

参数解释：

对分段上传任务中的对象名进行分组的字符。通常与前缀prefix搭配使用，如果指定了prefix，从prefix到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes；如果没有指定prefix，从对象名的首字符到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes。

例如，桶中有3个对象，分别为abcd、abcde、bbcde。如果指定delimiter为d，prefix为a，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes；如果只指定delimiter为d，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes，而bbcde会被单独分成一组，形成一条前缀为bbcd的CommonPrefixes。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

KeyMarker

string

可选

参数解释：

列举分段上传任务的起始位置。表示列举时返回指定的KeyMarker之后的分段上传任务。

取值范围：

上次请求返回体的NextKeyMarker值。

默认取值：

无

UploadIdMarker

string

可选

参数解释：

列举分段上传任务的起始位置（uploadId标识）。

约束限制：

只有与KeyMarker参数一起使用时才有意义，即列举时返回指定KeyMarker的UploadIdMarker之后的分段上传任务。

取值范围：

对象的分段上传任务ID，即上次请求返回体的NextUploadIdMarker值。

默认取值：

无

EncodingType

string

可选

参数解释：

用于指定对响应中的Key进行指定类型的编码。如果Key包含xml 1.0标准不支持的控制字符，可通过设置该参数对响应中的Key进行编码。

取值范围：

可选值为url。

默认取值：

无，不设置则不编码。

返回结果

表3 返回结果

参数类型

描述

Response

说明：

该接口返回一个Promise类型，需要使用Promise、async/await语法处理。

参数解释：

接口返回信息，详见Response。
表4 Response

参数名称

参数类型

描述

CommonMsg

ICommonMsg

参数解释：

接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见ICommonMsg。

InterfaceResult

ListMultipartUploadsOutput

参数解释：

操作成功后的结果数据，详见ListMultipartUploadsOutput。

约束限制：

当Status大于300时为空。
表5 ICommonMsg

参数名称

参数类型

描述

Status

number

参数解释：

OBS服务端返回的HTTP状态码。

取值范围：

状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。

Code

string

参数解释：

OBS服务端返回的错误码。

Message

string

参数解释：

OBS服务端返回的错误描述。

HostId

string

参数解释：

OBS服务端返回的请求服务端ID。

RequestId

string

参数解释：

OBS服务端返回的请求ID。

Id2

string

参数解释：

OBS服务端返回的请求ID2。

Indicator

string

参数解释：

OBS服务端返回的详细错误码。
表6 ListMultipartUploadsOutput

参数名称

参数类型

描述

RequestId

string

参数解释：

OBS服务端返回的请求ID。

默认取值：

无

Bucket

string

参数解释：

桶名。

约束限制：

  • 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。
  • 桶命名规则如下：
    • 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻（如：“my..bucket”）。
    • 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。
  • 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

取值范围：

长度为3～63个字符。

KeyMarker

string

参数解释：

列举分段上传任务的起始位置，与请求中的该参数对应。表示列举时返回指定的KeyMarker之后的分段上传任务。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

UploadIdMarker

string

参数解释：

列举分段上传任务的起始位置（uploadId标识），与请求中的该参数对应。

取值范围：

长度大于0且不超过32的字符串。

默认取值：

无

NextKeyMarker

string

参数解释：

下次列举分段上传任务请求的起始位置。如果本次没有返回全部结果，响应请求中将包含该元素，用于标明接下来请求的KeyMarker值。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

NextUploadIdMarker

string

参数解释：

下次列举分段上传任务请求的起始位置（uploadId标识）。与NextKeyMarker配合使用。如果本次没有返回全部结果，响应请求中将包含该元素，用于标明接下来请求的UploadIdMarker值。

取值范围：

长度大于0且不超过32的字符串。

默认取值：

无

MaxUploads

number

参数解释：

列举分段上传任务的最大数目，与请求中的该参数对应。

约束限制：

当该参数超出范围时，按照默认的1000进行处理。

取值范围：

1~1000，单位：个。

默认取值：

1000

IsTruncated

boolean

参数解释：

表明本次请求是否返回了全部结果。

取值范围：

  • true：表示没有返回全部结果。
  • false：表示已返回了全部结果。

默认取值：

无

Prefix

string

参数解释：

分段上传任务中的对象名前缀，与请求中的该参数对应。限定返回的分段上传任务中的对象名必须带有prefix前缀。

例如，假设您拥有以下对象：logs/day1、logs/day2、logs/day3和ExampleObject.jpg。如果您将logs/指定为前缀，将返回以字符串“logs/”开头的三个对象所在的分段上传任务。如果您指定空的前缀且请求中没有其他过滤条件，将返回桶中的所有分段上传任务。

约束限制：

长度大于0且不超过1024的字符串。

默认取值：

无

Delimiter

string

参数解释：

用于对分段上传任务中的对象名进行分组的字符，与请求中的该参数对应。通常与前缀prefix搭配使用，如果指定了prefix，从prefix到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes；如果没有指定prefix，从对象名的首字符到第一次出现delimiter间具有相同字符串的对象名会被分成一组，形成一条CommonPrefixes。

例如，桶中有3个对象，分别为abcd、abcde、bbcde。如果指定delimiter为d，prefix为a，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes；如果只指定delimiter为d，abcd、abcde会被分成一组，形成一条前缀为abcd的CommonPrefixes，而bbcde会被单独分成一组，形成一条前缀为bbcd的CommonPrefixes。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

Uploads

Upload[]

参数解释：

桶内分段上传任务列表，详见Upload。

EncodingType

string

参数解释：

用于指定对响应中的Key进行指定类型的编码。如果Key包含xml 1.0标准不支持的控制字符，可通过设置该参数对响应中的Key进行编码。

取值范围：

可选值为url。

默认取值：

无，不设置则不编码。
表7 Upload

参数名称

参数类型

描述

Key

string

参数解释：

对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。

例如，您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt 中，对象名为folder/test.txt。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

UploadId

string

参数解释：

分段上传任务的ID。例如：000001648453845DBB78F2340DD460D8

取值范围：

长度大于0且不超过32的字符串。

默认取值：

无

Initiator

Initiator

参数解释：

分段上传任务的创建者，详见Initiator。

Owner

Owner

参数解释：

分段上传的对象的所有者账号户ID，详见Owner。

StorageClass

StorageClassType

参数解释：

分段上传的对象的存储类型。

取值范围：

存储类型取值范围：参见StorageClassType。

默认取值：

无

Initiated

string

参数解释：

分段上传任务的初始化时间。

约束限制：

日期格式必须为ISO8601的格式。 例如：2018-01-01T00:00:00.000Z。

默认取值：

无
表8 Initiator

参数名称

参数类型

是否必选

描述

ID

string

作为请求参数时必选

参数解释：

创建者的账号ID，即domain_id。

取值范围：

如何获取账号ID请参见如何获取账号ID和用户ID？(HarmonyOS SDK)

默认取值：

无

DisplayName

string

可选

参数解释：

创建者账号名。

约束限制：

账号名不支持中文，只能包含英文字母、数字或特殊字符“-_”，且须以字母开头，账号名长度支持6~32个字符。

默认取值：

无
表9 Owner

参数名称

参数类型

是否必选

描述

ID

string

作为请求参数时必选

参数解释：

所有者的账号ID，即domain_id。

取值范围：

如何获取账号ID请参见如何获取账号ID和用户ID？(HarmonyOS SDK)

默认取值：

无

DisplayName

string

可选

参数解释：

所有者的账号用户名。

默认取值：

无
表10 StorageClassType

常量名

原始值

说明

STANDARD

STANDARD

标准存储。

标准存储拥有低访问时延和较高的吞吐量，适用于有大量热点对象（平均一个月多次）或小对象（<1MB），且需要频繁访问数据的业务场景。

WARM

WARM

低频访问存储。

低频访问存储适用于不频繁访问（平均一年少于12次）但在需要时也要求能够快速访问数据的业务场景。

COLD

COLD

归档存储。

归档存储适用于很少访问（平均一年访问一次）数据的业务场景。

DEEP_ARCHIVE

DEEP_ARCHIVE

深度归档存储。

适用于长期不访问（平均几年访问一次）数据的业务场景。

代码示例

本示例用于examplebucket桶中所有的初始化后还未合并以及未取消的多段上传任务。

 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
 
// 引入依赖包
import ObsClient, { ListMultipartUploadsInput } from '@obs/esdk-obs-harmony';
import { process } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
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",
});

async function listMultipartUploads() {
  try {
    const params: ListMultipartUploadsInput = {
      // 指定存储桶名称
      Bucket: "examplebucket",
            // 指定列举的多段任务的最大条目，此处以10为例
      MaxUploads: 10
    };
    // 列举分段上传任务
    const result = await obsClient.listMultipartUploads(params);
    if (result.CommonMsg.Status < 300) {
      hilog.info(0x0001, 'OBS-Harmony', "List multipart uploads successful with bucket(%s) !", params.Bucket);
      hilog.info(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId);
      for (let i = 0; i < result.InterfaceResult.Uploads.length; i++) {
        const upload = result.InterfaceResult.Uploads[i];
        hilog.info(0x0001, 'OBS-Harmony', "Upload[%d]-OwnerId:%s, UploadId:%s, Key:%s, Initiated:%s",
            i, upload.Owner.ID, upload.UploadId, upload.Key, upload.Initiated);
    }
      return;
    }
    hilog.error(0x0001, 'OBS-Harmony', "An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    hilog.error(0x0001, 'OBS-Harmony', "Status: %d", result.CommonMsg.Status);
    hilog.error(0x0001, 'OBS-Harmony', "Code: %s", result.CommonMsg.Code);
    hilog.error(0x0001, 'OBS-Harmony', "Message: %s", result.CommonMsg.Message);
    hilog.error(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    const err = error as BusinessError;
    hilog.error(0x0001, 'OBS-Harmony', 'An Exception occurred: code=%d, message: %s', err.code, err.message);
  }
}

listMultipartUploads();

相关链接

相关文档