全部产品
Search

搜索本产品

    Object Storage Service：AppendObject

    文档中心

    Object Storage Service：AppendObject

    更新时间：Dec 07, 2025

    Anda dapat memanggil operasi AppendObject untuk mengunggah objek dengan menambahkan data. Objek yang dibuat menggunakan operasi AppendObject merupakan objek Appendable, sedangkan objek yang diunggah melalui operasi PutObject adalah objek Normal.

    Pengendalian versi

    Saat melakukan operasi pada objek Appendable dalam bucket yang memiliki pengendalian versi aktif atau ditangguhkan, perhatikan hal-hal berikut:

    • Anda hanya dapat menambahkan data ke versi terkini suatu objek jika objek tersebut merupakan objek Appendable. OSS tidak membuat versi sebelumnya untuk objek Appendable ini.

      Jika Anda melakukan operasi PutObject atau DeleteObject pada versi terkini objek Appendable, OSS akan menyimpan objek tersebut sebagai versi sebelumnya. Namun, Anda tidak dapat lagi menambahkan data ke objek tersebut.

    • Anda tidak dapat melakukan operasi AppendObject pada objek non-Appendable, seperti objek Normal atau penanda hapus (delete markers).

    • Anda hanya dapat membuat versi Appendable baru jika objek tersebut belum ada atau versi terbarunya adalah penanda hapus. Untuk melakukannya, panggil AppendObject dan atur parameter position ke 0.

    Batasan

    • Ukuran akhir objek yang dibuat menggunakan AppendObject tidak boleh melebihi 5 GB.

    • Anda tidak dapat menggunakan operasi AppendObject pada objek yang dilindungi oleh kebijakan retensi.

    • Anda tidak dapat menentukan ID CMK untuk mengaktifkan enkripsi sisi server dengan Key Management Service (KMS) pada objek Appendable.

    • Kinerja pengunduhan objek Appendable jauh lebih rendah dibandingkan objek Normal atau Multipart. Pertimbangkan hal ini sesuai dengan skenario bisnis Anda.

    Izin

    Secara default, Akun Alibaba Cloud memiliki izin penuh. Pengguna RAM atau Peran RAM di bawah Akun Alibaba Cloud tidak memiliki izin apa pun secara default. Akun Alibaba Cloud atau administrator akun harus memberikan izin operasi melalui RAM Policy atau Bucket policies.

    API

    Action

    Definisi

    AppendObject

    oss:PutObject

    Anda dapat memanggil operasi ini untuk mengunggah objek dengan menambahkan objek ke objek yang sudah ada.

    oss:PutObjectTagging

    Saat mengunggah objek dengan menambahkannya ke objek yang sudah ada, jika Anda menentukan tag objek melalui x-oss-tagging, izin ini diperlukan.

    Sintaks permintaan

    POST /ObjectName?append&position=Position HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

    Header permintaan

    Nama

    Tipe

    Wajib

    Contoh

    Deskripsi

    Cache-control

    string

    Tidak

    no-cache

    Menentukan perilaku caching halaman web untuk objek. Untuk informasi selengkapnya, lihat RFC2616.

    Default: none

    Content-Disposition

    string

    Tidak

    attachment;filename=oss_download.jpg

    Menentukan nama objek saat diunduh. Untuk informasi selengkapnya, lihat RFC2616.

    Default: none

    Content-MD5

    string

    Tidak

    ohhnqLBJFiKkPSBO1eNaUA==

    Header Content-MD5 adalah nilai yang dihasilkan oleh algoritma MD5. Header ini digunakan untuk memeriksa apakah konten pesan sama dengan konten yang dikirim.

    Untuk mendapatkan nilai Content-MD5, jalankan algoritma MD5 pada isi pesan (tidak termasuk header) untuk mendapatkan angka 128-bit, lalu encode angka tersebut dalam Base64.

    Default: none

    Batasan: none

    Expires

    string

    Tidak

    Wed, 08 Jul 2015 16:57:01 GMT

    Waktu kedaluwarsa. Untuk informasi selengkapnya, lihat RFC2616.

    Default: none

    x-oss-server-side-encryption

    string

    Tidak

    AES256

    Menentukan metode enkripsi sisi server.

    Nilai yang valid:

    • AES256: menggunakan kunci yang sepenuhnya dikelola oleh OSS untuk enkripsi dan dekripsi (SSE-OSS).

    • KMS: menggunakan kunci yang dikelola oleh KMS untuk enkripsi dan dekripsi.

    x-oss-object-acl

    string

    Tidak

    private

    Menentukan izin akses objek.

    Nilai yang valid:

    • default (default): Objek mewarisi izin akses bucket.

    • private: Objek merupakan resource privat. Hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca-tulis pada objek. Pengguna lain tidak dapat mengakses objek.

    • public-read: Objek merupakan resource baca-publik. Hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca-tulis pada objek. Pengguna lain hanya memiliki izin baca. Gunakan izin ini dengan hati-hati.

    • public-read-write: Objek merupakan resource baca-tulis publik. Semua pengguna memiliki izin baca-tulis pada objek. Gunakan izin ini dengan hati-hati.

    Untuk informasi selengkapnya tentang izin akses, lihat Object ACL.

    x-oss-storage-class

    string

    Tidak

    Standard

    Menentukan kelas penyimpanan objek.

    Untuk bucket dengan kelas penyimpanan apa pun, jika Anda menentukan parameter ini saat mengunggah objek, objek yang diunggah akan disimpan dalam kelas penyimpanan yang ditentukan. Misalnya, jika Anda mengatur x-oss-storage-class ke Standard saat mengunggah objek ke bucket Infrequent Access, objek tersebut akan disimpan sebagai Standard.

    Nilai yang valid:

    • Standard: Standard

    • IA: Infrequent Access

    • Archive: Archive Storage

    Untuk informasi selengkapnya tentang kelas penyimpanan, lihat Kelas penyimpanan.

    Penting

    • Header permintaan ini hanya berlaku untuk operasi append pertama. Tidak berlaku untuk operasi append berikutnya.

    • Objek tipe Appendable tidak dapat dikonversi ke kelas penyimpanan Cold Archive atau Deep Cold Archive dengan cara apa pun.

    x-oss-meta-*

    string

    Tidak

    x-oss-meta-location

    Anda dapat menambahkan x-oss-meta-* saat membuat objek Appendable. Anda tidak dapat menyertakan parameter ini dalam operasi append berikutnya. Jika Anda mengonfigurasi parameter yang diawali dengan awalan x-oss-meta-*, parameter tersebut dianggap sebagai metadata.

    Batas ukuran metadata: Suatu objek dapat memiliki beberapa catatan metadata, tetapi ukuran total semua metadata tidak boleh melebihi 8 KB.

    Konvensi penamaan metadata: Nama metadata dapat berisi tanda hubung (-), angka, dan huruf kecil (a-z). Huruf kapital akan dikonversi menjadi huruf kecil. Karakter lain, termasuk garis bawah (_), tidak didukung.

    x-oss-tagging

    string

    Tidak

    TagA=A

    Menentukan tag objek dalam format pasangan kunci-nilai. Anda dapat menentukan beberapa tag sekaligus, misalnya TagA=A&TagB=B.

    Penting

    • Header permintaan ini hanya berlaku untuk operasi append pertama. Tidak berlaku untuk operasi append berikutnya.

    • Kunci dan nilai harus di-URL-encode. Kunci wajib diisi, sedangkan nilai bersifat opsional. Misalnya, Anda dapat mengatur tag objek menjadi TagA&TagB=B.

    Untuk informasi selengkapnya tentang header permintaan umum lainnya untuk operasi ini, lihat Header permintaan umum.

    Parameter permintaan

    Penting

    Parameter append dan position merupakan bagian dari CanonicalizedResource dan harus disertakan dalam signature.

    Nama

    Tipe

    Wajib

    Contoh

    Deskripsi

    append

    string

    Ya

    Tidak berlaku

    Menentukan operasi AppendObject. Setiap operasi AppendObject memperbarui waktu modifikasi terakhir objek.

    position

    string

    Ya

    0

    Menentukan posisi mulai penambahan data. Setelah setiap operasi berhasil, header respons x-oss-next-append-position menunjukkan posisi untuk append berikutnya.

    Posisi untuk operasi append pertama harus 0. Posisi untuk operasi append berikutnya adalah ukuran objek saat ini. Misalnya, jika posisi untuk permintaan AppendObject pertama adalah 0 dan content-length-nya 65536, maka posisi untuk permintaan AppendObject kedua harus 65536.

    • Jika posisi adalah 0 dan tidak ada objek dengan nama yang sama, permintaan AppendObject mirip dengan permintaan PutObject. Artinya, Anda dapat mengatur header permintaan seperti x-oss-server-side-encryption. Jika Anda menambahkan header x-oss-server-side-encryption yang valid, respons AppendObject berikutnya juga akan menyertakan header x-oss-server-side-encryption. Untuk mengubah metadata nanti, gunakan operasi CopyObject.

    • Jika posisi benar, menambahkan konten berukuran 0 ke objek Appendable yang sudah ada tidak mengubah status objek tersebut.

    Header respons

    Header respons

    Tipe

    Contoh

    Deskripsi

    x-oss-next-append-position

    integer 64-bit

    1717

    Posisi untuk permintaan berikutnya, yaitu ukuran objek saat ini.

    Header ini dikembalikan ketika operasi AppendObject berhasil atau ketika terjadi kesalahan 409 karena posisi tidak sesuai dengan ukuran objek.

    x-oss-hash-crc64ecma

    integer 64-bit

    3231342946509354535

    Menunjukkan nilai CRC 64-bit objek. CRC 64-bit ini dihitung berdasarkan standar CRC-64/XZ.

    Untuk informasi selengkapnya tentang header respons umum lainnya untuk operasi ini, lihat Header respons umum.

    Metode perhitungan CRC-64

    Anda dapat menggunakan metode berikut untuk melakukan perhitungan:

    • Perhitungan menggunakan modul 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();
}

    • Perhitungan menggunakan Python crcmod

      import crcmod
