APPEND Object

最后更新时间:2021-09-23 12:22:40

    功能描述

    APPEND Object 接口请求可以将一个对象以分块追加的方式上传至指定存储桶中。对象首次使用 APPEND Object 接口上传时,该对象的属性自动为 appendable ,使用其他接口上传时则属性自动为 normal (如果该对象已存在则属性会被覆盖为 normal),可以使用 GET ObjectHEAD Object 接口获取 x-cos-object-type 响应头来判断对象属性。对象属性为 appendable 时才能使用本接口追加上传。

    追加上传的对象,每个分块大小默认最大为5GB,无最小限制,同时通过追加方式产生的对象大小不得超过5GB。如果 Position 的值和当前对象的长度不致,COS 将返回409错误。如果追加一个 normal 属性的文件,COS 将返回409 ObjectNotAppendable。

    注意:

    • Appendable 的对象不可以被复制,不参与版本管理,不参与生命周期管理,不可跨地域复制。
    • 使用 APPEND 接口进行追加上传时,COS 不会校验请求携带的存储类型,仅会以当前对象的存储类型为准。
    • APPEND 接口不支持智能分层存储类型。

    请求

    请求示例

    POST /ObjectName?append&position=*position* HTTP/1.1
    Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
    Content-Length: size
    Content-Type: ContentType
    Date: GMT Date
    Authorization: Auth String
    
    说明:

    请求头

    公共头部

    该请求操作的实现使用公共请求头,了解公共请求头详情请参见 公共请求头部 文档。

    非公共头部

    必选头部
    该请求操作的实现使用如下必选头部:

    名称 描述 类型 是否必选
    Content-Length RFC 2616 中定义的 HTTP 请求内容长度(字节) String

    推荐头部
    该请求操作的实现使用如下推荐请求头部信息:

    节点名称(关键字) 描述 类型 是否必选
    Cache-Control RFC 2616 中定义的缓存策略,将作为 Object 元数据返回 String
    Content-Disposition RFC 2616 中定义的文件名称,将作为 Object 元数据返回 String
    Content-Encoding RFC 2616 中定义的编码格式,将作为 Object 元数据返回 String
    Content-MD5 RFC 1864中定义的请求体内容的16字节二进制 MD5 哈希值的 Base64 编码形式,用于完整性检查,验证请求体在传输过程中是否发生变化,最终的取值长度应为24个字符,请注意在编写代码时使用正确的方法和参数,例如ZzD3iDJdrMAAb00lgLLeig== String
    Content-Type RFC 2616 中定义的内容类型(MIME),将作为 Object 元数据返回 String
    Expect 当使用 Expect: 100-continue 时,在收到服务端确认后,才会发送请求内容 String
    Expires RFC 2616 中定义的过期时间,将作为 Object 元数据返回 String
    x-cos-meta- * 允许用户自定义的头部信息,将作为 Object 元数据返回,大小限制2K String

    权限相关头部
    该请求操作的实现可以用 POST 请求中的 x-cos-acl 头来设置文件访问权限。目前 Object 访问权限有三种:public-read-write,public-read 和 private。如果不设置,默认为 private 权限。也可以单独明确赋予用户读、写或读写权限。内容如下:

    说明:

    了解更多 ACL 请求可详细请参见 PUT Bucket acl 文档。

    名称 描述 类型 是否必选
    x-cos-acl 定义 Object 的 ACL 属性,有效值为 private,public-read-write,public-read
    默认值为 private
    String
    x-cos-grant-read 赋予被授权者读的权限,格式:x-cos-grant-read: id=" ",id=" "
  • 当需要给子账号授权时,id="qcs::cam::uin/<owneruin>:uin/<subuin>"
  • 当需要给主账号授权时,id="qcs::cam::uin/<owneruin>:uin/<owneruin>"
  • String
    x-cos-grant-write 赋予被授权者写的权限,格式:x-cos-grant-write: id=" ",id=" "
  • 当需要给子账号授权时,id="qcs::cam::uin/<owneruin>:uin/<subuin>"
  • 当需要给主账号授权时,id="qcs::cam::uin/<owneruin>:uin/<owneruin>"
  • String
    x-cos-grant-full-control 赋予被授权者读写权限,格式:x-cos-grant-full-control: id=" ",id=" "
  • 当需要给子账号授权时,id="qcs::cam::uin/<owneruin>:uin/<subuin>"
  • 当需要给主账号授权时,id="qcs::cam::uin/<owneruin>:uin/<owneruin>"
  • String

    请求参数

    具体内容如下:

    参数名称 描述 类型 是否必选
    position 追加操作的起始点,单位为字节。首次追加则设置 Position=0,后续追加则设置 Position 为当前 Object 的 content-length Int

    请求体

    该请求的请求体为空。

    响应

    响应头

    公共响应头

    该响应使用公共响应头,了解公共请求头详情请参见 公共响应头部 文档。

    特有响应头

    该请求操作的响应头具体数据为:

    节点名称(关键字) 描述 类型
    x-cos-next-append-position 下一次追加操作的起始点,单位:字节 String
    ETag 文件的唯一标识 String

    响应体

    该响应体返回为空。

    错误分析

    1. 如果对一个非 appendable 的文件进行 APPEND 操作,那么会返回409 Confilct,错误信息:
      The operation is not valid for the current state of the object。
    2. 如果请求中未携带 position 参数,会返回400 Bad Request,错误信息:InvalidArgument。
    3. 如果请求中缺失 Content-Length 头部,会返回 411 Length Required,错误信息:
      You must provide the Content-Length HTTP header。

    获取更多关于 COS 的错误码的信息,或者产品所有的错误列表,请参见 错误码 文档。

    实际案例

    请求

    POST /coss3/app?append&position=0 HTTP/1.1
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Date: Tue, 16 Jan 2016 21:32:00 GMT
    Authorization: q-sign-algorithm=sha1&q-ak=AKIDDNMEycgLRPI2axw9xa2Hhx87wZ3M****&q-sign-time=1484208848;32557104848&q-key-time=1484208848;32557104848&q-header-list=host&q-url-param-list=append;position&q-signature=855fe6b833fadf20570f7f650e2120e17ce8****
    Content-Length: 4096
    [Object]
    

    响应

    HTTP/1.1 200 OK
    Content-Type: application/xml
    Content-Length: 0
    Connection: keep-alive
    Date: Tue, 16 Jan 2016 21:32:00 GMT
    ETag: 1ce5b469b7d6600ecc2fd112e570917b
    Server: tencent-cos
    x-cos-content-sha1: 1ceaf73df40e531df3bfb26b4fb7cd95fb7bff1d
    x-cos-next-append-position: 4096
    x-cos-request-id: NTg3NzNhZGZfMmM4OGY3X2I2Zl8x****