API PutObject Object Storage Service - Object Storage Service

Operasi PutObject mengunggah objek ke bucket di Object Storage Service (OSS). Ukuran objek dalam satu kali unggah tidak boleh melebihi 5 GB.

Sintaksis permintaan

PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Catatan penggunaan

Ukuran maksimum objek yang dapat diunggah dalam satu operasi adalah 5 GB. Untuk mengunggah objek yang lebih besar dari 5 GB, gunakan multipart upload.
Secara default, jika Anda mengunggah objek dengan nama yang sama seperti objek yang sudah ada, OSS akan menimpa objek tersebut dan mengembalikan kode status 200 OK. Anda dapat mengatur parameter untuk mencegah penimpaan dan menghindari penimpaan tidak sengaja terhadap objek penting.
OSS menggunakan struktur penyimpanan datar dan tidak memiliki konsep direktori seperti pada sistem file tradisional. Anda dapat mensimulasikan struktur folder dengan membuat objek kosong yang namanya diakhiri dengan garis miring (/).

Izin

Secara default, akun Alibaba Cloud memiliki izin penuh. Secara default, RAM user atau RAM role tidak memiliki izin apa pun. Akun Alibaba Cloud atau administrator akun harus memberikan izin melalui RAM Policy atau Bucket Policy.

API	Action	Deskripsi
PutObject	`oss:PutObject`	Mengunggah objek.
	`oss:PutObjectTagging`	Diperlukan jika Anda menentukan tag objek menggunakan header `x-oss-tagging` saat mengunggah objek.
	`kms:GenerateDataKey`	Diperlukan jika header `X-Oss-Server-Side-Encryption: KMS` diatur ke `KMS` saat Anda mengunggah objek.
	`kms:Decrypt`

Pengendalian versi

Jika Pengendalian versi diaktifkan untuk bucket, OSS secara otomatis menghasilkan ID versi unik untuk setiap objek baru. ID versi ini dikembalikan dalam header respons x-oss-version-id.

Jika Pengendalian versi ditangguhkan untuk bucket, ID versi objek baru bernilai null. OSS memastikan hanya satu versi null dari suatu objek yang dapat ada di bucket tersebut.

Parameter permintaan

OSS mendukung header permintaan HTTP standar seperti Cache-Control, Expires, Content-Encoding, Content-Disposition, dan Content-Type. Saat Anda mengatur header ini dalam permintaan unggah, nilainya akan diterapkan secara otomatis saat objek diunduh.

Header Respons Umum.

