All Products
Search

This Product

    Object Storage Service:PostObject

    Document Center

    Object Storage Service:PostObject

    Last Updated:Apr 01, 2026

    Gunakan operasi PostObject untuk mengunggah objek ke bucket tertentu melalui formulir HTML.

    Catatan penggunaan

    • Untuk mengunggah objek menggunakan formulir HTML, Anda harus memiliki izin oss:PutObject. Untuk informasi selengkapnya, lihat Attach a custom policy to a RAM user.

    • Ukuran maksimum objek yang diunggah dengan operasi PostObject adalah 5 GB.

    • Permintaan POST memerlukan izin menulis pada bucket. Jika bucket bersifat public-read-write, tanda tangan (signature) tidak diperlukan. Jika tidak, Object Storage Service (OSS) akan memverifikasi signature untuk operasi tersebut.

    • Berbeda dengan operasi PutObject, operasi PostObject menggunakan AccessKey secret untuk menandatangani policy. Signature ini menjadi nilai field formulir Signature.

    • URL untuk pengiriman formulir adalah endpoint bucket. Anda tidak perlu menentukan objek dalam URL. Baris permintaan harus berupa POST / HTTP/1.1, bukan POST /ObjectName HTTP/1.1.

    • Jika permintaan POST menyertakan signature dalam header atau URL, OSS tidak memvalidasi informasi tersebut.

    Pengendalian versi

    Saat Anda mengirim permintaan PostObject ke bucket yang telah diaktifkan fitur versioning, OSS secara otomatis menghasilkan ID versi unik untuk objek yang diunggah dan mengembalikan ID versi tersebut dalam header respons x-oss-version-id.

    Saat Anda mengirim permintaan PostObject ke bucket dengan versioning yang ditangguhkan, OSS memberikan ID versi null untuk objek yang diunggah dan mengembalikan ID versi tersebut dalam header respons x-oss-version-id. Sebuah objek hanya dapat memiliki satu ID versi null.

    Sintaksis permintaan

    POST / HTTP/1.1 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length：ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
