CompleteMultipartUpload - Object Storage Service

Menyelesaikan tugas unggah multipart dari sebuah objek setelah semua bagian diunggah.

Catatan

Saat memanggil operasi CompleteMultipartUpload, Anda harus menyediakan daftar lengkap semua bagian yang valid, termasuk nomor bagian dan entity tag (ETag) untuk setiap bagian. Setelah Object Storage Service (OSS) menerima daftar tersebut, OSS akan memverifikasi keabsahan setiap bagian satu per satu. Jika semua bagian divalidasi, OSS menggabungkan bagian-bagian tersebut menjadi satu objek utuh.

Konfirmasi ukuran setiap bagian
Saat memanggil operasi CompleteMultipartUpload, OSS memeriksa apakah setiap bagian, kecuali bagian terakhir, memiliki ukuran minimal 100 KB serta memverifikasi nomor bagian dan ETag dari setiap bagian dalam daftar. Oleh karena itu, saat sebuah bagian diunggah, klien harus mencatat nomor bagian dan nilai ETag yang dikembalikan oleh server.
Penanganan permintaan
Proses penyelesaian permintaan CompleteMultipartUpload membutuhkan waktu. Jika klien terputus selama periode ini, OSS tetap akan melanjutkan pemrosesan permintaan.
PartNumber
OSS memverifikasi nilai PartNumber saat Anda memanggil operasi CompleteMultipartUpload.
Nilai PartNumber berkisar antara 1 hingga 10000. Nomor bagian dalam permintaan tidak harus berurutan, namun harus diurutkan secara menaik. Sebagai contoh, jika nomor bagian pertama adalah 1, nomor bagian kedua bisa saja 5.
UploadId
Sebuah objek dapat diunggah melalui beberapa tugas unggah dengan ID unggah independen. Saat satu tugas selesai, ID unggahnya menjadi tidak valid, tetapi ID unggah dari tugas lainnya tetap aktif.
x-oss-server-side-encryption
Jika header x-oss-server-side-encryption ditentukan dalam permintaan InitiateMultipartUpload, header ini akan dikembalikan dalam respons terhadap permintaan CompleteMultipartUpload. Nilai header tersebut menunjukkan metode enkripsi yang digunakan untuk mengenkripsi objek di server OSS.

Pengelolaan Versi

Anda dapat memanggil operasi CompleteMultipartUpload untuk menyelesaikan tugas unggah multipart dari sebuah objek ketika pengelolaan versi diaktifkan pada bucket tempat objek diunggah. Dalam hal ini, OSS menghasilkan ID versi unik untuk objek tersebut dan mengembalikan ID versi sebagai header x-oss-version-id dalam respons.

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 harus memberikan izin operasi melalui Kebijakan RAM atau Kebijakan Bucket.

API	Aksi	Definisi
CompleteMultipartUpload	`oss:PutObject`	Menggabungkan bagian-bagian menjadi sebuah objek.
CompleteMultipartUpload	`oss:PutObjectTagging`	Saat menggabungkan bagian-bagian menjadi sebuah objek, jika Anda menentukan tag objek melalui x-oss-tagging, izin ini diperlukan.

Sintaks Permintaan

POST /ObjectName?uploadId=UploadId HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Content-Length: Size
Authorization: Signature
<CompleteMultipartUpload>
<Part>
<PartNumber>PartNumber</PartNumber>
<ETag>ETag</ETag>
</Part>
...
</CompleteMultipartUpload>

Parameter Permintaan

Anda dapat mengonfigurasi parameter encoding-type dalam permintaan CompleteMultipartUpload. OSS menggunakan jenis penyandian yang ditentukan untuk menyandikan nama objek dalam respons.

Parameter

Tipe

Deskripsi

encoding-type

String

Jenis penyandian nama objek dalam respons. Hanya penyandian URL yang didukung.

Nama objek dapat berisi karakter yang disandikan dalam UTF-8. Namun, standar XML 1.0 tidak dapat digunakan untuk mengurai karakter kontrol, seperti karakter dengan nilai ASCII dari 0 hingga 10. Anda dapat mengonfigurasi parameter ini untuk menyandikan nama objek dalam respons.