Parameter	Tipe	Wajib	Contoh	Deskripsi
Authorization	String	Tidak	OSS qn6q************:77Dv**************	Mengotentikasi dan mengotorisasi permintaan. Untuk informasi selengkapnya tentang cara menghitung signature, lihat Sertakan signature dalam header. Header Authorization biasanya wajib. Namun, Anda tidak perlu menyertakan header ini jika signature disertakan dalam URL. Untuk informasi selengkapnya, lihat Sertakan signature dalam URL. Nilai default: tidak ada
Cache-Control	String	Tidak	no-cache	Menentukan perilaku caching saat objek diunduh. Nilai yang valid: no-cache: Cache harus melakukan re-validasi konten dengan server origin sebelum menyajikannya. Jika konten berubah, server mengembalikan objek baru. Jika tidak, cache dikonfirmasi masih valid. no-store: Seluruh konten objek tidak di-cache. public: Seluruh konten objek di-cache. private: Seluruh konten objek hanya di-cache di sisi klien. max-age=<seconds>: Periode validitas konten yang di-cache. Satuan: detik. Opsi ini hanya tersedia di HTTP 1.1. Nilai default: tidak ada
Content-Disposition	String	Tidak	attachment	Menentukan cara objek ditampilkan. Nilai yang valid: Content-Disposition:inline: Objek ditampilkan langsung di browser. Content-Disposition:attachment: Objek diunduh ke path unduhan yang ditentukan oleh browser dengan nama objek asli. Content-Disposition:attachment; filename="yourFileName": Objek diunduh ke path unduhan yang ditentukan oleh browser dengan nama objek kustom. yourFileName menentukan nama kustom objek yang diunduh, misalnya example.jpg. Jika Anda ingin mengunduh objek ke path unduhan yang ditentukan oleh browser, perhatikan hal-hal berikut: Catatan Jika nama objek mengandung karakter khusus seperti tanda bintang () atau garis miring (/), nama objek yang diunduh mungkin di-escape. Misalnya, jika Anda mengunduh `example.jpg` ke komputer lokal, `example.jpg` mungkin di-escape menjadi `example_.jpg`. Untuk memastikan bahwa nama objek yang mengandung karakter non-ASCII (seperti bahasa Tionghoa) ditangani dengan benar saat diunduh dan tidak menghasilkan nama file yang rusak, Anda harus melakukan URL-encode karakter Tionghoa dalam nama objek. Misalnya, agar objek `Test.txt` di OSS diunduh sebagai file lokal dengan nama objek asli `Test.txt`, Anda harus mengatur header Content-Disposition menjadi `attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename=UTF-8''%E6%B5%8B%E8%AF%95.txt`, yang berasal dari `"attachment;filename="+URLEncoder.encode("Test","UTF-8")+".txt;filename*=UTF-8''"+URLEncoder.encode("Test","UTF-8")+".txt"`. Apakah objek dipratinjau atau diunduh sebagai lampiran saat diakses melalui URL objek ditentukan oleh waktu pembuatan bucket tempat objek disimpan, waktu aktivasi OSS, dan jenis domain name. Untuk informasi selengkapnya, lihat Apa yang harus saya lakukan jika objek gambar diunduh sebagai lampiran tetapi tidak dapat dipratinjau saat saya mengakses objek gambar tersebut melalui URL-nya? Nilai default: tidak ada
Content-Encoding	String	Tidak	identity	Menentukan encoding objek. Anda harus mengatur header ini sesuai dengan tipe encoding aktual objek. Jika tidak, kesalahan parsing atau unduhan di sisi klien mungkin terjadi. Jika objek tidak di-encode, biarkan header ini kosong. Nilai yang valid: identity (default): OSS tidak mengompresi atau meng-encode objek. gzip: OSS menggunakan algoritma kompresi LZ77 yang dibuat oleh Lempel dan Ziv pada tahun 1977 dan Pemeriksaan redundansi siklik (CRC) 32-bit untuk meng-encode objek. compress: OSS menggunakan algoritma kompresi Lempel–Ziv–Welch (LZW) untuk meng-encode objek. deflate: OSS menggunakan library zlib dan algoritma deflate untuk meng-encode objek. br: OSS menggunakan algoritma Brotli untuk meng-encode objek. Nilai default: tidak ada
Content-MD5	String	Tidak	eB5eJF1ptWaXm4bijSPyxw==	Digunakan untuk memeriksa integritas konten pesan. Header Content-MD5 adalah nilai yang dihasilkan menggunakan algoritma MD5. Jika Anda mengatur header ini, OSS menghitung nilai Content-MD5 dari badan pesan dan memeriksa apakah nilainya sesuai dengan nilai yang Anda berikan. Untuk informasi selengkapnya, lihat Menghitung nilai Content-MD5. Untuk memastikan integritas data, OSS menyediakan beberapa metode untuk memverifikasi nilai hash MD5. Jika Anda ingin menggunakan Content-MD5 untuk verifikasi, sertakan header Content-MD5 dalam permintaan Anda. Nilai default: tidak ada
Content-Length	String	Tidak	344606	Ukuran badan pesan HTTP yang akan ditransfer, dalam byte. Jika nilai header Content-Length lebih kecil daripada ukuran data aktual dalam badan permintaan, OSS tetap membuat objek tersebut. Namun, ukuran objek sama dengan ukuran yang ditentukan dalam Content-Length, dan data berlebih akan dibuang.
Expires	String	Tidak	Wed, 08 Jul 2015 16:57:01 GMT	Menentukan waktu kedaluwarsa objek. Untuk informasi selengkapnya, lihat RFC2616. Nilai default: tidak ada
x-oss-forbid-overwrite	String	Tidak	false	Menentukan apakah objek dengan nama yang sama akan ditimpa selama operasi PutObject. Jika pengendalian versi diaktifkan atau ditangguhkan untuk bucket tujuan, header permintaan x-oss-forbid-overwrite diabaikan, dan objek yang sudah ada dapat ditimpa. Jika Anda tidak menentukan x-oss-forbid-overwrite, atau jika Anda 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 dengan nama yang sama tidak dapat ditimpa. Mengatur header permintaan x-oss-forbid-overwrite memengaruhi kinerja pemrosesan QPS. Jika Anda menggunakan header permintaan x-oss-forbid-overwrite untuk banyak operasi (QPS > 1000), hubungi dukungan teknis untuk menghindari dampak terhadap operasi bisnis Anda. Nilai default: false
x-oss-server-side-encryption	String	Tidak	AES256	Menentukan metode enkripsi sisi server yang digunakan saat Anda membuat objek. Nilai yang valid: AES256, KMS Jika Anda menentukan header ini, header tersebut dikembalikan dalam respons. OSS mengenkripsi objek yang diunggah. Saat Anda mengunduh objek tersebut, respons mencakup header x-oss-server-side-encryption, dan nilainya diatur ke algoritma enkripsi objek tersebut.
x-oss-server-side-encryption-key-id	String	Tidak	9468da86-3509-4f8d-a61e-6eab1eac****	ID kunci master pelanggan (CMK) yang dikelola oleh KMS. Header ini hanya berlaku ketika x-oss-server-side-encryption diatur ke KMS.
x-oss-object-acl	String	Tidak	default	Menentukan daftar kontrol akses (ACL) objek saat objek dibuat. Nilai yang valid: default (default): Objek mewarisi 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 dapat mengakses 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. Gunakan ACL ini dengan hati-hati. public-read-write: Objek merupakan resource publik baca/tulis. Semua pengguna memiliki izin baca dan tulis pada objek tersebut. Gunakan ACL ini dengan hati-hati. Untuk informasi selengkapnya tentang ACL, lihat Object ACL.
x-oss-storage-class	String	Tidak	Standard	Menentukan kelas penyimpanan objek. Untuk bucket dengan kelas penyimpanan apa pun, jika Anda menentukan header ini saat mengunggah objek, objek tersebut akan disimpan dalam kelas penyimpanan yang ditentukan. Misalnya, jika Anda mengatur x-oss-storage-class ke Standard saat mengunggah objek ke bucket Infrequent Access (IA), objek tersebut akan disimpan sebagai objek Standard. Nilai yang valid: Standard: Standard IA: Akses Jarang Archive: Arsip ColdArchive: Penyimpanan Arsip Dingin DeepColdArchive: Deep Cold Archive Penting Mengatur kelas penyimpanan ke Deep Cold Archive saat unggah mengakibatkan biaya PUT request fees yang lebih tinggi. Kami menyarankan Anda mengatur kelas penyimpanan objek ke Standard saat mengunggah objek, dan 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-meta-*	String	Tidak	x-oss-meta-location	Saat Anda memanggil operasi PutObject, header yang diawali dengan awalan x-oss-meta- dianggap sebagai metadata yang ditentukan pengguna. Misalnya, `x-oss-meta-location`. Sebuah objek dapat memiliki beberapa header metadata yang ditentukan pengguna, tetapi ukuran totalnya tidak boleh melebihi 8 KB. Metadata yang ditentukan pengguna mendukung tanda hubung (-), angka, dan huruf. OSS mengonversi huruf kapital menjadi huruf kecil. Karakter lain, termasuk garis bawah (_), tidak didukung.
x-oss-tagging	String	Tidak	TagA=A&TagB=B	Menentukan satu atau beberapa tag pasangan kunci-nilai untuk objek. Contohnya: `TagA=A&TagB=B`. Catatan Kunci dan nilai harus di-URL-encode. Kunci wajib, sedangkan nilai opsional. Misalnya, Anda dapat mengatur tag objek menjadi `TagA&TagB=B`.
x-oss-object-worm-mode	String	Tidak	COMPLIANCE	Menentukan mode kebijakan retensi untuk objek. Nilainya adalah `COMPLIANCE`. Header ini hanya berlaku untuk bucket yang telah mengaktifkan ObjectWorm. Jika Anda mengatur header ini, Anda juga harus mengatur `x-oss-object-worm-retain-until-date`.
x-oss-object-worm-retain-until-date	String	Tidak	2026-09-30T00:00:00.000Z	Menentukan tanggal kedaluwarsa kebijakan retensi. Tanggal harus dalam format ISO 8601. Header ini hanya berlaku untuk bucket yang telah mengaktifkan ObjectWorm. Sebelum tanggal kedaluwarsa yang ditentukan, objek tidak dapat dihapus atau ditimpa. Jika Anda tidak menentukan header ini, aturan retensi default bucket akan diterapkan pada objek yang diunggah, jika aturan default telah dikonfigurasi.

