# 列举桶中已初始化多段任务-ListMultipartUploads #### 功能介绍 用户可以通过本接口查询一个桶中所有的初始化后还未合并以及未取消的多段上传任务。了解更多多段上传相关信息，请参见[多段上传](https://support.huaweicloud.com/usermanual-obs/obs_41_0021.html)。 #### 接口约束 - 文件夹不支持多段上传。 - 一个请求只能上传一个段，可以同时发起多个请求。 - 分段相关限制： 表1分段相关限制 | 项目 | 限制 | |:---|:---| | 对象大小 | 最大48.8TB | | 每次上传的段的数量 | 最大10000 | | 段编号 | 1到10000（含） | | 段大小 | 100KB到5GB，最后一个段大小是0到5GB | | 列举已上传的段请求返回的段数量 | 最大1000 | | 列举已初始化多段任务请求返回的任务数量 | 最大1000 | - 如果您使用[SSE-C加密（用户提供密钥）](https://support.huaweicloud.com/usermanual-obs/obs_03_0093.html)，需要在**初始化上传段任务** 、**上传段** 、**拷贝段** 的过程中携带密钥信息，且同一个任务内的多段操作，携带的密钥必须保持一致。**合并段无需携带密钥**，合并后的对象是一个使用SSE-C方式加密的对象。 - 如果您使用[SSE-KMS](https://support.huaweicloud.com/usermanual-obs/obs_03_0090.html)或者[SSE-OBS](https://support.huaweicloud.com/usermanual-obs/obs_03_0092.html)加密方式，只需要在**初始化上传段任务**时配置好加密方式、算法和密钥信息。 #### 授权信息 您必须是桶拥有者或拥有列举桶中已初始化多段任务的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。 - 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限： - 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:bucket:ListBucketMultipartUploads** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。 - 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:bucket:listBucketMultipartUploads** 权限，授权操作请参见[创建IAM自定义身份策略](https://support.huaweicloud.com/usermanual-iam5/iam_01_0917.html)。 | 授权项 Action | 访问级别 Access Level | 资源类型（\*为必须） Resource Type (\*: required) | [条件键](https://support.huaweicloud.com/api-obs/obs_04_0112.html#ZH-CN_TOPIC_0000002375307974__condition_table) Condition Key | [别名](https://support.huaweicloud.com/iam5_faq/iam_01_1103.html) Alias | 依赖的授权项 Dependencies | |:---|:---|:---|:---|:---|:---| | obs:bucket:listBucketMultipartUploads | List | bucket \* | - [g:EnterpriseProjectId](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) - [g:ResourceTag/\](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) | - | - | | obs:bucket:listBucketMultipartUploads | List | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain | - | - | - 如果使用**桶策略** 进行授权，需具备**obs:bucket:ListBucketMultipartUploads** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。 #### URI GET / #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-obs/obs_04_0006.html)。调用前需要先[计算API签名](https://support.huaweicloud.com/api-obs/obs_04_0009.html)，并将签名添加到请求中。 您还可以使用[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/OBS/doc?api=ListMultipartUploads)在线调试接口。 #### 请求消息样式 ``` GET /?uploads&max-uploads=max HTTP/1.1 Host: bucketname.obs.cn-north-4.myhuaweicloud.com Date: date Authorization: authorization ``` #### URI参数（URI Parameters） 该请求可以通过在请求消息中指定参数，查询指定范围的多段上传任务，请求参数说明如[表2]所示。 表2URI参数 | **参数名称** | **是否必选** | 参数类型 | **描述** | |:---|:---|:---|:---| | delimiter | 否 | String | **参数解释：** 对于名字中包含delimiter的对象的任务，其对象名（如果请求中指定了prefix，则此处的对象名需要去掉prefix）中从首字符至第一个delimiter之间的字符串将作为CommonPrefix在响应中返回。对象名包含CommonPrefix的任务被视为一个分组，作为一条记录在响应中返回，该记录不包含任务的信息，仅用于提示用户该分组下存在多段上传任务。 **约束限制：** 不涉及 **取值范围：** 长度大于0且不超过1024的字符串。 **默认取值：** 不涉及 | | prefix | 否 | String | **参数解释：** 列举桶内多段任务列表时，指定一个前缀，限定返回的多段任务的对象名必须带有prefix前缀。如果请求中指定了prefix，则响应中仅包含对象名以prefix开始的任务信息。 **约束限制：** 满足对象名的格式。 **取值范围：** 长度大于0且不超过1024的字符串。 **默认取值：** 不涉及 | | max-uploads | 否 | Integer | **参数解释：** 单次列举的多段任务的最大条目。单位：个。 **约束限制：** 不涉及 **取值范围：** \[1,1000\]，当超出范围时，按照默认的1000进行处理。 **默认取值：** 1000 | | key-marker | 否 | String | **参数解释：** 列举时返回指定的key-marker之后的多段任务。 **约束限制：** 不涉及 **取值范围：** 上次请求返回体的NextKeyMarker值。 **默认取值：** 不涉及 | | upload-id-marker | 否 | String | **参数解释：** 列举时返回指定的key-marker的upload-id-marker之后的多段任务。 **约束限制：** 需要和key-marker一起使用才有意义。 **取值范围：** 上次请求返回体的NextUploadIdMarker值。 **默认取值：** 不涉及 | | encoding-type | 否 | String | **参数解释：** 对响应中的部分元素进行指定类型的编码。如果Delimiter、KeyMarker、Prefix、NextKeyMarker和Key包含xml 1.0标准不支持的控制字符，可通过设置encoding-type对响应中的Delimiter、KeyMarker、Prefix（包括CommonPrefixes中的Prefix）、NextKeyMarker和Key进行编码。 **约束限制：** 当前只支持URL编码。 **取值范围：** url **默认取值：** 不涉及，不设置则不编码。 | #### 请求头参数（Request headers） 该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。 #### 请求体参数（Request body） 该请求消息中不带请求体参数。 #### 响应消息样式 ``` HTTP/1.1 status_code Date: date Content-Length: length bucketname nextMarker idMarker maxUploads true key uploadID domainID/domainID:userID/userID ownerID storageclass initiatedDate ``` #### 响应头 (Response Headers) 该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。 #### 响应体 (Response Body) 该请求的响应消息中通过消息元素返回多段上传任务，元素的具体意义如[表3]所示。 表3响应体 | **参数名称** | 参数类型 | **描述** | |:---|:---|:---| | ListMultipartUploadsResult | Container | **参数解释：** 保存列举多段上传请求结果的容器，ListMultipartUploadsResult是Bucket、KeyMarker、UploadIdMarker、NextKeyMarker、NextUploadIdMarker、MaxUploads、IsTruncated、Upload、Prefix、Delimiter、CommonPrefixes的父节点。 **取值范围：** 请详见[ListMultipartUploadsResult响应消息元素说明]。 | 表4ListMultipartUploadsResult响应体说明 | **参数名称** | 参数类型 | **描述** | |:---|:---|:---| | Bucket | String | **参数解释：** 初始化任务所在的桶名。 **取值范围：** 长度为3\~63的字符串。 | | EncodingType | String | **参数解释：** 对响应中的部分元素进行指定类型的编码。如果请求中设置了encoding-type，那响应中的Delimiter、KeyMarker、Prefix（包括CommonPrefixes中的Prefix）、NextKeyMarker和Key会被编码。 **取值范围：** url | | KeyMarker | String | **参数解释：** 列举时的起始对象位置。 **取值范围：** 长度大于0且不超过1024的字符串。 | | UploadIdMarker | String | **参数解释：** 列举时的起始UploadId位置。 **取值范围：** 长度大于0且不超过32的字符串。 | | NextKeyMarker | String | **参数解释：** 如果本次没有返回全部结果，响应请求中将包含NextKeyMarker字段，用于标明接下来请求的KeyMarker值。 **取值范围：** 长度大于0且不超过1024的字符串。 | | NextUploadIdMarker | String | **参数解释：** 如果本次没有返回全部结果，响应请求中将包含NextUploadIdMarker元素，用于标明接下来请求的UploadMarker值。 **取值范围：** 长度大于0且不超过32的字符串。 | | MaxUploads | Integer | **参数解释：** 单次返回的最大多段上传任务数目。单位：个。 **取值范围：** \[1，1000\]，当超出范围时默认为1000。 | | IsTruncated | Boolean | **参数解释：** 表明是否本次返回的分段上传结果列表被截断。 **取值范围：** - true：表示本次没有返回全部结果 - false：表示本次已经返回了全部结果。 | | Upload | Container | **参数解释：** 保存分段上传任务信息的容器，Upload是Key、UploadId、Initiator、Owner、StorageClass、Initiated的父节点。 **取值范围：** 请详见[Upload响应消息元素说明]。 | | ListMultipartUploadsResult.Prefix | String | **参数解释：** 请求中携带的prefix。 **取值范围：** 长度大于0且不超过1024的字符串。 | | Delimiter | String | **参数解释：** 请求中带的Delimiter。 **取值范围：** 长度大于0且不超过1024的字符串。 | | CommonPrefixes | Container | **参数解释：** 请求中带Delimiter参数时，返回消息带CommonPrefixes分组信息，CommonPrefixes是Prefix的父节点。 **取值范围：** 请详见[CommonPrefixes响应消息元素说明]。 | 表5Upload响应体说明 | **参数名称** | 参数类型 | **描述** | |:---|:---|:---| | Key | String | **参数解释：** 初始化多段上传任务的对象名称。 **取值范围：** 长度大于0且不超过1024的字符串。 | | UploadId | String | **参数解释：** 多段上传任务的ID。 **取值范围：** 长度大于0且不超过32的字符串。 | | Initiator | Container | **参数解释：** 多段上传任务的创建者，Initiator是ID的父节点。 **取值范围：** 请详见[Initiator响应消息元素说明]。 | | Owner | Container | **参数解释：** 段的所有者，Owner是ID的父节点。 **取值范围：** 请详见[Owner响应消息元素说明]。 | | StorageClass | String | **参数解释：** 表明待多段上传的对象存储类型。 **取值范围：** - STANDARD：标准存储 - WARM：低频访问存储 - COLD：归档存储 - DEEP_ARCHIVE：深度归档存储 | | Initiated | Date | **参数解释：** 多段上传任务的初始化时间（UTC时间）。日期格式为ISO8601的格式，例如：2018-01-01T00:00:00.000Z。 **取值范围：** 不涉及 | 表6Initiator响应体说明 | **参数名称** | 参数类型 | **描述** | |:---|:---|:---| | ID | String | **参数解释：** 多段任务创建者的urn。格式为domainID/{domainId}:userID/{userId}。 **取值范围：** 不涉及 | 表7Owner响应体说明 | **参数名称** | 参数类型 | **描述** | |:---|:---|:---| | ID | String | **参数解释：** 多段任务创建者的DomainId，格式为{domainId}。 **取值范围：** 不涉及 | 表8CommonPrefixes响应体说明 | **参数名称** | 参数类型 | **描述** | |:---|:---|:---| | CommonPrefixes. Prefix | String | **参数解释：** CommonPrefixes分组信息中，表明不同的前缀。 **取值范围：** 不涉及 | #### 错误响应消息 OBS系统对maxUploads进行判断，如果maxUploads不为整数类型或者小于0，OBS返回400 Bad Request。 表9错误码响应消息 | 错误码 | 描述 | HTTP状态码 | |:---|:---|:---| | InvalidArgument | 无效的参数。 | 400 Bad Request | 其他错误已经包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)中。 #### 请求示例：不带任何参数列举已初始化的段任务 ``` GET /?uploads HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: Wed, 01 Jul 2015 04:51:21 GMT Authorization: OBS UDSIAMSTUBTEST000008:XdmZgYQ+ZVy1rjxJ9/KpKq+wrU0= ``` #### 响应示例：不带任何参数列举已初始化的段任务 ``` HTTP/1.1 200 OK Server: OBS x-obs-request-id: 8DF400000163D405534D046A2295674C x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSDaHP+a+Bp0RI6Mm9XvCOrf7q3qvBQW Content-Type: application/xml Date: Wed, 01 Jul 2015 04:51:21 GMT Content-Length: 681 examplebucket 1000 false obj2 00000163D40171ED8DF4050919BD02B8 domainID/b4bf1b36d9ca43d984fbcb9491b6fce9:userID/71f390117351534r88115ea2c26d1999 b4bf1b36d9ca43d984fbcb9491b6fce9 STANDARD 2015-07-01T02:30:54.582Z ``` #### 请求示例：带prefix和delimiter列举已初始化的段任务 例如，用户桶examplebucket中2个段任务，对象名分别为multipart-object001和part2-key02，列举段任务时，设置prefix为"multipart"，delimiter设置为object001，列举已初始化的段任务。 ``` GET /?uploads&delimiter=object001&prefix=multipart HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: Wed, 01 Jul 2015 04:51:21 GMT Authorization: OBS UDSIAMSTUBTEST000008:XdmZgYQ+ZVy1rjxJ9/KpKq+wrU0= ``` #### 响应示例：带prefix和delimiter列举已初始化的段任务 ``` HTTP/1.1 200 OK Server: OBS x-obs-request-id: 5DEB00000164A27A1610B8250790D703 x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSq3ls2ZtLDD6pQLcJq1yGITXgspSvBR Content-Type: application/xml Date: Wed, 01 Jul 2015 04:51:21 GMT Content-Length: 681 examplebucket object001 multipart 1000 false multipart-object001 ``` #### 使用SDK调用接口 建议您使用OBS SDK调用接口。SDK对API进行了封装以简化您的开发工作，直接调用SDK接口函数即可访问OBS，无需手动计算签名。 | [Java](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0607.html) | [Python](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_1001.html) | [C](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0607.html) | [Go](https://support.huaweicloud.com/sdk-go-devg-obs/obs_33_0521.html) | [BrowserJS](https://support.huaweicloud.com/sdk-browserjs-devg-obs/obs_24_0507.html) | [.NET](https://support.huaweicloud.com/sdk-dotnet-devg-obs/obs_25_0408.html) | [Android](https://support.huaweicloud.com/sdk-android-devg-obs/obs_26_0407.html) | [iOS](https://support.huaweicloud.com/sdk-ios-devg-obs/obs_27_0406.html) | [PHP](https://support.huaweicloud.com/sdk-php-devg-obs/obs_28_0407.html) | [Node.js](https://support.huaweicloud.com/sdk-nodejs-devg-obs/obs_29_0407.html) | |---|---|---|---|---|---|---|---|---|---| #### 相关文档 - 使用obsutil上传多个任务，请参见[上传对象](https://support.huaweicloud.com/utiltg-obs/obs_11_0013.html)。 - 使用OBS Browser+上传多个任务，请参见[上传文件或文件夹](https://support.huaweicloud.com/browsertg-obs/obs_03_1061.html)。 - 了解更多多段上传相关信息，请参见[多段上传](https://support.huaweicloud.com/usermanual-obs/obs_41_0021.html)。 - API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。