# 上传段-UploadPart
#### 功能介绍
多段上传任务创建后，用户可以通过指定多段上传任务号，通过上传段接口为特定的任务上传段，从客户端上传新数据，了解完整的多段上传流程请参见[多段上传](https://support.huaweicloud.com/usermanual-obs/obs_41_0021.html)。同一个对象的同一个多段上传任务在上传段时，上传的顺序对后续的合并操作没有影响，也即支持多个段并发上传。
请确保段大小范围是\[100KB,5GB\]，最后一个段的大小范围为\[0,5GB\]，否则在进行合并段操作时会报错。上传的段的编号也有范围限制，其范围是\[1,10000\]。
![](https://support.huaweicloud.com/api-obs/public_sys-resources/notice_3.0-zh-cn.png)
段任务中的partNumber是唯一的，重复上传相同partNumber的段，后一次上传会覆盖前一次上传内容。多并发上传同一对象的同一partNumber时，服务端遵循Last Write Win策略，但"Last Write"的时间定义为段元数据创建时间。为了保证数据准确性，客户端需要加锁保证同一对象的同一个段上传的并发性。同一对象的不同段并发上传不需要加锁。
#### 授权信息
您必须是桶拥有者或拥有上传段的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。
- 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限：
  - 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:object:PutObject** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。
  
  - 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:object:putObject** 权限，授权操作请参见[创建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:object:putObject                                | Permission_management                                      | object \*                                                                        | [g:EnterpriseProjectId](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2)                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                            | - obs:object:getObject  - kms:cmk:create  - kms:cmk:list  - kms:cmk:createDataKey  - kms:cmk:decryptDataKey   |
    | obs:object:putObject                                | Permission_management                                      | -                                                                                | - obs:EpochTime  - obs:SourceIp  - obs:TlsVersion  - obs:CustomDomain  - obs:x-obs-acl   | -                                                                                                            | - obs:object:getObject  - kms:cmk:create  - kms:cmk:list  - kms:cmk:createDataKey  - kms:cmk:decryptDataKey   |
       
    
   
- 如果使用**桶策略** 进行授权，需具备**obs:object:PutObject** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。
 
#### URI
PUT /{*object_key*}
#### 调用方法
请参见[如何调用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=UploadPart)在线调试接口。
#### 请求消息样式
```
PUT /ObjectName?partNumber=partNum&uploadId=uploadID  HTTP/1.1  
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Date: date
Content-Length: length 
Authorization: authorization
Content-MD5: md5
<object Content>
```
#### URI参数（URI Parameters）
在上传段的时候需要通过在消息参数中指定多段上传任务号和段号来上传指定段，参数的具体意义如[表1]所示。
 表1URI参数 
| **参数名称**   | **参数类型** | **是否必选** | **描述**                                                                                                                                                                                                                                                                                                                                                          |
|:---|:---|:---|:---|
| partNumber | Integer  | 是        | **参数解释：** 上传段的段号。 **约束限制：** 无 **取值范围：** 从1到10000的整数。 **默认取值：** 无 |
| uploadId   | String   | 是        | **参数解释：** 多段上传任务Id。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无                    |
   
#### 请求头参数（Request headers）
该请求使用公共消息头，具体请参考[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。
表2请求头参数 
| **消息头名称**                                       | **消息头类型**    | **是否必选**                               | **描述**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
|:---|:---|:---|:---|
| x-obs-server-side-encryption-customer-algorithm | String       | 否。当使用SSE-C方式时，必选，需要与初始化上传段任务使用相同的算法。   | **参数解释：** 该头域表示加密使用的算法。 示例：x-obs-server-side-encryption-customer-algorithm：AES256 **约束限制：** - 在SSE-C加密方式下使用该头域，该头域表示加密使用的算法。  - 需要和x-obs-server-side-encryption-customer-key， x-obs-server-side-encryption-customer-key-MD5一起使用。   **取值范围：** AES256 **默认取值：** 无                                                             |
| x-obs-server-side-encryption-customer-key       | String       | 否。当使用SSE-C方式时，必选，需要与初始化上传段任务使用相同的密钥。   | **参数解释：** 该头域表示加密使用的密钥，该密钥用于加密对象。 示例：x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= **约束限制：** - 仅在SSE-C加密方式下使用该头域。  - 该头域由256-bit的密钥经过base64-encoded得到，需要和x-obs-server-side-encryption-customer-algorithm，x-obs-server-side-encryption-customer-key-MD5一起使用。   **取值范围：** 无 **默认取值：** 无 |
| x-obs-server-side-encryption-customer-key-MD5   | String       | 否。当使用SSE-C方式时，必选，需要与初始化上传段任务使用相同的MD5值。 | **参数解释：** 该头域表示加密使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。 示例：x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== **约束限制：** 仅在SSE-C加密方式下使用该头域。 该头域由密钥的128-bit MD5值经过base64-encoded得到，需要和x-obs-server-side-encryption-customer-algorithm，x-obs-server-side-encryption-customer-key一起使用。 **取值范围：** 密钥ID MD5的base64值。 **默认取值：** 无                                                                                                                |
| x-obs-checksum-crc64ecma                        | UnsignedLong | 否                                      | **参数解释：** 按照ECMA-182标准计算出当前段的crc64值，采用64位无符号数编码；使用该头域服务端会进行数据一致性校验。 - 如果服务端计算出的crc64值与头域携带的crc64值相同，响应码为200  - 如果服务端计算出的crc64值与头域携带的crc64值不符，响应码为400   示例：x-obs-checksum-crc64ecma: 11051210869376104954 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及                       |
   
#### 请求消息元素
该请求消息中不使用消息元素。
#### 响应消息样式
```
HTTP/1.1 status_code
Date: date
ETag: etag
Content-Length: length
```
#### 响应头 (Response Headers)
该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。
表3响应头 
| **消息头名称**                                       | **消息头类型** | **描述**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|:---|:---|:---|
| x-obs-server-side-encryption                    | String    | **参数解释：** 该头域表示服务端的加密方式。如果服务端加密是SSE-KMS方式，响应包含该头域。 示例：x-obs-server-side-encryption：kms **取值范围：** - kms：使用SSE-KMS加密方式  - AES256：使用SSE-OBS加密方式，且使用AES256算法                                                                                      |
| x-obs-server-side-data-encryption               | String    | **参数解释：** 如果服务端加密是SSE-KMS方式，且数据加密算法为SM4，响应包含该头域。仅在SSE-KMS加密方式下使用该头域，如果开启SSE-KMS但不返回该头域则表明使用AES256算法。 示例：x-obs-server-side-data-encryption：SM4 **取值范围：** SM4：国密SM4算法                                                                                                                                                                                                                                                                                               |
| x-obs-server-side-encryption-kms-key-id         | String    | **参数描述：** 当加密方式为SSE-KMS且使用指定密钥加密时，需输入密钥ID。密钥ID获取方法请参见[查看密钥](https://support.huaweicloud.com/usermanual-dew/dew_01_0179.html)。 说明： - 当您设置了x-obs-server-side-encryption头域且赋值为"kms"，即选择kms加密方式时，才能使用该头域指定加密密钥。  - 当您选择使用kms加密方式，但未设置此头域时，默认的主密钥将会被使用。如果默认主密钥不存在，系统将默认创建并使用。   **取值范围：** 不涉及 |
| x-obs-sse-kms-key-project-id                    | String    | **参数解释：** 加密方式为SSE-KMS且使用自定义KMS密钥加密时，返回KMS主密钥所属的项目ID（非企业项目ID）。 **取值范围：** x-obs-server-side-encryption-kms-key-id指定的KMS主密钥所属的项目ID（非企业项目ID）。                                                                                                                                                                                                                                                                                                                                                                 |
| x-obs-server-side-encryption-bucket-key-enabled | String    | **参数解释：** SSE-KMS桶密钥功能开关。当您设置本头域为"true"时，必须同时设置本接口的另一个头域x-obs-server-side-encryption-kms-key-id以指定密钥ID。 **取值范围：** - true：开启桶密钥。  - false：关闭桶密钥。                                                                                                                                            |
| x-obs-server-side-encryption-customer-algorithm | String    | **参数解释：** 该头域表示加密使用的算法。如果服务端加密是SSE-C方式，响应包含该头域。 示例：x-obs-server-side-encryption-customer-algorithm：AES256 **取值范围：** AES256                                                                                                                                                                                                                                                                                                                                            |
| x-obs-server-side-encryption-customer-key-MD5   | String    | **参数解释：** 该头域表示加密使用的密钥的MD5值。如果服务端加密是SSE-C方式，响应包含该头域。 示例：x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== **取值范围：** 密钥ID MD5的base64值。                                                                                                                                                                                                                                                                                                      |
   
#### 响应体 (Response Body)
该请求的响应消息中不带消息元素。
#### 错误响应消息说明
1. 如果段序号超过范围\[1,10000\]，则返回错误400 Bad Request。
2. 如果段大小超过5G，则返回错误400 Bad Request。
3. 如果AccessKey或签名无效，OBS返回403 Forbidden， 错误码为AccessDenied。
4. 查询桶是否存在，如果桶不存在，OBS返回404 Not Found，错误码为NoSuchBucket。
5. 检查桶的ACL，判断用户DomainId是否具有指定桶的写权限，如果没有权限，则OBS返回403 Forbidden，错误码为AccessDenied。
6. 检查多段上传任务是否存在，如果不存在，OBS返回404 Not Found，错误码为NoSuchUpload。
7. 检查请求用户是否是多段上传任务的发起者（Initiator），如果不是，OBS返回403 Forbidden， 错误码为AccessDenied。
其他错误已包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)中。
#### 请求示例
```
PUT /object02?partNumber=1&uploadId=00000163D40171ED8DF4050919BD02B8 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com
Accept: */*
Date: Wed, 01 Jul 2015 05:15:55 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:ZB0hFwaHubi1aKHv7dSZjJts40g=
Content-Length: 102015348
[102015348 Byte part content]
```
#### 响应示例
```
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D40956A703289CA066F1
ETag: "b026324c6904b2a9cb4b88d6d61c81d1"
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCUQu/EOEVSMa04GXVwy0z9WI+BsDKvfh
Date: Wed, 01 Jul 2015 05:15:55 GMT
Content-Length: 0
```
#### 请求示例：携带服务端加密请求头
```
PUT /object02?partNumber=1&uploadId=00000163D40171ED8DF4050919BD02B8 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: Wed, 01 Jul 2015 05:15:55 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:ZB0hFwaHubi1aKHv7dSZjJts40g=
Content-Length: 102015348
x-obs-server-side-encryption-customer-key: g0lCfA3Dv40jZz5SQJ1ZukLRFqtd093ksp192   
x-obs-server-side-encryption-customer-key-MD5: Eo93ne1X/iTcs0132  
x-obs-server-side-encryption-customer-algorithm: AES256  
 
[102015348 Byte part content]
```
#### 响应示例：反馈服务加密响应头
```
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D40956A703289CA066F1
ETag: "b026324c6904b2a9cb4b88d6d61c81d1"
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCUQu/EOEVSMa04GXVwy0z9WI+BsDKvfh
Date: Wed, 01 Jul 2015 05:15:55 GMT
Content-Length: 0
x-obs-server-side-encryption-customer-algorithm: AES256
x-obs-server-side-encryption-customer-key-MD5: Eo93ne1X/iTcs0132
```