調用AppendObject接口用于以追加寫的方式上傳文件(Object)。通過AppendObject操作創建的Object類型為Appendable Object,而通過PutObject上傳的Object是Normal Object。
版本控制
在目標Bucket處于開啟或暫停版本控制狀態下,對Appendable類型Object執行相關操作時,有如下注意事項:
僅允許對當前版本為Appendable類型的Object執行追加上傳(AppendObject)操作,且OSS不會為該Appendable類型的Object生成歷史版本。
對當前版本為Appendable類型的Object執行PutObject或DeleteObject操作時,OSS會將該Appendable類型的Object保留為歷史版本,但該Object不允許繼續追加。
不支持對非Appendable類型的Object,包括Normal Object、刪除標記(Delete Marker)等執行AppendObject操作。
使用限制
通過AppendObject方式最后生成的Object大小不得超過5 GB。
處于保留策略(WORM)保護期的Object不支持AppendObject操作。
AppendableObject不支持指定CMK ID進行服務端KMS加密。
請求語法
POST /ObjectName?append&position=Position HTTP/1.1
Content-Length:ContentLength
Content-Type: ContentType
Host: BucketName.oss.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
當您在OSS ON云盒中調用該接口時,您需要將Host替換為云盒Endpoint。更多信息,請參見云盒Endpoint。
請求頭
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
Cache-control | 字符串 | 否 | no-cache | 指定該Object的網頁緩存行為。更多信息,請參見RFC2616。 默認值:無 |
Content-Disposition | 字符串 | 否 | attachment;filename=oss_download.jpg | 指定該Object被下載時的名稱。更多信息,請參見RFC2616。 默認值:無 |
Content-Encoding | 字符串 | 否 | utf-8 | 指定該Object的內容編碼格式。更多信息,請參見RFC2616。 默認值:無 |
Content-MD5 | 字符串 | 否 | ohhnqLBJFiKkPSBO1eNaUA== | Content-MD5是一串由MD5算法生成的值,該請求頭用于檢查消息內容是否與發送時一致。 獲取Content-MD5值:對消息內容(不包括頭部)執行MD5算法,獲得128比特位數字,然后對該數字進行base64編碼。 默認值:無 限制:無 |
Expires | GMT | 否 | Wed, 08 Jul 2015 16:57:01 GMT | 過期時間。更多信息,請參見RFC2616。 默認值:無 |
x-oss-server-side-encryption | 字符串 | 否 | AES256 | 指定服務器端加密方式。 合法值:
說明 在OSS ON云盒使用場景中,僅支持AES256。 |
x-oss-object-acl | 字符串 | 否 | private | 指定Object的訪問權限。 取值:
關于訪問權限的更多信息,請參見設置Object ACL。 |
x-oss-storage-class | 字符串 | 否 | Standard | 指定Object的存儲類型。 對于任意存儲類型的Bucket,如果上傳Object時指定此參數,則此次上傳的Object將存儲為指定的類型。例如在IA類型的Bucket中上傳Object時,如果指定x-oss-storage-class為Standard,則該Object直接存儲為Standard。 取值:
關于存儲類型的更多信息,請參見存儲類型概述。 重要
|
x-oss-meta-* | 字符串 | 否 | x-oss-meta-location | 創建AppendObject時可以添加x-oss-meta-*,繼續追加時不可以攜帶此參數。如果配置以x-oss-meta-*為前綴的參數,則該參數視為元數據。 元數據大小限制:一個Object可以包含多個元數據,但所有的元數據總大小不能超過8 KB。 元數據命名規則:支持短劃線(-)、數字、英文字母(a~z)。英文字符的大寫字母會被轉成小寫字母,不支持下劃線(_)在內的其他字符。 |
x-oss-tagging | 字符串 | 否 | TagA=A | 以鍵值對(Key-Value)的形式指定Object的標簽信息,可同時設置多個標簽,例如 重要
|
關于此接口涉及的其他公共請求頭的更多信息,請參見公共請求頭(Common Request Headers)。
請求參數
append和position均為CanonicalizedResource,需要包含在簽名中。
名稱 | 類型 | 是否必選 | 示例值 | 描述 |
append | 字符串 | 是 | 不涉及 | 用于指定AppendObject操作。每次執行AppendObject都會更新該Object的最后修改時間。 |
position | 字符串 | 是 | 0 | 用于指定從何處進行追加。 每次操作成功后,響應消息頭x-oss-next-append-position會標明下一次追加的position。 首次追加操作的position必須為0,后續追加操作的position是Object的當前大小。例如,第一次AppendObject請求指定position值為0,content-length是65536,則第二次AppendObject需要指定position為65536。
|
響應頭
響應消息頭 | 類型 | 示例 | 描述 |
x-oss-next-append-position | 64位整型 | 1717 | 下一次請求應當提供的position,即當前Object大小。 當AppendObject執行成功,或者因position和Object大小不匹配而引起的409錯誤時,會返回此消息頭。 |
x-oss-hash-crc64ecma | 64位整型 | 3231342946509354535 | 表明Object的64位CRC值。該64位CRC由ECMA-182標準計算得出。 |
關于此接口涉及的其他公共響應頭的更多信息,請參見公共響應頭(Common Response Headers)。
CRC64的計算方式
Appendable Object的CRC64采用ECMA-182標準。您可以使用以下方法進行計算:
用Boost CRC模塊的方式計算
typedef boost::crc_optimal<64, 0x42F0E1EBA9EA3693ULL, 0xffffffffffffffffULL, 0xffffffffffffffffULL, true, true> boost_ecma; uint64_t do_boost_crc(const char* buffer, int length) { boost_ecma crc; crc.process_bytes(buffer, length); return crc.checksum(); }
用Python crcmod的方式計算
do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693L, initCrc=0L, xorOut=0xffffffffffffffffL, rev=True) print do_crc64(“123456789”)
和其他操作的關系
其他操作 | 關系描述 |
如果對一個已經存在的Appendable Object進行PutObject操作,該Appendable Object會被新的Object覆蓋,類型轉換為Normal Object。 | |
對Appendable Object執行HeadObject操作會返回x-oss-next-append-position、x-oss-hash-crc64ecma以及x-oss-object-type。Appendable Object的x-oss-object-type為Appendable。 | |
在GetBucket請求的響應中,會將Appendable Object的Type設為Appendable。 |
示例
請求示例
POST /oss.jpg?append&position=0 HTTP/1.1 Host: oss-example.oss.aliyuncs.com Cache-control: no-cache Expires: Wed, 08 Jul 2015 16:57:01 GMT Content-Encoding: utf-8 x-oss-storage-class: Archive Content-Disposition: attachment;filename=oss_download.jpg Date: Wed, 08 Jul 2015 06:57:01 GMT Content-Type: image/jpg Content-Length: 1717 Authorization: OSS qn6q**************:77Dv**************** [1717 bytes of object data]
返回示例
HTTP/1.1 200 OK Date: Wed, 08 Jul 2015 06:57:01 GMT ETag: "0F7230CAA4BE94CCBDC99C550000****" Connection: keep-alive Content-Length: 0 Server: AliyunOSS x-oss-hash-crc64ecma: 14741617095266562575 x-oss-next-append-position: 1717 x-oss-request-id: 559CC9BDC755F95A6448****
版本控制請求示例
對于開啟版本控制的Bucket,AppendObject的響應Header中會返回x-oss-version-id,其值為當前版本Object的版本ID。
POST /example?append&position=0 HTTP/1.1 Host: versioning-append.oss.aliyuncs.com Date: Tue, 09 Apr 2019 03:59:33 GMT Content-Length: 3 Content-Type: application/octet-stream Authorization: OSS qn6q**************:77Dv****************
返回示例
HTTP/1.1 200 OK Date: Tue, 09 Apr 2019 03:59:33 GMT ETag: "2776271A4A09D82CA518AC5C0000****" Connection: keep-alive Content-Length: 0 Server: AliyunOSS x-oss-version-id: CAEQGhiBgIC_k6aV5RgiIGI3YTY2ZmMzYWJlMzQ3YjM4YTljOTk5YjUyZGF**** x-oss-hash-crc64ecma: 3231342946509354535 x-oss-next-append-position: 47 x-oss-request-id: 5CAC18A5B7AEADE01700****
SDK
此接口所對應的各語言SDK如下:
錯誤碼
錯誤代碼 | HTTP 狀態碼 | 說明 |
ObjectNotAppendable | 409 | 對一個非Appendable Object進行AppendObject操作。 |
PositionNotEqualToLength | 409 |
|
InvalidArgument | 400 | x-oss-storage-class、x-oss-object-acl等值設置無效。 |
FileImmutable | 409 | Bucket內的數據處于被保護狀態時,如果您嘗試刪除或修改這些數據,將返回此錯誤碼。 |
KmsServiceNotEnabled | 403 | 使用KMS加密算法時,沒有在控制臺預先開通密鑰管理服務KMS。 |