API untuk memulai unggah multi-bagian - Object Storage Service

Untuk mengunggah data menggunakan unggah multi-bagian, pertama-tama panggil operasi InitiateMultipartUpload guna memulai tugas unggah multi-bagian di OSS.

Catatan penggunaan

Operasi ini mengembalikan ID unggah yang unik secara global dari OSS untuk mengidentifikasi tugas unggah multi-bagian. Anda dapat menggunakan ID ini dalam operasi berikutnya, seperti membatalkan atau mengkueri unggahan tersebut.
Permintaan InitiateMultipartUpload tidak memengaruhi objek yang sudah ada dengan nama yang sama.
Saat menghitung signature otentikasi untuk operasi InitiateMultipartUpload, Anda harus menambahkan ?uploads ke CanonicalizedResource.
Untuk memulai tugas unggah multi-bagian, Anda harus memiliki izin oss:PutObject. Untuk informasi selengkapnya, lihat Berikan kebijakan kustom kepada RAM user.

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

API	Action	Deskripsi
InitiateMultipartUpload	`oss:PutObject`	Menginisialisasi tugas unggah multi-bagian.
	`oss:PutObjectTagging`	Saat menginisialisasi tugas unggah multi-bagian, jika Anda menentukan tag objek melalui x-oss-tagging, izin ini diperlukan.
	`kms:GenerateDataKey`	Saat mengunggah objek, jika metadata objek berisi X-Oss-Server-Side-Encryption: KMS, kedua izin ini diperlukan.
	`kms:Decrypt`

Sintaksis permintaan

POST /ObjectName?uploads HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT date
Authorization: SignatureValue

Header permintaan

Permintaan InitiateMultipartUpload mendukung header permintaan HTTP standar seperti Cache-Control, Content-Disposition, Content-Encoding, Content-Type, dan Expires, serta mendukung header kustom dengan awalan x-oss-meta-. Untuk informasi selengkapnya, lihat PutObject.

Header	Tipe	Deskripsi
Cache-Control	String	Menentukan perilaku caching untuk halaman web saat objek diunduh. Untuk informasi selengkapnya, lihat RFC 2616. Nilai default: Tidak ada
Content-Disposition	String	Menentukan nama objek saat diunduh. Untuk informasi selengkapnya, lihat RFC 2616. Nilai default: Tidak ada
Content-Encoding	String	Menentukan format encoding konten objek saat diunduh. Untuk informasi selengkapnya, lihat RFC 2616. Nilai default: Tidak ada
Expires	String	Waktu kedaluwarsa. Untuk informasi selengkapnya, lihat RFC 2616. Nilai default: Tidak ada
x-oss-forbid-overwrite	String	Menentukan apakah objek dengan nama yang sama boleh ditimpa. Jika Pengendalian versi diaktifkan atau ditangguhkan untuk bucket tujuan, header permintaan x-oss-forbid-overwrite akan diabaikan, dan objek dapat ditimpa. Jika Anda tidak menentukan x-oss-forbid-overwrite atau mengatur x-oss-forbid-overwrite ke false, Anda dapat menimpa objek dengan nama yang sama. Mengatur x-oss-forbid-overwrite ke true mencegah penimpaan objek dengan nama yang sama. Menetapkan header permintaan x-oss-forbid-overwrite mengurangi performa permintaan per detik (QPS), sehingga jika Anda memiliki banyak operasi yang memerlukan header permintaan x-oss-forbid-overwrite (QPS>1000), harap hubungi dukungan teknis untuk menghindari dampak pada bisnis Anda.
x-oss-server-side-encryption	String	Algoritma Enkripsi sisi server untuk setiap bagian objek. Nilai yang valid: AES256, KMS Penting Untuk menggunakan enkripsi KMS, Anda harus mengaktifkan Key Management Service (KMS). Jika Anda menentukan header ini dalam permintaan, OSS menyertakannya dalam respons. OSS mengenkripsi setiap bagian yang diunggah menggunakan algoritma yang ditentukan. Saat Anda mengunduh objek, header x-oss-server-side-encryption disertakan dalam respons, dan nilainya diatur ke algoritma enkripsi objek tersebut.
x-oss-server-side-encryption-key-id	String	ID kunci master pelanggan (CMK) yang dikelola oleh KMS. Header ini hanya berlaku ketika x-oss-server-side-encryption diatur ke KMS.
x-oss-storage-class	String	Kelas penyimpanan objek. Untuk bucket dengan kelas penyimpanan apa pun, jika Anda menentukan kelas penyimpanan saat mengunggah objek, objek tersebut akan disimpan sebagai kelas penyimpanan yang ditentukan. Misalnya, jika Anda mengunggah objek ke bucket Infrequent Access (IA) dan mengatur x-oss-storage-class ke Standard, objek tersebut langsung disimpan sebagai kelas penyimpanan Standard. Nilai yang valid: Standard IA: Infrequent Access Archive ColdArchive DeepColdArchive Penting Menetapkan kelas penyimpanan ke Deep Cold Archive saat pengunggahan mengakibatkan biaya PUT request fees yang lebih tinggi. Kami menyarankan agar Anda menetapkan kelas penyimpanan objek ke Standard saat mengunggah objek, lalu mengonfigurasi aturan siklus hidup untuk mengonversi kelas penyimpanan objek Standard menjadi Deep Cold Archive. Hal ini mengurangi biaya permintaan PUT. Untuk informasi selengkapnya, lihat Kelas penyimpanan.
x-oss-tagging	String	Menentukan tag untuk objek. Anda dapat menentukan beberapa tag untuk satu objek. Contoh: `TagA=A&TagB=B` Catatan Kunci dan nilai tag harus di-encode URL. Jika tag tidak mengandung tanda sama dengan (`=`), nilainya dianggap sebagai string kosong.
x-oss-object-worm-mode	String	Mode kebijakan retensi untuk objek. Tetapkan nilainya ke `COMPLIANCE`. Header ini hanya berlaku untuk bucket yang telah mengaktifkan kebijakan retensi tingkat objek (ObjectWorm). Jika Anda menentukan header ini, Anda juga harus menentukan `x-oss-object-worm-retain-until-date`.
x-oss-object-worm-retain-until-date	String	Tanggal kedaluwarsa retensi objek. Nilainya harus dalam format `ISO 8601`. Header ini hanya berlaku untuk bucket yang telah mengaktifkan kebijakan retensi tingkat objek (ObjectWorm). Sebelum tanggal kedaluwarsa yang ditentukan, objek tidak dapat dihapus atau ditimpa. Jika header ini tidak ditentukan, aturan retensi default bucket akan diterapkan pada objek yang diunggah, jika dikonfigurasi.