Secara default, header ini dibiarkan kosong.

Nilai valid: url.

Header Permintaan

Header

Tipe

Wajib

Deskripsi

x-oss-forbid-overwrite

String

Tidak

Menentukan apakah objek dengan nama objek yang sama ditimpa saat Anda memanggil operasi CompleteMultipartUpload.

Jika x-oss-forbid-overwrite tidak ditentukan atau diatur ke false, objek yang ada dapat ditimpa oleh objek dengan nama yang sama.
Jika x-oss-forbid-overwrite diatur ke true, objek yang ada tidak dapat ditimpa oleh objek dengan nama yang sama.

Catatan

Header permintaan x-oss-forbid-overwrite tidak valid jika pengelolaan versi diaktifkan atau ditangguhkan untuk bucket. Dalam hal ini, operasi CompleteMultipartUpload menimpa objek dengan nama yang sama.
Jika Anda menentukan header permintaan x-oss-forbid-overwrite, kinerja queries per second (QPS) OSS mungkin menurun. Jika Anda ingin mengonfigurasi header x-oss-forbid-overwrite dalam sejumlah besar permintaan (lebih dari 1.000 QPS), ajukan Tiket.

x-oss-complete-all

String

Tidak

Menentukan apakah akan mencantumkan semua bagian yang diunggah menggunakan ID unggah saat ini.

Nilai valid: yes.

Jika x-oss-complete-all diatur ke yes dalam permintaan, OSS mencantumkan semua bagian yang diunggah menggunakan ID unggah saat ini, mengurutkan bagian-bagian berdasarkan nomor bagian, dan kemudian melakukan operasi CompleteMultipartUpload. Saat OSS melakukan operasi CompleteMultipartUpload, OSS tidak dapat mendeteksi bagian-bagian yang belum diunggah atau sedang diunggah. Sebelum Anda memanggil operasi CompleteMultipartUpload, pastikan semua bagian telah diunggah.
Jika x-oss-complete-all ditentukan dalam permintaan, badan permintaan tidak dapat ditentukan. Jika tidak, kesalahan akan terjadi.
Jika x-oss-complete-all ditentukan dalam permintaan, format respons tetap tidak berubah.

Untuk informasi lebih lanjut tentang header permintaan umum seperti Host dan Date dalam permintaan CompleteMultipartUpload, lihat Header HTTP Umum.

Elemen Permintaan

Elemen	Tipe	Deskripsi
CompleteMultipartUpload	Container	Wadah yang menyimpan konten permintaan CompleteMultipartUpload. Node anak: Part. Node induk: none.
ETag	String	Nilai ETag yang dikembalikan oleh OSS setelah bagian-bagian diunggah. Node induk: Part.
Part	Container	Wadah yang menyimpan bagian-bagian yang diunggah. Node anak: ETag dan PartNumber. Node induk: CompleteMultipartUpload.
PartNumber	Integer	Nomor bagian. Node induk: Part.

Elemen Respons

Elemen	Tipe	Deskripsi
Bucket	String	Nama bucket yang berisi objek yang ingin Anda pulihkan. Node induk: CompleteMultipartUploadResult.
CompleteMultipartUploadResult	Container	Wadah yang menyimpan hasil permintaan CompleteMultipartUpload. Node anak: Bucket, Key, ETag, dan Location. Node induk: none.
ETag	String	ETag yang dihasilkan saat objek dibuat. ETag digunakan untuk mengidentifikasi konten objek. Jika objek dibuat dengan memanggil operasi CompleteMultipartUpload, nilai ETag bukan hash MD5 dari konten objek tetapi nilai unik yang dihitung berdasarkan aturan tertentu. Catatan ETag objek dapat digunakan untuk memeriksa apakah konten objek dimodifikasi. Namun, kami merekomendasikan Anda menggunakan hash MD5 objek daripada nilai ETag objek untuk memverifikasi integritas data. Node induk: CompleteMultipartUploadResult.
Location	String	URL yang digunakan untuk mengakses objek yang diunggah. Node induk: CompleteMultipartUploadResult.
Key	String	Nama objek yang diunggah. Node induk: CompleteMultipartUploadResult.
EncodingType	String	Jenis penyandian nama objek dalam respons. Jika parameter ini ditentukan dalam permintaan, nama objek disandikan dalam respons. Node induk: Container.

