AppendObject - Object Storage Service - Alibaba Cloud Documentation Center

Panggil operasi AppendObject untuk mengunggah objek dengan menambahkan data. Objek yang dibuat menggunakan operasi ini bersifat Appendable, sedangkan objek yang diunggah melalui operasi PutObject bersifat Normal.

Pengendalian versi

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

Anda hanya dapat menambahkan data ke versi terkini objek Appendable. OSS tidak membuat versi sebelumnya selama operasi ini.
Jika Anda melakukan operasi PutObject atau DeleteObject pada versi terkini objek Appendable, OSS akan menyimpannya sebagai versi sebelumnya, dan Anda tidak dapat lagi menambahkan data ke objek tersebut.
Operasi AppendObject tidak dapat dilakukan pada objek non-Appendable, seperti objek Normal atau delete marker.
Anda hanya dapat membuat versi Appendable baru jika objek tersebut belum ada atau versi terbarunya adalah delete marker. Untuk melakukannya, panggil operasi AppendObject dan atur parameter position ke 0.

Catatan penggunaan

Ukuran objek yang dibuat melalui operasi AppendObject tidak boleh melebihi 5 GB.
Operasi AppendObject tidak didukung untuk objek yang dilindungi oleh kebijakan retensi tingkat bucket.
Anda tidak dapat menentukan ID CMK untuk mengaktifkan enkripsi sisi server dengan KMS pada objek Appendable.
Kinerja pengunduhan objek Appendable jauh lebih rendah dibandingkan objek Normal atau objek yang diunggah menggunakan unggah multi-bagian. Evaluasi kebutuhan bisnis Anda sebelum menggunakan objek Appendable.
Jika kebijakan retensi tingkat objek diaktifkan untuk suatu bucket, Anda tidak dapat menggunakan operasi AppendObject untuk mengunggah objek.

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 kebijakan RAM atau Bucket Policy.

API

Action

Description

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 menambahkan objek ke objek yang sudah ada, jika Anda menentukan tag objek melalui x-oss-tagging, izin ini diperlukan.

Sintaksis 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

Parameter	Type	Required	Example	Description
Cache-control	String	No	no-cache	Menentukan cara objek di-cache oleh browser web dan proxy. Untuk informasi selengkapnya, lihat RFC2616. Nilai default: none
Content-Disposition	String	No	attachment;filename=oss_download.jpg	Menentukan nama file objek saat diunduh. Untuk informasi selengkapnya, lihat RFC2616. Nilai default: none
Content-MD5	String	No	ohhnqLBJFiKkPSBO1eNaUA==	Header Content-MD5 adalah nilai yang dihasilkan menggunakan algoritma MD5. Header ini digunakan untuk memeriksa integritas isi pesan. 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. Nilai default: none Batasan: none
Expires	String	No	Wed, 08 Jul 2015 16:57:01 GMT	Waktu kedaluwarsa. Untuk informasi selengkapnya, lihat RFC2616. Nilai default: none
x-oss-server-side-encryption	String	No	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	No	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 dan tulis pada objek tersebut. public-read: Objek merupakan resource publik-baca. Hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca dan tulis pada objek tersebut. Pengguna lain hanya memiliki izin baca. Berhati-hatilah saat memberikan izin ini. public-read-write: Objek merupakan resource publik-baca-tulis. Semua pengguna memiliki izin baca dan tulis pada objek tersebut. Berhati-hatilah saat memberikan izin ini. Untuk informasi selengkapnya tentang izin akses, lihat Object ACL.
x-oss-storage-class	String	No	Standard	Menentukan kelas penyimpanan objek. Jika Anda menentukan header ini saat mengunggah objek, objek akan disimpan dalam kelas penyimpanan yang ditentukan, terlepas dari kelas penyimpanan default bucket. Misalnya, jika Anda mengatur x-oss-storage-class ke Standard saat mengunggah objek ke bucket Infrequent Access (IA), objek tersebut akan disimpan dalam kelas penyimpanan Standard. Nilai yang valid: Standard: Standard IA: Infrequent Access (IA) Archive: Archive Untuk informasi selengkapnya tentang kelas penyimpanan, lihat Storage classes. Penting Header ini hanya berlaku untuk operasi append pertama pada suatu objek. Objek Appendable tidak dapat dikonversi ke kelas penyimpanan Cold Archive atau Deep Cold Archive.
x-oss-meta-*	String	No	x-oss-meta-location	Header ini hanya dapat ditambahkan saat membuat objek Appendable, bukan pada permintaan append berikutnya. Setiap header dengan awalan x-oss-meta-* dianggap sebagai metadata objek. Total ukuran semua metadata objek tidak boleh melebihi 8 KB. Konvensi penamaan metadata: Nama metadata yang ditentukan pengguna dapat berisi tanda hubung (-), angka, dan huruf. Huruf kapital akan diubah menjadi huruf kecil. Karakter lain, seperti garis bawah (_), tidak didukung.
x-oss-tagging	String	No	TagA=A	Menentukan tag objek dalam format pasangan kunci-nilai. Anda dapat menentukan beberapa tag sekaligus. Contoh: `TagA=A&TagB=B`. Penting Header ini hanya berlaku untuk operasi append pertama pada suatu objek. Kunci dan nilai harus di-URL-encode. Kunci wajib diisi, sedangkan nilai opsional. Misalnya, Anda dapat mengatur tag objek menjadi `TagA&TagB=B`.