do_crc64 = crcmod.mkCrcFun(0x142F0E1EBA9EA3693, initCrc=0, xorOut=0xffffffffffffffff, rev=True)
print(do_crc64(b"123456789"))

    Hubungan dengan operasi lain

    Operasi lain

    Deskripsi hubungan

    PutObject

    Jika Anda melakukan operasi PutObject pada objek Appendable yang sudah ada, objek Appendable tersebut akan ditimpa oleh objek baru, dan tipenya berubah menjadi Normal.

    HeadObject

    Operasi HeadObject pada objek Appendable mengembalikan x-oss-next-append-position, x-oss-hash-crc64ecma, dan x-oss-object-type. x-oss-object-type objek Appendable adalah Appendable.

    GetBucket (ListObjects)

    Dalam respons permintaan GetBucket, Type objek Appendable diatur ke Appendable.

    Contoh

    • Contoh permintaan

      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 
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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e  
[1717 bytes of object data]

      Contoh respons

      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****

    • Contoh permintaan dengan pengendalian versi

      Jika pengendalian versi diaktifkan untuk bucket, respons permintaan AppendObject mencakup header respons x-oss-version-id, yang menentukan ID versi objek versi terkini.

      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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      Contoh respons

      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 untuk operasi ini tersedia dalam bahasa-bahasa berikut:

    Antarmuka baris perintah ossutil

    Untuk melakukan operasi ini menggunakan ossutil, lihat perintah append-object.

    Kode kesalahan

    Kode kesalahan

    Kode status HTTP

    Deskripsi

    ObjectNotAppendable

    409

    Operasi AppendObject dilakukan pada objek non-Appendable.

    PositionNotEqualToLength

    409

    • Nilai position tidak sesuai dengan panjang objek saat ini.

      Anda dapat memperoleh posisi untuk permintaan berikutnya dari header respons x-oss-next-append-position dan mencoba permintaan lagi. Karena konkurensi, permintaan mungkin tetap gagal dengan kesalahan PositionNotEqualToLength meskipun Anda mengatur posisi ke nilai x-oss-next-append-position.

    • Jika posisi adalah 0, permintaan berhasil jika tidak ada objek Appendable dengan nama yang sama, atau jika objek Appendable dengan nama yang sama memiliki panjang 0. Dalam kasus lain, posisi dianggap tidak sesuai dengan panjang objek, dan kode kesalahan ini dikembalikan.

    InvalidArgument

    400

    Nilai parameter seperti x-oss-storage-class dan x-oss-object-acl tidak valid.

    FileImmutable

    409

    Jika Anda mencoba menghapus atau mengubah data dalam bucket yang berada dalam status terlindungi, kode kesalahan ini dikembalikan.

    KmsServiceNotEnabled

    403

    Saat Anda menggunakan algoritma enkripsi KMS, Key Management Service (KMS) belum diaktifkan di Konsol.