全部文档
当前文档
最近更新时间：2023-11-28 11:38:00
该接口用于以追加写的方式上传对象（Object）。当对象不存在时，调用此接口会创建新对象，当对象已存在时，调用此接口会在对象尾部追加上传数据。
ObjectNotAppendable错误。有关追加上传的更多适用场景说明请参见文档：文件管理-追加上传。
POST /{ObjectKey}?append&position={Position} HTTP/1.1
Content-Length: {ContentLength}
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
| 名称 | 描述 | 是否必选 |
|---|---|---|
| append | 用于指定Append Object操作。无参数值。 | 是 |
| position |
|
是 |
该接口可以使用所有常用请求头部。此外，也可以使用下表所列请求头部。
| 名称 | 描述 | 是否必选 |
|---|---|---|
| Cache-Control | 对象的缓存机制。更多信息，点击查看。 类型：String 默认值：None 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| Content-Disposition | 对象被下载时的名称。更多信息，点击查看。 类型：String 默认值：None 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| Content-Encoding | 对象的内容编码格式。更多信息，点击查看。 类型：String 默认值：None 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| Content-Length | 对象的大小，单位是字节。更多信息，点击查看。 类型：整型 默认值：None 约束条件：无 | 是 |
| Content-MD5 | 对消息内容（不包括头部）计算MD5值，获得128比特位数字，然后对该数字进行base64编码，用于对象完整性校验。Append Object操作的Content-MD5是本次追加操作的对象内容的MD5，不是整个对象的MD5。 类型：String 默认值：None 约束条件：无 | 否 |
| Content-Type | 用于描述文件内容MIME格式。更多信息，点击查看 。类型：String 默认值：binary/octet-stream 有效值: MIME types 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| Expect | 当使用Expect: 100-continue 时，客户端会在收到服务端的确认信息后，才发送请求体。如果请求头的信息被拒绝，则客户端不会发送请求体。类型：String 默认值：None 有效值：100-continue 约束条件：无 | 否 |
| Expires | 对象的过期时间。更多信息，点击查看 。类型：String 默认值：None 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| x-kss-meta- | 用户元数据前缀标识。若某个请求头前缀为x-kss-meta-， 则为用户自定义元数据。 类型：String 默认值：None 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| x-kss-storage-class | 对象的存储类型。 类型：String 默认值：None 有效值：STANDARD/STANDARD_IA 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效，也不会校验。 | 否 |
| x-kss-content-maxlength | 设置单次追加内容的最大允许大小。 类型：String 默认值：None 约束条件：无 | 否 |
| x-kss-tagging | 对象标签，可同时设置多个标签，例如：TagA=A&TagB=B。 说明: Key和Value需要先进行URL编码，如果某项没有”=“，则看作Value为空字符串，详见对象标签。约束条件：该值仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| x-kss-acl | 对象的权限。类型：String 默认值：private有效值：private/public-read 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效，也不会校验。 | 否 |
| x-kss-grant-read | 为若干用户授予READ权限。header的值为以一个逗号","分割的授权用户id列表。例如：x-kss-grant-read:id=“1234578”,id=“3344211” 类型：String 默认值：无 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| x-kss-grant-full-control | 为若干用户授予FULL_CONTROL权限。 类型：String 默认值：无 约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| x-kss-server-side-encryption | 使用KS3托管密钥的方式进行服务端加密。合法值：AES256约束条件：仅在首次执行Append Object操作时有效，后续追加时不生效。 | 否 |
| x-kss-server-side-encryption-customer-algorithm | 使用客户提供的密钥进行服务器端加密。合法值：AES256。约束条件：
|
否 |
| x-kss-server-side-encryption-customer-key | 使用客户提供的密钥进行服务器端加密，值为加密时使用的base64-encoded加密密钥。 类型：String 约束条件：
|
否 |
| x-kss-server-side-encryption-customer-key-MD5 | 使用客户提供的密钥进行服务器端加密，值为x-kss-server-side-encryption-customer-key的MD5值。类型：String 约束条件：
|
否 |
| 名称 | 描述 |
|---|---|
| ETag | 对象的实体标签，与对象内容有关，与名称无关。类型: String |
| x-kss-next-append-position | 下一次请求应当提供的position，即当前Object的大小。当Append Object执行成功，或者因position和Object大小不匹配而引起的409错误时，会返回此响应头。单位：字节类型：整型 |
| x-kss-object-type | Object的类型。通过Append Object操作创建的Object类型为Appendable Object，通过Put Object、Post Object、Put Fetch上传的对象类型为Normal Object，通过分块上传的对象类型是Multipart Object。类型：String |
| x-kss-server-side-encryption | 如果首次执行Append Object时使用了KS3托管密钥服务端加密，则首次及后续所有Append Object操作响应会包含该头部，值为使用的加密算法。类型：String |
| x-kss-server-side-encryption-customer-algorithm | 如果服务端使用了用户提供的加密密钥加密，则返回此响应头，该值与请求头x-kss-server-side-encryption-customer-algorithm的值一致。 类型：String 有效值：AES256 |
| x-kss-server-side-encryption-customer-key-MD5 | 如果服务端使用了用户提供的加密密钥加密，则返回此响应头，值与请求头x-kss-server-side-encryption-customer-key-MD5的值一致。 |
POST /ks3.txt?append&position=0 HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Cache-control: no-cache
Content-Disposition: attachment;filename=ks3_download.txt
Date: Wed, 22 Sep 2021 06:57:01 GMT
Content-Type: text/plain
Content-Length: 100000
Authorization: authorization string
[100000 bytes of object data]
HTTP/1.1 200 OK
Date: Wed, 22 Sep 2021 06:57:01 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
x-kss-next-append-position: 100000
x-kss-request-id:614C615E5B40CC30391F3477
Server: Tengine
POST /ks3.txt?append&position=100000 HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Cache-control: no-cache
Content-Disposition: attachment;filename=ks3_download.txt
Date: Wed, 22 Sep 2021 06:57:01 GMT
Content-Type: text/plain
Content-Length: 300000
Authorization: authorization string
[300000 bytes of object data]
HTTP/1.1 200 OK
Date: Wed, 22 Sep 2021 06:57:01 GMT
ETag: "bbb8aae57c104cda40c93843ad5e6db8"
Content-Length: 0
Connection: close
x-kss-next-append-position: 400000
x-kss-request-id:79af2a64dba44f9cb7d4c870ada1bbab
Server: Tengine
| 错误码 | HTTP状态码 | 描述 |
|---|---|---|
| NotFoundApi | 400 Bad Request | 请求参数缺少append或position。 |
| ObjectNotAppendable | 409 Conflict | 不能对非Appendable Object进行Append Object操作。 |
| PositionNotEqualToLength | 409 Conflict |
|
| BadDigest | 400 Bad Request | Content-MD5的值合法，但和Append Object操作对象内容的MD5不一致。 |
| InvalidDigest | 400 Bad Request | Content-MD5的值是不合法的、无效的。 |
| InvalidArgument | 400 Bad Request | 通用请求头参数设置无效，报错信息同PUT Object。 |
| EntityTooLarge | 400 Bad Request | 单次追加不得超过5GB，对象总大小也不得超过5GB。 |
| InvalidPosition | 400 Bad Request | Position参数不合法，不是正整型，比如小于0。 |
| BadRequest | 400 Bad Request | 设置Tagging数量超过十个。 |
| InvalidTaggingFormat | 400 Bad Request | 设置无效的Tagging。 |
| OperationNotSupported | 400 Bad Request | 归档类型的文件不支持追加上传。 |
| EntityTooLarge | 400 Bad Request | 单次追加的对象大小，超过了x-kss-content-maxlength设置的值。 |
| MissingCustomerKey | 400 Bad Request | 客户端提供密钥的加密(SSE-C)，第二次追加写时，没有携带加密请求头参数。 |
| Md5NotMatchForOldMd5 | 400 Bad Request | 客户端提供密钥的加密(SSE-C)，第二次追加写时，携带的SSE-C密钥MD5与第一次时不一致。 |
| Md5ErrorForCustomerKey | 400 Bad Request | 客户端提供密钥的加密(SSE-C)，SSE-C密钥的MD5不正确。 |
| InvalidEncryptionAlgorithmErrorException | 400 Bad Request | KS3托管密钥加密（SSE-S3），提供的x-kss-server-side-encryption不是AES256 |
| AlgorithmInvalidForCustomerKeyException | 400 Bad Request | 客户端提供密钥的加密(SSE-C)，提供的x-kss-server-side-encryption不是AES256 |
| InvalidArgumentException | 400 Bad Request | 客户端提供密钥的加密(SSE-C)，缺少任意一个加密参数 |
纯净模式