Parameter respons

Parameter	Tipe	Contoh	Deskripsi
Content-MD5	String	1B2M2Y8AsgTpgAmY7PhC****	Hash MD5 dari objek yang diunggah. Penting Ini adalah hash MD5 dari objek yang diunggah, bukan hash MD5 dari badan respons.
x-oss-hash-crc64ecma	String	316181249502703****	Hash CRC-64 dari objek yang diunggah.
x-oss-version-id	String	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	ID versi objek yang diunggah. OSS hanya mengembalikan header ini jika bucket telah mengaktifkan pengendalian versi.

Untuk informasi selengkapnya tentang header respons umum, lihat Header Respons Umum.

Contoh

Unggah sederhana

Permintaan

PUT /test.txt HTTP/1.1
Host: test.oss-cn-zhangjiakou.aliyuncs.com
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: */*
Connection: keep-alive
Content-Type: text/plain
Date: Tue, 04 Dec 2018 15:56:37 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-zhangjiakou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Transfer-Encoding: chunked

Respons

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 04 Dec 2018 15:56:38 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5C06A3B67B8B5A3DA422299D
ETag: "D41D8CD98F00B204E9800998ECF8****"
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
x-oss-server-time: 7

Mengatur kelas penyimpanan

Permintaan

PUT /oss.jpg HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Cache-control: no-cache 
Expires: Fri, 28 Feb 2012 05:38:42 GMT 
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Fri, 24 Feb 2012 06:03:28 GMT 
Content-Type: image/jpeg 
Content-Length: 344606 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 
[344606 bytes of object data]

Respons

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Sat, 21 Nov 2015 18:52:34 GMT
Content-Type: image/jpeg
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5650BD72207FB30443962F9A
ETag: "A797938C31D59EDD08D86188F6D5B872"

Mengaktifkan pengendalian versi

Permintaan

PUT /test HTTP/1.1
Content-Length: 362149
Content-Type: text/html
Host: versioning-put.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:53:24 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Respons

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 02:53:24 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5CAC0A3DB7AEADE01700****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****
ETag: "4F345B1F066DB1444775AA97D5D2****"

Kode kesalahan

Kode kesalahan	Kode status HTTP	Deskripsi
MissingContentLength	411	Permintaan tidak menggunakan chunked encoding, atau parameter Content-Length tidak diatur.
InvalidEncryptionAlgorithmError	400	Nilai yang ditentukan untuk x-oss-server-side-encryption tidak valid. Nilai yang valid: AES256, KMS.
AccessDenied	403	Anda tidak memiliki izin yang diperlukan untuk mengakses bucket yang ditentukan saat mengunggah objek.
NoSuchBucket	404	Bucket yang ditentukan tidak ada saat Anda mengunggah objek.
InvalidObjectName	400	Nama objek tidak valid. Nama objek mungkin tidak ditentukan, melebihi batas panjang, atau tidak valid.
InvalidArgument	400	Penyebab yang mungkin: Ukuran objek melebihi 5 GB. Nilai parameter seperti x-oss-storage-class tidak valid.
RequestTimeout	400	Content-Length ditentukan, tetapi tidak ada badan pesan yang dikirim, atau badan pesan yang dikirim lebih kecil dari ukuran yang ditentukan. Dalam kasus ini, server menunggu hingga permintaan timeout.
Bad Request	400	Jika Anda menentukan Content-MD5 dalam permintaan, OSS menghitung hash MD5 dari data yang dikirim dan membandingkannya dengan nilai Content-MD5 dalam permintaan. Jika kedua nilai tidak cocok, kesalahan ini dikembalikan.
KmsServiceNotEnabled	403	Anda menentukan KMS untuk x-oss-server-side-encryption tetapi belum membeli paket KMS.
FileAlreadyExists	409	Alasan yang mungkin untuk kesalahan ini adalah sebagai berikut: Header permintaan mencakup `x-oss-forbid-overwrite=true`, tetapi objek dengan nama yang sama sudah ada di bucket. Fitur namespace hierarkis diaktifkan untuk bucket, dan direktori dengan nama yang sama sudah ada di level direktori saat ini.
FileImmutable	409	OSS mengembalikan kesalahan ini jika Anda mencoba memodifikasi objek yang dilindungi oleh kebijakan retensi.

Metode integrasi

SDK
Anda dapat memanggil API PutObject menggunakan SDK berikut:
Java
Python V2
Go V2
C++
PHP V2
C
.NET
Android
iOS
Node.js
Browser.js
Ruby
Harmony
Alat baris perintah ossutil
Untuk informasi tentang perintah ossutil yang sesuai dengan operasi PutObject, lihat put-object.

FAQ

Cara memodifikasi metadata objek

Anda dapat memodifikasi metadata objek menggunakan Konsol OSS, ossbrowser, SDK berbagai bahasa, alat baris perintah ossutil, atau REST API. Misalnya, Anda dapat mengubah Content-Type dari application/octet-stream menjadi image/jpeg. Untuk informasi selengkapnya, lihat Mengelola metadata objek.

Mengapa header Expires tidak berfungsi?

Prioritas header cache
Jika Anda mengatur Expires dan Cache-Control, Cache-Control memiliki prioritas lebih tinggi. Jika Cache-Control mencakup direktif caching seperti max-age=3600, header Expires mungkin diabaikan.

Expires diatur secara salah

Header Expires memerlukan nilai berupa waktu di masa depan dalam format GMT. Kode berikut memberikan contoh cara mengatur header ini menggunakan Node.js SDK:

const OSS = require('ali-oss');

// Buat instans klien OSS.
const client = new OSS({
  // Ganti yourregion dengan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur region ke oss-cn-hangzhou.
  region: 'yourregion',
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Tentukan nama bucket.
  bucket: 'examplebucket',
});

async function setExpires(objectName, expiresDate) {
  try {
    const result = await client.copy(objectName, objectName, {
      meta: {
        'Expires': expiresDate.toGMTString()
      }
    });
    console.log('Header Expires berhasil diatur.');
  } catch (error) {
    console.error('Kesalahan saat mengatur header Expires:', error);
  }
}

// Atur waktu kedaluwarsa absolut untuk konten yang di-cache.
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);

Java	Python V2	Go V2	C++	PHP V2
C	.NET	Android	iOS	Node.js
Browser.js	Ruby	Harmony