Contoh

Menyelesaikan tugas unggah multipart dari sebuah objek dalam bucket tanpa versi

Contoh permintaan

POST /multipart.data?uploadId=0004B9B2D2F7815C432C9057C031****&encoding-type=url HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 1056
Date: Fri, 24 Feb 2012 10:19:18 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<CompleteMultipartUpload> 
    <Part> 
        <PartNumber>1</PartNumber>  
        <ETag>"3349DC700140D7F86A0784842780****"</ETag> 
    </Part>  
    <Part> 
        <PartNumber>5</PartNumber>  
        <ETag>"8EFDA8BE206636A695359836FE0A****"</ETag> 
    </Part>  
    <Part> 
        <PartNumber>8</PartNumber>  
        <ETag>"8C315065167132444177411FDA14****"</ETag> 
    </Part> 
</CompleteMultipartUpload>

Contoh respons sukses

HTTP/1.1 200 OK
Server: AliyunOSS
Content-Length: 329
Content-Type: Application/xml
Connection: keep-alive
x-oss-request-id: 594f0751-3b1e-168f-4501-4ac71d21****
Date: Fri, 24 Feb 2012 10:19:18 GMT
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <EncodingType>url</EncodingType>
    <Location>http://oss-example.oss-cn-hangzhou.aliyuncs.com /multipart.data</Location>
    <Bucket>oss-example</Bucket>
    <Key>multipart.data</Key>
    <ETag>"B864DB6A936D376F9F8D3ED3BBE540****"</ETag>
</CompleteMultipartUploadResult>

Memodifikasi ACL objek dalam bucket yang memiliki versi

Contoh permintaan

POST /multipart.data?uploadId=63C06A5CFF6F4AE4A6BB3AD7F01C****  HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 223
Date: Tue, 09 Apr 2019 07:01:56 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<CompleteMultipartUpload> 
    <Part> 
        <PartNumber>1</PartNumber>  
        <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag> 
    </Part>  
    <Part> 
        <PartNumber>5</PartNumber>  
        <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag> 
    </Part>  
</CompleteMultipartUpload>

Contoh respons sukses

HTTP/1.1 200 OK
Server: AliyunOSS
Content-Length: 314
Content-Type: Application/xml
Connection: keep-alive
x-oss-version-id: CAEQMxiBgID6v86D0BYiIDc3ZDI0YTBjZGQzYjQ2Mjk4OWVjYWNiMDljYzhlN****
x-oss-request-id: 5CAC4364B7AEADE017000662
Date: Tue, 09 Apr 2019 07:01:56 GMT
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
  <Location>http://oss-example.oss-cn-hangzhou.aliyuncs.com/multipart.data</Location>
  <Bucket>oss-example</Bucket>
  <Key>multipart.data</Key>
  <ETag>"097DE458AD02B5F89F9D0530231876****"</ETag>
</CompleteMultipartUploadResult>

SDK OSS

Anda dapat menggunakan SDK OSS untuk bahasa pemrograman berikut guna memanggil operasi CompleteMultipartUpload:

ossutil

Untuk informasi tentang perintah ossutil yang sesuai dengan operasi CompleteMultipartUpload, lihat complete-multipart-upload.

Kode kesalahan

Kode kesalahan

Status HTTP

Deskripsi

InvalidDigest

400

Nilai Content-MD5 dalam permintaan berbeda dari hash MD5 yang dihitung oleh OSS. Untuk mencegah kesalahan selama transmisi data, Anda dapat menyertakan nilai Content-MD5 dalam permintaan. OSS menghitung hash MD5 dari data yang diunggah dan membandingkannya dengan nilai Content-MD5 dalam permintaan.

FileAlreadyExists

409

Penyebab yang mungkin:

Permintaan berisi header x-oss-forbid-overwrite=true, dan bucket berisi objek dengan nama yang sama dengan objek yang ingin Anda unggah.
Objek tempat Anda ingin melakukan operasi CompleteMultipartUpload adalah direktori dalam bucket yang fitur namespace hierarkisnya diaktifkan.