全部产品
Search

搜索本产品

    Object Storage Service：PostObject

    文档中心

    Object Storage Service：PostObject

    更新时间：Dec 06, 2025

    Anda dapat memanggil operasi PostObject untuk mengunggah objek ke bucket tertentu menggunakan formulir HTML.

    Catatan penggunaan

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

    • Ukuran objek yang diunggah menggunakan operasi PostObject tidak boleh melebihi 5 GB.

    • Permintaan PostObject memerlukan izin tulis pada bucket. Jika daftar kontrol akses (ACL) bucket tersebut adalah public-read-write, Anda tidak perlu menyertakan informasi signature. Jika tidak, Object Storage Service (OSS) akan mengautentikasi signature dalam permintaan tersebut.

    • Berbeda dengan operasi PutObject, operasi PostObject menggunakan Rahasia AccessKey untuk menandatangani kebijakan. String signature yang dihitung digunakan sebagai nilai field formulir Signature. OSS mengautentikasi nilai ini untuk menentukan validitas signature tersebut.

    • URL untuk formulir yang dikirimkan adalah nama domain bucket. Anda tidak perlu menentukan objek dalam URL. Baris permintaan adalah POST / HTTP/1.1 dan bukan POST /ObjectName HTTP/1.1.

    • Jika permintaan POST berisi informasi signature di header atau URL, OSS tidak akan memeriksa informasi tersebut.

    Pengendalian versi

    Jika Anda mengirim permintaan PostObject ke bucket yang telah diaktifkan fitur Pengendalian versi, OSS secara otomatis menghasilkan ID versi unik untuk objek baru tersebut. ID ini dikembalikan dalam header respons x-oss-version-id.

    Jika Anda mengirim permintaan PostObject ke bucket yang Pengendalian versinya ditangguhkan, OSS secara otomatis menghasilkan ID versi null untuk objek baru tersebut. ID ini dikembalikan dalam header respons x-oss-version-id. Hanya satu ID versi null yang diizinkan untuk objek yang sama.

    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 permintaan PostObject diencode dalam format multipart/form-data. Berbeda dengan operasi PutObject yang meneruskan parameter melalui header permintaan HTTP, operasi PostObject meneruskan parameter sebagai field formulir dalam badan pesan.

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

    Name

    Type

    Required

    Description

    Content-Type

    String

    No

    Tipe file dan encoding halaman web. Hal ini menentukan cara browser membaca dan mengencode file tersebut.

    Formulir yang dikirimkan dalam operasi Post harus diencode dalam format multipart/form-data. Artinya, header Content-Type berada dalam format multipart/form-data;boundary=xxxxxx.

    Boundary adalah string acak yang dihasilkan oleh formulir. Anda tidak perlu menentukannya secara manual. Jika Anda menggunakan SDK untuk membuat formulir, SDK tersebut juga akan menghasilkan nilai acak.

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

    Elemen formulir

    Tabel berikut menjelaskan elemen formulir yang umum digunakan baik untuk signature V1 maupun V4. Untuk informasi tentang elemen formulir yang khusus untuk signature V4, lihat V4 signature form. Untuk informasi tentang elemen formulir yang khusus untuk signature V1, lihat V1 signature form.

    Penting

    • Field file harus menjadi field formulir terakhir. Field formulir lainnya dapat disusun dalam urutan apa pun.

    • Kunci field formulir tidak boleh melebihi ukuran 8 KB, dan nilainya tidak boleh melebihi 2 MB.

    Name

    Type

    Required

    Description

    Cache-Control

    String

    No

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

    Nilai default: none.

    Content-Disposition

    String

    No

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

    Nilai default: none.

    Content-Encoding

    String

    No

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

    Nilai default: none.

    Expires

    String

    No

    Waktu kedaluwarsa. Untuk informasi selengkapnya, lihat RFC 2616.

    Nilai default: none.

    policy

    String

    Yes, conditional

    Kebijakan ini menentukan validitas field formulir permintaan. Permintaan yang tidak berisi field formulir policy dianggap sebagai permintaan anonim dan hanya dapat digunakan untuk mengakses bucket public-read-write.

    Nilai default: none.

    Batasan: Field formulir policy wajib disertakan jika bucket bukan public-read-write atau jika field formulir OSSAccessKeyId atau Signature disediakan.

    Penting

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

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

    String

    No

    Kunci master pelanggan (CMK) yang dikelola oleh KMS. Elemen ini hanya berlaku ketika x-oss-server-side-encryption diatur ke KMS.

    x-oss-content-type

    String

    No

    Browser secara otomatis menambahkan Content-Type ke field formulir file. Untuk mengatasi hal ini, OSS mendukung penambahan x-oss-content-type ke badan permintaan Post. Elemen ini memungkinkan Anda menentukan Content-Type dan memiliki prioritas tertinggi.

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

    Nilai default: none.

    x-oss-forbid-overwrite

    String

    No

    Menentukan apakah objek yang memiliki nama yang sama akan ditimpa selama operasi PostObject.

    Ketika bucket tujuan berada dalam status pengendalian versi aktif atau ditangguhkan, header permintaan x-oss-forbid-overwrite tidak berlaku. Artinya, objek yang memiliki nama yang sama dapat ditimpa.

    • Jika x-oss-forbid-overwrite tidak ditentukan atau x-oss-forbid-overwrite disetel ke false, objek dengan nama yang sama dapat ditimpa.

    • Jika Anda mengatur x-oss-forbid-overwrite ke true, objek yang memiliki nama yang sama tidak dapat ditimpa.

    Mengatur header permintaan x-oss-forbid-overwrite mengurangi performa QPS. Jika Anda memiliki banyak operasi yang memerlukan header permintaan x-oss-forbid-overwrite (QPS > 1.000), hubungi dukungan teknis untuk menghindari dampak terhadap bisnis Anda.

    x-oss-object-acl

    String

    No

    Menentukan izin akses objek dalam field formulir file. Elemen ini dapat ditentukan dalam field formulir file.

    Nilai yang valid:

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

    • private: Objek merupakan resource pribadi. Hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca dan tulis pada objek tersebut. Pengguna lain tidak dapat 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 memiliki izin baca pada 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 izin akses, lihat Object ACL.

    x-oss-storage-class

    String

    No

    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 menentukan x-oss-storage-class sebagai Standard saat mengunggah objek ke bucket IA, objek tersebut akan disimpan sebagai objek Standard.

    Nilai yang valid:

    • Standard: Standard

    • IA: Infrequent Access

    • Archive: Archive Storage

    • ColdArchive: Cold Archive

    • DeepColdArchive: Deep Cold Archive

      Penting

      Menyetel kelas penyimpanan ke Deep Cold Archive saat pengunggahan mengakibatkan biaya PUT request fees yang lebih tinggi. Kami menyarankan agar Anda menyetel kelas penyimpanan objek ke Standard saat mengunggah objek, lalu mengonfigurasi lifecycle rules untuk mengonversi kelas penyimpanan objek Standard menjadi Deep Cold Archive. Hal ini mengurangi biaya permintaan PUT.

    Untuk informasi selengkapnya, lihat Storage classes.

    key

    String

    Yes

    Nama objek yang akan diunggah. Jangan mengencode nama tersebut. Jika nama tersebut mencakup path, seperti destfolder/example.jpg, OSS secara otomatis membuat folder yang sesuai.

    Nilai default: none.

    success_action_redirect

    String

    No

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

    Nilai default: none.

    success_action_status

    String

    No

    Ketika field formulir success_action_redirect tidak ditentukan, field formulir ini menentukan kode status yang dikembalikan ke klien setelah pengunggahan berhasil.

    Nilai yang 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 file 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

    No

    Metadata pengguna yang ditentukan sendiri oleh pengguna.

    Nilai default: none.

    Jika permintaan mencakup field formulir yang diawali dengan x-oss-meta-, field tersebut dianggap sebagai metadata pengguna. Misalnya, x-oss-meta-location.

    Catatan

    Sebuah objek dapat memiliki beberapa parameter semacam ini, tetapi ukuran total semua metadata pengguna tidak boleh melebihi 8 KB.

    x-oss-security-token

    String

    No

    Token keamanan. Parameter ini hanya diperlukan ketika Anda menggunakan Security Token Service (STS) untuk membuat URL yang ditandatangani. Anda dapat memperoleh token keamanan dengan memanggil operasi AssumeRole dari STS.

    Nilai default: none.

    file

    String

    Yes

    File atau konten teks. Jangan mengencode konten tersebut. Browser secara otomatis menyetel Content-Type berdasarkan tipe file dan menimpa pengaturan Anda. OSS hanya dapat mengunggah satu file dalam satu waktu.

    Nilai default: none.

    Penting

    Field file harus menjadi field formulir terakhir.

    Header respons

    Name

    Type

    Example

    Description

    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 dari file tersebut.

    Penting

    Hash MD5 file tersebut adalah hash MD5 yang diperoleh setelah klien menyelesaikan pengunggahan, bukan hash MD5 dari badan respons.

    x-oss-hash-crc64ecma

    String

    316181249502703****

    Nilai CRC-64 dari file tersebut.

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

    ID versi file tersebut. Header respons ini hanya dikembalikan ketika Anda mengunggah file ke bucket yang telah diaktifkan fitur pengendalian versi.

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

    Elemen respons

    Name

    Type

    Description

    PostResponse

    Container

    Kontainer yang menyimpan hasil permintaan Post.

    Node anak: Bucket, ETag, Key, dan Location

    Bucket

    String

    Nama bucket.

    Node induk: PostResponse

    ETag

    String

    ETag (Entity Tag) dibuat saat setiap objek dihasilkan. 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 memanggil operasi ini menggunakan kit pengembangan perangkat lunak (SDK) berikut:

    Kode kesalahan

    Error code

    HTTP status code

    Description

    FieldItemTooLong

    400

    Ukuran kunci field formulir tidak boleh melebihi 8 KB, dan ukuran nilai field formulir tidak boleh melebihi 2 MB.

    InvalidArgument

    400

    Terlepas dari apakah bucket bersifat public-read-write atau tidak, jika salah satu dari field formulir OSSAccessKeyId, policy, atau Signature diunggah, dua field formulir lainnya wajib disertakan. Jika tidak disertakan, kesalahan ini akan dikembalikan.

    InvalidDigest

    400

    Jika Anda mengunggah permintaan dengan header Content-MD5, OSS menghitung Content-MD5 dari badan dan memeriksa konsistensinya. Jika tidak konsisten, kesalahan ini akan dikembalikan.

    EntityTooLarge

    400

    Panjang total badan permintaan tidak boleh melebihi 5 GB. Jika file terlalu besar, kesalahan ini akan dikembalikan.

    InvalidEncryptionAlgorithmError

    400

    Jika Anda menentukan header permintaan x-oss-server-side-encryption selama pengunggahan, Anda harus mengatur nilainya ke AES256 atau KMS. Jika Anda mengatur ke nilai lain, kesalahan ini akan dikembalikan.

    IncorrectNumberOfFilesInPOSTRequest

    400

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

    FileAlreadyExists

    409

    Jika header permintaan berisi x-oss-forbid-overwrite=true, objek yang memiliki nama yang sama tidak dapat ditimpa. Jika file tersebut sudah ada, kesalahan ini akan dikembalikan.

    KmsServiceNotEnabled

    403

    x-oss-server-side-encryption ditentukan sebagai KMS, tetapi Anda belum membeli paket KMS sebelumnya.

    FileImmutable

    409

    Jika Anda mencoba menghapus atau memodifikasi data dalam bucket yang dilindungi, kode kesalahan ini akan dikembalikan.

    MethodNotAllowed

    405

    Metode permintaan HTTP tidak didukung atau tidak diizinkan oleh server. Periksa metode permintaan dan header untuk memastikan informasi header benar dan layanan mendukung metode permintaan tersebut. Periksa URL untuk memastikan protokol, nama domain, dan path-nya benar.

    POST policy

    Field formulir policy adalah kebijakan keamanan yang didefinisikan dalam format JSON. Field ini menentukan batasan dan kendala izin untuk mengunggah file ke OSS menggunakan formulir HTML. Kebijakan ini menggunakan beberapa parameter untuk membatasi operasi pengunggahan, seperti nama bucket, awalan objek, periode validitas, metode HTTP yang diizinkan, serta batasan ukuran dan tipe konten pengunggahan.

    POST signature

    Signature POST menjamin keamanan permintaan pengunggahan. Saat Anda menggunakan operasi PostObject, OSS mengharuskan setiap permintaan pengunggahan menyertakan signature untuk memverifikasi legalitas dan keamanan permintaan tersebut.

    FAQ

    Apa yang harus saya lakukan jika muncul kesalahan "Your proposed upload exceeds the maximum allowed size"?

    • Penyebab: Ukuran file 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 file yang diunggah dalam byte. Misalnya, untuk mengunggah file sebesar 1 GB, Anda dapat mengatur content-length-range ke ["content-length-range", 1, 1073741824].

    Referensi