Untuk informasi selengkapnya tentang header permintaan umum untuk operasi ini, lihat Common Request Headers.

Parameter permintaan

Penting

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

Parameter

Type

Required

Example

Description

append

String

Yes

Not applicable

Menentukan bahwa ini adalah operasi AppendObject. Setiap operasi AppendObject memperbarui waktu modifikasi terakhir objek.

position

String

Yes

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

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

Jika Anda mengatur position ke 0 dan tidak ada objek dengan nama yang sama, permintaan AppendObject diproses seperti permintaan PutObject. 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 memodifikasi metadata nanti, gunakan operasi CopyObject.
Jika nilai position valid, menambahkan data 0 byte ke objek Appendable yang sudah ada tidak mengubah status objek tersebut.

Header respons

Response header

Type

Example

Description

x-oss-next-append-position

64-bit integer

1717

Posisi untuk operasi append berikutnya, yaitu ukuran objek saat ini.

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

x-oss-hash-crc64ecma

64-bit integer

3231342946509354535

Menunjukkan nilai Pemeriksaan redundansi siklik 64-bit (CRC) objek, dihitung berdasarkan standar ECMA-182.

Untuk informasi selengkapnya tentang header respons umum untuk operasi ini, lihat Common Response Headers.

Metode perhitungan CRC-64

Anda dapat menggunakan metode berikut untuk menghitung nilai CRC-64:

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();
}

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

Other operation	Description
PutObject	Menggunakan PutObject pada objek Appendable yang sudah ada akan menimpanya dan mengubah jenisnya menjadi Normal.
HeadObject	Operasi HeadObject pada objek Appendable mengembalikan header x-oss-next-append-position, x-oss-hash-crc64ecma, dan x-oss-object-type. Nilai x-oss-object-type untuk objek Appendable adalah Appendable.
GetBucket (ListObjects)	Dalam respons permintaan GetBucket, nilai Type untuk 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 suatu bucket, respons terhadap permintaan AppendObject mencakup header x-oss-version-id. Nilai header ini adalah ID versi dari versi terkini objek.

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

CLI (ossutil)

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

Kode error

Error code	HTTP status code	Description
ObjectNotAppendable	409	Mencoba menambahkan data ke objek non-Appendable.
PositionNotEqualToLength	409	Nilai position tidak sesuai dengan panjang objek saat ini. Anda dapat memperoleh posisi yang benar dari header respons x-oss-next-append-position dan mencoba ulang permintaan. Namun, karena konkurensi, permintaan yang dicoba ulang mungkin tetap gagal dengan error PositionNotEqualToLength. Ketika position bernilai 0, permintaan berhasil hanya jika objek dengan nama yang sama tidak ada atau memiliki panjang 0. Jika tidak, error ini dikembalikan.
InvalidArgument	400	Nilai yang ditentukan untuk parameter, seperti x-oss-storage-class atau x-oss-object-acl, tidak valid.
FileImmutable	409	Error ini dikembalikan saat mencoba memodifikasi data dalam bucket yang dilindungi oleh kebijakan retensi.
KmsServiceNotEnabled	403	Error ini terjadi saat Anda mencoba menggunakan algoritma enkripsi KMS, tetapi Key Management Service (KMS) belum diaktifkan.