# 追加写对象-AppendObject #### 功能介绍 追加写对象操作是指在指定桶内的一个对象尾追加上传数据，不存在相同对象名的对象则创建新对象。了解更多追加写对象相关信息，请参见[追加写对象](https://support.huaweicloud.com/usermanual-obs/obs_03_1006.html)。 通过Append Object操作创建的Object类型为Appendable Object，而通过Put Object上传的Object是Normal Object。 为了确保数据在传输过程中没有遭到破坏，用户可以在请求头参数（Request headers）中加入Content-MD5参数，OBS收到上传数据后，会对数据进行MD5校验，如果不一致则返回出错信息。 #### 与其他功能结合使用 - [和其他操作的关系] 1. 对一个已经存在的Appendable对象进行Put Object操作，那么该Appendable对象会被新Object覆盖，类型变为Normal对象，反之出错。 2. Appendable对象复制后变成Normal对象，不支持Appendable对象复制成Appendable对象。 - [WORM] 在开启了WORM开关的桶中，使用追加写上传对象将失败并返回403。 #### 接口约束 1. 每次追加上传都会更新该对象的最后修改时间。 2. 服务端加密SSE-C方式，那么追加上传和初始化段一样，设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传也必须携带。 3. 服务端加密SSE-KMS方式，有且只有第一次上传且桶内不存在同名对象时，才设置诸如x-obs-server-side-encryption之类的请求Header，后续追加上传不携带。 4. 每次追加上传的长度不能超过对象长度上限5G的限制。 5. 每个Appendable对象追加写次数最多为10000次。 6. 如果对象存储类型为COLD（归档存储）或DEEP_ARCHIVE（深度归档存储），则不能调用该接口。 7. 如果桶设置了跨区域复制配置，则不能调用该接口。 8. 并行文件系统不支持追加写对象。 #### 授权信息 您必须是对象拥有者或拥有追加写对象的权限，才能调用本接口，建议使用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) | - | - kms:cmk:create - kms:cmk:list - kms:cmk:createDataKey - functiongraph:function:invokeAsync - functiongraph:workflow:invoke - smn:topic:publish | | obs:object:putObject | Permission_management | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain - obs:x-obs-acl | - | - kms:cmk:create - kms:cmk:list - kms:cmk:createDataKey - functiongraph:function:invokeAsync - functiongraph:workflow:invoke - smn:topic:publish | - 如果使用**桶策略** 进行授权，需具备**obs:object:PutObject** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。 #### URI POST /{*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=AppendObject)在线调试接口。 #### 请求消息样式 ``` POST /ObjectName?append&position=Position HTTP/1.1 Host: bucketname.obs.cn-north-4.myhuaweicloud.com Content-Type: application/xml Content-Length: length Authorization: authorization Date: date ``` #### URI参数（URI Parameters） 该请求需要在消息中指定参数，表明这是追加写上传，同时指定本次追加上传位置，参数的具体意义如[表1]所示 表1URI参数 | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | append | String | 是 | **参数解释：** 表明这是以追加写方式上传对象。 **约束限制：** 无 **取值范围：** 无 **默认取值：** 无 | | position | Integer | 是 | **参数解释：** 追加写位置。 **约束限制：** 不能超过5GB。 **取值范围：** 需要追加写的对象首次上传时就必须指定position为0，下次追加需要填写的position会在服务端本次上传成功返回消息的头域x-obs-next-append-position中携带。 **默认取值：** 无 | #### 请求头参数（Request headers） 该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。 请求参数position=0时，该请求可以使用的附加消息头，具体如[表2]所示。 该请求可以使用的服务端加密请求头参数，具体如[表3]所示。 表2请求头参数 | **消息头名称** | **消息头类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | x-obs-acl | String | 否 | **参数解释：** 第一次写时，可以加上此消息头设置对象的权限控制策略，使用的策略为预定义的常用策略。 **约束限制：** 预定义策略为字符串形式。 **取值范围：** - private - public-read - public-read-write 各策略详细说明见[ACL](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0005.html)章节的"使用头域设置ACL"。 **默认取值：** private | | x-obs-grant-read | String | 否 | **参数解释：** 第一次写时，使用此头域可以授权读对象、获取对象元数据的权限给domain下的所有用户。 示例：x-obs-grant-read: id=domainID。 **约束限制**： 如果授权给多个租户，需要通过","分隔。 **取值范围：** 无 **默认取值：** 无 | | x-obs-grant-read-acp | String | 否 | **参数解释：** 第一次写时，使用此头域授权获取对象ACL的权限给domain下的所有用户。 示例：x-obs-grant-read-acp: id=domainID。 **约束限制**： 如果授权给多个租户，需要通过","分隔。 **取值范围：** 无 **默认取值：** 无 | | x-obs-grant-write-acp | String | 否 | **参数解释：** 第一次写时，使用此头域授权写对象ACL的权限给domain下的所有用户。 示例：x-obs-grant-write-acp: id=domainID。 **约束限制**： 如果授权给多个租户，需要通过","分隔。 **取值范围：** 无 **默认取值：** 无 | | x-obs-grant-full-control | String | 否 | **参数解释：** 第一次写时，使用此头域授权读对象、获取对象元数据、获取对象ACL、写对象ACL的权限给domain下的所有用户。 示例：x-obs-grant-full-control: id=domainID。 **约束限制**： 如果授权给多个租户，需要通过","分隔。 **取值范围：** 无 **默认取值：** 无 | | x-obs-storage-class | String | 否 | **参数解释：** 第一次写时，可以加上此头域设置对象的存储类型。 示例：x-obs-storage-class：STANDARD **约束限制：** - 归档存储和深度归档存储对象不支持追加上传。 - 设置对象的存储类型时请注意大小写敏感。 **取值范围：** - STANDARD - WARM **默认取值：** 如果未设置此头域，则以桶的默认存储类型作为对象的存储类型。 | | x-obs-meta-\* | String | 否 | **参数解释：** 第一次写时，可以在HTTP请求中加入以"x-obs-meta-"开头的消息头，用来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回消息的头中出现。 示例：x-obs-meta-test：test metadata **约束限制：** HTTP请求不包含消息体，长度不能超过8KB。 **取值范围：** 无 **默认取值：** 无 | | x-obs-persistent-headers | String | 否 | **参数解释：** 第一次写时，可以在HTTP请求中加入"x-obs-persistent-headers"消息头，用来加入一个或多个自定义的响应头，当用户获取此对象或查询此对象元数据时，加入的自定义响应头将会在返回消息的头域中出现。 格式：x-obs-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2).... 说明：其中key1/key2等为自定义header，如果含有非ASCII码或不可识别字符，可以采用URL编码或者Base64编码，服务端只会作为字符串处理，不会做解码。value1/value2等为对应自定义header的值，base64_encode指做base64编码，即将自定义header和对应值的base64编码作为一个key-value对用":"连接，然后用","将所有的key-value对连接起来，放在x-obs-persistent-headers这个header中即可，服务端会对上传的value做解码处理。 示例：x-obs-persistent-headers: key1:dmFsdWUx,key2:dmFsdWUy 下载此对象或获取此对象元数据时：返回两个头域分别为"key1:value1"与"key2:value2" **约束限制：** - 通过该方式指定的自定义响应头不能以"x-obs-"为前缀，比如可以指定"key1"，但是不能指定"x-obs-key1"。 - 不能指定http标准头，例如host/content-md5/origin/range/Content-Disposition等。 - 此头域和自定义元数据总长度不能超过8KB。 - 如果传入相同key，将value以","拼接后放入同一个key中返回。 - 如果value解码后存在非US-ASCII值或不可识别字符，则服务端只会作为字符串处理并通过"?UTF-8?B?\<(str)\>?="包装，而不会做解码，例如key1:abbc，会返回key1: =?UTF-8?B?abbc?=。 - value不支持包含的字符"空格"、"="、","、";"、":"、"."，如果需要包含，请使用URL编码或者Base64编码。 **取值范围：** 无 **默认取值：** 无 | | x-obs-website-redirect-location | String | 否 | **参数解释：** 当桶设置了Website配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的URL，OBS将这个值从头域中取出，保存在对象的元数据中。 **约束限制：** 必须以"/"、"http://"或"https://"开头，长度不超过2K。 **取值范围：** 无 **默认取值：** 无 | | x-obs-expires | Integer | 否 | **参数解释：** 表示对象的过期时间，单位是天。过期之后对象会被自动删除。（从对象最后修改时间开始计算） 示例：x-obs-expires：3 **约束限制：** 设置的天数计算出的过期时间不能早于当前时间，如10天前上传的对象，不能设置小于10的值。 **取值范围：** 大于0的整数值。 **默认取值：** 无 | | x-obs-tagging | String | 否 | **参数解释：** 以键值对（Key-Value）的形式指定对象的标签信息，可同时设置多个标签。 示例：x-obs-tagging:TagA=A\&TagB\&TagC **约束限制：** - 该请求头仅在首次追加操作时设置生效，后续追加操作不生效。 - Key或Value包含特殊字符以及"="、中文字符时，需要进行URL编码处理。 - 如果某项没有"="，则看作Value为空字符串。 **取值范围：** 无 **默认取值：** 无 | | x-obs-checksum-crc64ecma | UnsignedLong | 否 | **参数解释：** 按照ECMA-182标准计算出整个追加写对象的crc64值，采用64位无符号数编码；使用该头域服务端会进行数据一致性校验。 - 如果服务端计算出的crc64值与头域携带的crc64值相同，响应码为200 - 如果服务端计算出的crc64值与头域携带的crc64值不符，响应码为400 示例：x-obs-checksum-crc64ecma: 11051210869376104954 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | 表3服务端加密请求头参数 | **消息头名称** | **消息头类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | x-obs-server-side-encryption | String | 否。当使用SSE-KMS方式时，必选。 | **参数解释：** 使用该头域表示服务端加密是SSE-KMS方式。 示例：x-obs-server-side-encryption：kms **约束限制：** 无 **取值范围：** - kms - AES256 **默认取值：** 无 | | x-obs-server-side-data-encryption | String | 否 | **参数解释：** 在SSE-KMS加密方式下使用该头域，该头域表示对象使用的数据加密算法。 示例：x-obs-server-side-data-encryption：SM4 **约束限制:** 无 **取值范围：** - SM4 - AES256 **默认取值：** 无 | | 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-server-side-encryption-customer-algorithm | String | 否。当使用SSE-C方式时，必选。 | **参数解释：** 在SSE-C加密方式下使用该头域，该头域表示加密使用的算法。 示例：x-obs-server-side-encryption-customer-algorithm：AES256 **约束限制：** 需要和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方式时，必选。 | **参数解释：** 在SSE-C加密方式下使用该头域，该头域表示加密使用的密钥。该密钥用于加密对象。 示例：x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= **约束限制：** 该头域由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方式时，必选。 | **参数解释：** 在SSE-C加密方式下使用该头域，该头域表示加密使用的密钥的MD5值。MD5值用于验证密钥传输过程中是否出错。 示例：x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== **约束限制：** 该头域由密钥的128-bit MD5值经过base64-encoded得到，需要和x-obs-server-side-encryption-customer-algorithm，x-obs-server-side-encryption-customer-key一起使用。 **取值范围：** 密钥ID MD5的base64值。 **默认取值：** 无 | #### 请求体参数（Request body） 该请求消息体中携带的是对象的数据内容。 #### 响应消息样式 ``` 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)。 ![](https://support.huaweicloud.com/api-obs/public_sys-resources/note_3.0-zh-cn.png) ETag返回的是本次追加上传数据的Hash值，不是整个对象的Hash值。 表4响应头 | **消息头名称** | **消息头类型** | **描述** | |:---|:---|:---| | x-obs-version-id | String | **参数解释：** 对象的版本号。如果桶的多版本状态为开启，则会返回对象的版本号。 **取值范围：** 无 | | x-obs-server-side-encryption | String | **参数解释：** 该头域表示服务端的加密方式。如果服务端加密是SSE-KMS方式，响应包含该头域。 示例：x-obs-server-side-encryption：kms **取值范围：** - kms - AES256 | | x-obs-server-side-data-encryption | String | **参数解释：** 如果服务端加密是SSE-KMS方式，且数据加密算法为SM4，响应包含该头域。 示例：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)。 说明： - 当您选择使用kms加密方式，但未设置此头域时，默认的主密钥将会被使用。如果默认主密钥不存在，系统将默认创建并使用。 - 当您设置了x-obs-server-side-encryption头域且赋值为"kms"，即选择kms加密方式时，才能使用该头域指定加密密钥。 **取值范围：** 不涉及。 | | 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 | **参数解释：** 如果服务端加密是SSE-C方式，响应包含该头域，该头域表示加密使用的密钥的MD5值。 示例：x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== **取值范围：** 密钥ID MD5的base64值。 | | x-obs-next-append-position | Integer | **参数解释：** 指明下一次请求应该提供的position。对象为Appendable对象时，会返回此头域。 **取值范围：** 无 | #### 响应体 (Response Body) 该请求的响应消息中不带消息元素。 #### 错误响应消息 1. 如果本次追加上传使对象长度超过对象长度限制，OBS返回400 Bad Request，错误码为AppendTooLarge。 2. 如果position的值和当前对象的原始长度不一致，OBS返回409 Conflict，错误码为PositionNotEqualToLength。 3. 如果指定桶中存在相同对象键值的对象，对象类型非Appendable，OBS返回409 Conflict，错误码为ObjectNotAppendable。 4. 如果对象追加写次数超过10000次，OBS返回409 Conflict，错误码为ObjectNotAppendable。 5. 如果对象存储类型为COLD（归档存储）或DEEP_ARCHIVE（深度归档存储），则不能调用该接口，否则OBS返回409 Conflict，错误码为ObjectNotAppendable。 6. 如果桶设置了跨区域复制配置，则不能调用该接口，否则OBS返回400 Bad Request，错误码为OperationNotSupported。 其他错误已包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)中。 #### 请求示例：普通追加写对象 ``` POST /object?append&position=0 HTTP/1.1 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT Content-Type: image/jpg Content-Length: 1458 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [1458 bytes of object data] ``` #### 响应示例：普通追加写对象 ``` HTTP/1.1 200 OK Date: Wed, 27 Jun 2015 13:45:50 GMT ETag: "d41d8cd98f00b204e9800998ecf8427e" Content-Length: 0 Server: OBS x-obs-request-id: 8DF400000163D3F0FD2A03D2D30B0542 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCTjCqTmsA1XRpIrmrJdvcEWvZyjbztdd x-obs-next-append-position: 1458 ``` #### 请求示例：带redirect和自定义头域追加写对象 用户存在桶examplebucket，对象obj001不存在，通过追加写接口创建新对象， 设置重定向头域"x-obs-website-redirect-location":"http://www.example.com/"，自定义头域"x-obs-meta-redirect":"redirect"，请求为 ``` POST /obj001?append&position=0 HTTP/1.1 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Expires: Wed, 27 Jun 2015 13:45:50 GMT Date: Wed, 08 Jul 2015 06:57:01 GMT x-obs-website-redirect-location: http://www.example.com/ x-obs-meta-redirect: redirect Content-Length: 6 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:kZoYNv66bsmc10+dcGKw5x2PRrk= [6 bytes of object data] ``` #### 响应示例：带redirect和自定义头域追加写对象 ``` HTTP/1.1 200 OK Date: Wed, 27 Jun 2015 13:45:50 GMT ETag: "9516dfb15f51c7ee19a4d46b8c0dbe1d" Content-Length: 0 Server: OBS x-obs-request-id: 5DEB00000164A3150AC36F8F0C120D50 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCSrVlTYwsA4p9GEW+LYqotSl5BYDxHfT x-obs-next-append-position: 6 ``` #### 请求示例：已启用版本控制 ``` POST /object01?append&position=0 HTTP/1.1 Authorization: OBS H4IPJX0TQTHTHEBQQCEC:iqSPeUBl66PwXDApxjRKk6hlcN4= User-Agent: curl/7.29.0 Host: examplebucket.obs.region.myhuaweicloud.com Date: Wed, 01 Jul 2015 02:37:22 GMT Content-Type: application/octet-stream [1458 bytes of object data] ``` #### 响应示例：已启用版本控制 ``` HTTP/1.1 200 OK x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSZbDadL1f7fYU44bvRLvc0l6D10+wzG x-obs-request-id: 0000018A2BCBB3ABD3046B99E3ED2E30 Server: OBS Content-Length: 0 Date: Wed, 01 Jul 2015 02:37:22 GMT x-obs-next-append-position: 4 ETag: "56468d5607a5aaf1604ff5e15593b003" x-obs-version-id: G001118A6803675AFFFFD3043F7F91D0 ``` #### 使用SDK调用接口 建议您使用OBS SDK调用接口。SDK对API进行了封装以简化您的开发工作，直接调用SDK接口函数即可访问OBS，无需手动计算签名。 | [Java](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0609.html) | [Python](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_0904.html) | [C](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_0408.html) | [Go](https://support.huaweicloud.com/sdk-go-devg-obs/obs_23_0404.html) | [BrowserJS](https://support.huaweicloud.com/sdk-browserjs-devg-obs/obs_24_0509.html) | [.NET](https://support.huaweicloud.com/sdk-dotnet-devg-obs/obs_25_0410.html) | [Android](https://support.huaweicloud.com/sdk-android-devg-obs/obs_26_0409.html) | [iOS](https://support.huaweicloud.com/sdk-ios-devg-obs/obs_27_0408.html) | PHP不支持 | [Node.js](https://support.huaweicloud.com/sdk-nodejs-devg-obs/obs_29_0409.html) | |---|---|---|---|---|---|---|---|---|---| #### 相关文档 - 了解更多追加写对象相关介绍，请参见[追加写对象](https://support.huaweicloud.com/usermanual-obs/obs_03_1006.html)。 - API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。