全部產品
Search
文件中心

Object Storage Service:AppendObject

更新時間:Jul 20, 2024

調用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。

  • 當position值為0,且不存在同名Object時,則AppendObject與PutObject請求類似,即允許設定x-oss-server-side-encryption等要求標頭。如果加入了正確的x-oss-server-side-encryption頭,那麼後續的AppendObject回應標頭部也會包含x-oss-server-side-encryption頭。後續如需更改中繼資料,可以使用CopyObject介面。

  • 在position值正確的情況下,對已存在的Appendable Object追加一個大小為0的內容,該操作不會改變Object的狀態。

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

指定伺服器端加密方式。

合法值:

  • AES256:使用OSS完全託管密鑰進行加解密(SSE-OSS)。

  • KMS:使用KMS託管密鑰進行加解密。

x-oss-object-acl

字串

private

指定Object的存取權限。

取值:

  • default(預設):Object遵循所在儲存空間的存取權限。

  • private:Object是私人資源。只有Object的擁有者和授權使用者有該Object的讀寫權限,其他使用者沒有許可權操作該Object。

  • public-read:Object是公用讀取資源。只有Object的擁有者和授權使用者有該Object的讀寫權限,其他使用者只有該Object的讀許可權。請謹慎使用該許可權。

  • public-read-write:Object是公用讀寫資源。所有使用者都有該Object的讀寫權限。請謹慎使用該許可權。

關於存取權限的更多資訊,請參見設定Object ACL

x-oss-storage-class

字串

Standard

指定Object的儲存類型。

對於任意儲存類型的Bucket,如果上傳Object時指定此參數,則此次上傳的Object將儲存為指定的類型。例如在IA類型的Bucket中上傳Object時,如果指定x-oss-storage-class為Standard,則該Object直接儲存為Standard。

取值:

  • Standard:標準儲存

  • IA:低頻訪問

  • Archive:Archive Storage

關於儲存類型的更多資訊,請參見儲存類型概述

重要
  • 該要求標頭僅在首次追加操作時設定生效,後續追加操作不生效。

  • Appendable類型產生的Object,不支援以任何形式轉換為冷Archive Storage(Cold Archive)或者深度冷Archive Storage(Deep Cold Archive)類型。

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的標籤資訊,可同時設定多個標籤,例如TagA=A&TagB=B

重要
  • 該要求標頭僅在首次追加操作時設定生效,後續追加操作不生效。

  • Key和Value需進行URL編碼。其中,Key為必選項,Value為可選項,即Object標籤資訊可設定為TagA&TagB=B

關於此介面涉及的其他公用要求標頭的更多資訊,請參見公用要求標頭(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”)

和其他動作的關係

其他動作

關係描述

PutObject

如果對一個已經存在的Appendable Object進行PutObject操作,該Appendable Object會被新的Object覆蓋,類型轉換為Normal Object。

HeadObject

對Appendable Object執行HeadObject操作會返回x-oss-next-append-position、x-oss-hash-crc64ecma以及x-oss-object-type。Appendable Object的x-oss-object-type為Appendable。

GetBucket (ListObjects)

在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

  • position的值和當前Object的長度不一致。

    您可以通過回應標頭x-oss-next-append-position得到下一次position,並再次進行請求。由於並發的關係,即使把position的值設定為x-oss-next-append-position,該請求依然可能因為PositionNotEqualToLength而失敗。

  • position值為0時,如果沒有同名Appendable Object,或者同名Appendable Object長度為0,該請求成功;其他情況均視為position和Object長度不匹配的情形,返回此錯誤碼。

InvalidArgument

400

x-oss-storage-classx-oss-object-acl等值設定無效。

FileImmutable

409

Bucket內的資料處於被保護狀態時,如果您嘗試刪除或修改這些資料,將返回此錯誤碼。

KmsServiceNotEnabled

403

使用KMS密碼編譯演算法時,沒有在控制台預先開通Key Management Service。