key
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"
signature
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    Header permintaan

    Penting

    • Badan pesan untuk PostObject dikodekan dalam format multipart/form-data. Dalam operasi PutObject, parameter dilewatkan melalui header permintaan HTTP, sedangkan dalam operasi PostObject, parameter dilewatkan sebagai field formulir dalam badan pesan.

    • Dalam operasi PostObject, Anda tidak dapat menambahkan tag ke objek dengan menyertakan header permintaan x-oss-tagging. Setelah operasi PostObject selesai, Anda dapat memanggil API PutObjectTagging untuk menambahkan tag ke objek tersebut.

    Parameter

    Tipe

    Wajib

    Deskripsi

    Content-Type

    String

    Tidak

    Menentukan tipe objek dan format encoding halaman web. Informasi ini menentukan cara browser membaca objek tersebut.

    Formulir POST harus dikodekan sebagai multipart/form-data. Header Content-Type harus dalam format multipart/form-data;boundary=xxxxxx.

    Boundary adalah string pembatas yang dihasilkan secara acak oleh formulir. Anda tidak perlu menentukan string ini. Jika Anda menggunakan SDK untuk membuat formulir, SDK juga akan menghasilkan nilai acak untuk boundary.

    Operasi ini juga menggunakan header permintaan umum seperti Host dan Date. Untuk informasi selengkapnya, lihat Common request headers.

    Field formulir

    Tabel berikut mencantumkan field formulir yang umum digunakan dalam permintaan POST dengan signature V1 dan V4. Untuk informasi lebih lanjut tentang field formulir khusus signature V4, lihat V4 signature forms. Untuk informasi lebih lanjut tentang field formulir khusus signature V1, lihat V1 signature forms.

    Penting

    • Field file harus ditempatkan paling akhir. Field formulir lainnya dapat disusun dalam urutan apa pun.

    • Panjang kunci field formulir tidak boleh melebihi 8 KB, dan nilainya tidak boleh melebihi 2 MB.

    Parameter

    Tipe

    Wajib

    Deskripsi

    Cache-Control

    String

    Tidak

    Menentukan perilaku caching objek saat diunduh. Untuk informasi selengkapnya, lihat RFC 2616.

    Nilai default: none

    Content-Disposition

    String

    Tidak

    Menentukan nama objek saat diunduh. Untuk informasi selengkapnya, lihat RFC 2616.

    Nilai default: none

    Content-Encoding

    String

    Tidak

    Menentukan format encoding konten objek saat diunduh. Untuk informasi selengkapnya, lihat RFC 2616.

    Nilai default: none

    Expires

    String

    Tidak

    Waktu kedaluwarsa. Untuk informasi selengkapnya, lihat RFC 2616.

    Nilai default: none

    policy

    String

    Bersyarat

    Policy menentukan kondisi yang harus dipenuhi oleh formulir permintaan. Permintaan yang tidak menyertakan field formulir policy dianggap sebagai permintaan anonim dan hanya dapat mengakses bucket public-read-write.

    Nilai default: none

    Batasan: Field formulir policy wajib disertakan jika bucket tidak bersifat public-read-write atau jika permintaan menyertakan field formulir OSSAccessKeyId atau Signature.

    Penting

    Formulir dan policy harus dikodekan dalam UTF-8. Field formulir policy juga harus dikodekan dalam Base64.

    x-oss-server-side-encryption-key-id

    String

    Tidak

    Menunjukkan customer master key yang dikelola oleh KMS. Opsi ini hanya berlaku ketika x-oss-server-side-encryption diatur ke KMS.

    x-oss-content-type

    String

    Tidak

    Menentukan Content-Type objek. Browser secara otomatis menambahkan Content-Type ke field formulir file. Untuk mengatasi hal ini, OSS memungkinkan Anda menambahkan field formulir x-oss-content-type ke badan permintaan POST untuk menentukan Content-Type. Field ini memiliki prioritas tertinggi.

    Urutan prioritas: x-oss-content-type > Content-Type dari field formulir file

    Nilai default: none

    x-oss-forbid-overwrite

    String

    Tidak

    Menentukan apakah objek yang sudah ada dengan nama yang sama akan ditimpa selama operasi PostObject.

    Jika versioning diaktifkan atau ditangguhkan untuk bucket tujuan, pengaturan x-oss-forbid-overwrite tidak berlaku, artinya objek yang sudah ada dengan nama yang sama 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.

    • Jika Anda mengatur x-oss-forbid-overwrite ke true, objek yang sudah ada tidak akan ditimpa.

    Mengatur header permintaan x-oss-forbid-overwrite akan menurunkan performa pemrosesan QPS. Jika Anda perlu menggunakan header permintaan x-oss-forbid-overwrite untuk banyak operasi (QPS > 1000), hubungi dukungan teknis untuk menghindari dampak terhadap bisnis Anda.

    x-oss-object-acl

    String

    Tidak

    Menentukan daftar kontrol akses (ACL) objek.

    Nilai valid:

    • default (default): ACL objek sama dengan ACL bucket.

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

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

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

    Untuk informasi selengkapnya tentang kontrol akses, lihat Object ACL.

    x-oss-storage-class

    String

    Tidak

    Menentukan kelas penyimpanan objek.

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

    Nilai valid:

    • Standard

    • IA

    • Archive

    • ColdArchive

    • DeepColdArchive

      Penting

      Mengatur kelas penyimpanan ke Deep Cold Archive saat pengunggahan akan mengakibatkan biaya permintaan PUT yang lebih tinggi PUT request fees. Kami menyarankan agar Anda mengatur 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 Storage classes.

    key

    String

    Ya

    Nama objek yang akan diunggah. Anda tidak perlu mengencode nama objek tersebut. Jika nama tersebut berisi path, seperti destfolder/example.jpg, OSS secara otomatis membuat folder yang sesuai.

    Nilai default: none

    success_action_redirect

    String

    Tidak

    URL tempat klien dialihkan setelah pengunggahan berhasil. Jika field formulir ini tidak ditentukan, field formulir success_action_status yang menentukan hasilnya. Jika pengunggahan gagal, OSS mengembalikan kode kesalahan dan tidak melakukan pengalihan.

    Nilai default: none

    success_action_status

    String

    Tidak

    Menentukan kode status yang dikembalikan ke klien setelah pengunggahan berhasil jika success_action_redirect tidak ditentukan.

    Nilai valid: 200, 201, dan 204 (default).

    • Jika field ini diatur ke 200 atau 204, OSS mengembalikan dokumen kosong dan kode status yang sesuai.

    • Jika field ini diatur ke 201, OSS mengembalikan dokumen XML dan kode status 201.

    • Jika field ini tidak diatur atau diatur ke nilai yang tidak valid, OSS mengembalikan dokumen kosong dan kode status 204.

    x-oss-meta-*

    String

    Tidak

    Metadata yang ditentukan pengguna.

    Nilai default: none

    Jika permintaan menyertakan field formulir dengan awalan x-oss-meta-, field formulir tersebut dianggap sebagai metadata yang ditentukan pengguna. Contoh: x-oss-meta-location.

    Catatan

    Sebuah objek dapat memiliki beberapa field metadata yang ditentukan pengguna, tetapi ukuran total semua metadata yang ditentukan pengguna tidak boleh melebihi 8 KB.

    x-oss-security-token

    String

    Tidak

    Token keamanan, yang hanya diperlukan saat Anda menggunakan Security Token Service (STS) untuk menghasilkan URL yang ditandatangani. Anda dapat memperoleh token keamanan dengan memanggil operasi STS AssumeRole.

    Nilai default: none

    x-oss-object-worm-mode

    String

    Tidak

    Menentukan mode kebijakan retensi objek. Atur nilainya ke COMPLIANCE. Field ini hanya berlaku jika kebijakan retensi tingkat objek (ObjectWorm) diaktifkan untuk bucket tersebut. Jika Anda mengatur field ini, Anda juga harus mengatur x-oss-object-worm-retain-until-date.

    x-oss-object-worm-retain-until-date

    String

    Tidak

    Menentukan tanggal kedaluwarsa retensi untuk objek dalam format ISO 8601. Field ini hanya berlaku jika kebijakan retensi tingkat objek (ObjectWorm) diaktifkan untuk bucket tersebut. Sebelum tanggal kedaluwarsa retensi, objek tidak dapat dihapus atau ditimpa. Jika Anda tidak menentukan field ini, aturan retensi default bucket akan diterapkan pada objek yang diunggah, jika dikonfigurasi.

    file

    String

    Ya

    Konten objek. Anda tidak perlu mengencode konten tersebut. Browser secara otomatis mengatur Content-Type berdasarkan tipe file, yang akan menggantikan pengaturan pengguna. Anda hanya dapat mengunggah satu objek dalam satu waktu.

    Nilai default: none

    Penting

    Field formulir file harus menjadi field terakhir dalam formulir.

    Header respons

    Parameter

    Tipe

    Contoh

    Deskripsi

    x-oss-server-side-encryption

    String

    KMS

    Jika header x-oss-server-side-encryption ditentukan dalam permintaan, respons akan menyertakan header ini untuk menunjukkan algoritma enkripsi sisi server yang digunakan.

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    Hash MD5 objek.

    Penting

    Ini adalah hash MD5 objek setelah klien menyelesaikan pengunggahan, bukan hash MD5 dari badan respons.

    x-oss-hash-crc64ecma

    String

    316181249502703****

    Hash CRC-64 objek.

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

    ID versi objek. Header ini hanya dikembalikan saat Anda mengunggah objek ke bucket yang telah diaktifkan fitur versioning.

    Operasi ini juga menyertakan header respons umum lainnya, seperti Date dan x-oss-request-id. Untuk informasi selengkapnya, lihat Common response headers.

    Elemen respons

    Parameter

    Tipe

    Deskripsi

    PostResponse

    Kontainer

    Kontainer untuk hasil permintaan POST.

    Node anak: Bucket, ETag, Key, dan Location

    Bucket

    String

    Nama bucket.

    Node induk: PostResponse

    ETag

    String

    OSS membuat ETag (Entity Tag) saat objek dibuat. Untuk objek yang dibuat melalui permintaan POST, ETag adalah nilai unik yang dihasilkan berdasarkan aturan perhitungan tertentu, tetapi bukan hash MD5 dari konten objek tersebut. ETag dapat digunakan untuk memeriksa apakah konten objek telah berubah.

    Node induk: PostResponse

    Location

    String

    URL objek yang baru dibuat.

    Node induk: PostResponse

    Contoh

    • Contoh permintaan: 

      POST / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 344606
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
/user/a/objectName.txt
--9431149156168
Content-Disposition: form-data; name="success_action_status"
200
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
content_disposition
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
44CF9590006BF252****
--9431149156168
Content-Disposition: form-data; name="policy"
eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
--9431149156168
Content-Disposition: form-data; name="Signature"
kZoYNv66bsmc10+dcGKw5x2P****
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.txt"
Content-Type: text/plain
abcdefg
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    • Contoh respons: 

      HTTP/1.1 200 OK