Parameter permintaan

Gunakan parameter kueri encoding-type untuk meng-encode kunci objek dalam respons.

Parameter

Tipe

Deskripsi

encoding-type

String

Menentukan metode encoding untuk kunci objek dalam respons. Hanya encoding URL yang didukung. Kunci objek dalam UTF-8. Namun, standar XML 1.0 tidak mendukung karakter kontrol tertentu, seperti karakter dengan nilai ASCII dari 0 hingga 10. Jika kunci objek mengandung karakter tersebut, tentukan encoding-type untuk meng-encode kunci objek dalam respons.

Nilai default: Tidak ada

Nilai yang valid: url

Elemen respons

Setelah OSS menerima permintaan InitiateMultipartUpload, OSS mengembalikan badan respons dalam format XML yang berisi elemen Bucket, Key, dan UploadId.

Elemen	Tipe	Deskripsi
InitiateMultipartUploadResult	Kontainer	Kontainer untuk hasil permintaan `InitiateMultipartUpload`. Elemen anak: Bucket, Key, UploadId, dan EncodingType Elemen induk: Tidak ada
Bucket	String	Nama bucket tempat tugas unggah multi-bagian dimulai. Elemen induk: InitiateMultipartUploadResult
Key	String	Nama objek untuk tugas unggah multi-bagian. Elemen induk: InitiateMultipartUploadResult
UploadId	String	ID unik yang mengidentifikasi tugas unggah multi-bagian. ID ini diperlukan untuk pemanggilan berikutnya ke operasi UploadPart dan CompleteMultipartUpload. Elemen induk: InitiateMultipartUploadResult
EncodingType	String	Tipe encoding yang digunakan dalam respons. Jika Anda menentukan `encoding-type` dalam permintaan, elemen `Key` dalam respons akan di-encode. Elemen induk: InitiateMultipartUploadResult

Operasi ini menggunakan header respons umum. Untuk informasi selengkapnya, lihat Header respons umum.

Contoh

Contoh permintaan

POST /multipart.data?uploads HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Date: Wed, 22 Feb 2012 08:32:21 GMT 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Contoh respons

HTTP/1.1 200 OK
Content-Length: 230
Server: AliyunOSS
Connection: keep-alive
x-oss-request-id: 42c25703-7503-fbd8-670a-bda01eae****
Date: Wed, 22 Feb 2012 08:32:21 GMT
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Bucket>oss-example</Bucket>
    <Key>multipart.data</Key>
    <UploadId>0004B9894A22E5B1888A1E29F823****</UploadId>
</InitiateMultipartUploadResult>

SDK

Anda dapat memanggil operasi ini menggunakan SDK untuk bahasa pemrograman berikut:

CLI ossutil

Untuk perintah ossutil yang sesuai dengan operasi InitiateMultipartUpload, lihat initiate-multipart-upload.

Kode error

Kode error	Kode status HTTP	Deskripsi
InvalidEncryptionAlgorithmError	400	Algoritma Enkripsi sisi server selain `AES256`, `KMS` ditentukan.
InvalidArgument	400	Header permintaan `x-oss-server-side-encryption` ditentukan dalam permintaan untuk mengunggah bagian.
InvalidArgument	400	Kelas penyimpanan yang ditentukan tidak valid.
KmsServiceNotEnabled	403	`KMS` ditentukan sebagai algoritma enkripsi, tetapi Key Management Service (KMS) belum diaktifkan.
FileAlreadyExists	409	Error ini dikembalikan karena salah satu alasan berikut: Permintaan berisi header `x-oss-forbid-overwrite: true`, tetapi objek dengan nama yang sama sudah ada di bucket. Fitur namespace hirarkis diaktifkan untuk bucket, dan nama objek yang ditentukan bertentangan dengan direktori yang sudah ada.