調用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。
處於保留原則保護期的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
要求標頭
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。
|
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 | 指定伺服器端加密方式。 合法值:
|
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)。
回應標頭
響應訊息頭 | 類型 | 樣本 | 描述 |
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密碼編譯演算法時,沒有在控制台預先開通Key Management Service。 |