x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e 
Date: Fri, 24 Feb 2014 06:03:28 GMT
ETag: "5B3C1A2E053D763E1B002CC607C5****"
Connection: keep-alive
Content-Length: 0
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
Server: AliyunOSS

    SDK

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

    Kode kesalahan

    Kode kesalahan

    Kode status HTTP

    Deskripsi

    FieldItemTooLong

    400

    Panjang kunci field formulir melebihi 8 KB, atau panjang nilai field formulir melebihi 2 MB.

    InvalidArgument

    400

    Terlepas dari apakah bucket bersifat public-read-write atau tidak, jika Anda menentukan salah satu dari field formulir OSSAccessKeyId, policy, atau Signature, dua field lainnya menjadi wajib. Kesalahan ini dikembalikan jika field yang wajib tidak disertakan.

    InvalidDigest

    400

    Permintaan menyertakan header permintaan Content-MD5. OSS menghitung hash Content-MD5 dari badan permintaan dan memeriksa konsistensinya. Kesalahan ini dikembalikan jika hash yang dihitung tidak cocok dengan yang ada di header.

    EntityTooLarge

    400

    Panjang total badan permintaan tidak boleh melebihi 5 GB. Kesalahan ini dikembalikan jika objek terlalu besar.

    InvalidEncryptionAlgorithmError

    400

    Jika field permintaan x-oss-server-side-encryption ditentukan, nilainya harus AES256 atau KMS. Kesalahan ini dikembalikan jika nilai lain digunakan.

    IncorrectNumberOfFilesInPOSTRequest

    400

    Jumlah file dalam permintaan POST tidak valid. Permintaan POST hanya boleh berisi satu field formulir file.

    FileAlreadyExists

    409

    Permintaan menyertakan x-oss-forbid-overwrite=true, yang melarang penimpaan objek dengan nama yang sama. Kesalahan ini dikembalikan jika objek tersebut sudah ada.

    KmsServiceNotEnabled

    403

    x-oss-server-side-encryption diatur ke KMS, tetapi layanan KMS belum diaktifkan.

    FileImmutable

    409

    Kode kesalahan ini dikembalikan jika Anda mencoba menghapus atau mengubah data yang dilindungi oleh kebijakan retensi.

    MethodNotAllowed

    405

    Metode permintaan HTTP tidak didukung atau tidak diizinkan oleh server. Periksa metode permintaan dan header untuk memastikan bahwa metode tersebut benar dan didukung oleh server. Verifikasi URL, termasuk protokol, domain, dan path.

    POST policy

    Field formulir policy adalah kebijakan keamanan yang mendefinisikan izin dan batasan untuk mengunggah objek ke OSS menggunakan formulir HTML. Field formulir policy didefinisikan dalam format JSON dan membatasi operasi pengunggahan berdasarkan berbagai parameter, seperti nama bucket, awalan objek, waktu kedaluwarsa, metode HTTP yang diizinkan, serta batasan ukuran dan tipe konten.

    POST signature

    POST signature adalah tanda tangan yang harus disertakan dalam setiap permintaan pengunggahan saat Anda menggunakan metode PostObject. Tanda tangan ini menjamin legalitas dan keamanan permintaan pengunggahan.

    • Untuk informasi selengkapnya tentang signature V4 untuk permintaan POST, lihat POST V4 signature.

    • Untuk informasi selengkapnya tentang signature V1 untuk permintaan POST, lihat POST V1 signature.

    FAQ

    Kesalahan ukuran maksimum yang diizinkan

    • Penyebab: Ukuran objek yang diunggah berada di luar rentang yang ditentukan oleh content-length-range.

    • Solusi: Gunakan content-length-range untuk menentukan ukuran minimum dan maksimum yang diizinkan untuk pengunggahan, dalam byte. Misalnya, untuk mengunggah objek 1 GB, Anda dapat mengatur content-length-range ke ["content-length-range", 1, 1073741824].

    Referensi