API PutObject Object Storage Service - Object Storage Service

Gunakan API PutObject untuk mengunggah file ke bucket Object Storage Service (OSS). Ukuran maksimum file yang dapat diunggah dalam satu operasi adalah 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 file yang dapat diunggah dalam satu operasi adalah 5 GB. Untuk mengunggah file yang lebih besar dari 5 GB, gunakan fitur multipart upload.
Saat mengunggah file dengan nama yang sama seperti file yang sudah ada, file tersebut akan ditimpa secara default dan kode status 200 OK dikembalikan. Anda dapat mengatur parameter untuk mencegah penimpaan guna menghindari penimpaan tidak sengaja terhadap file penting.
OSS menggunakan struktur penyimpanan datar dan tidak memiliki direktori seperti sistem file tradisional. Anda dapat mensimulasikan struktur folder dengan membuat objek kosong yang diakhiri dengan garis miring (/).

Izin

Akun Alibaba Cloud memiliki izin penuh secara default. Namun, pengguna Resource Access Management (RAM) atau peran RAM di bawah akun tersebut tidak memiliki izin hingga diberikan oleh Akun Alibaba Cloud atau administrator melalui Kebijakan RAM atau Kebijakan Bucket.

API	Action	Definisi
PutObject	`oss:PutObject`	Mengunggah objek.
	`oss:PutObjectTagging`	Saat mengunggah objek, 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`

Pengendalian versi

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

Dalam bucket yang Pengendalian versinya ditangguhkan, ID versi objek baru bernilai null. OSS memastikan hanya ada satu versi null untuk suatu objek.

Parameter permintaan

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

Parameter	Tipe	Wajib	Contoh	Deskripsi
Authorization	String	Tidak	OSS qn6q************:77Dv**************	Menunjukkan bahwa permintaan telah diautentikasi dan diotorisasi. Untuk informasi selengkapnya tentang cara menghitung nilai Authorization, lihat Sertakan tanda tangan dalam header. Header Authorization biasanya wajib. Namun, Anda tidak perlu menyertakan header ini jika tanda tangan disertakan dalam URL. Untuk informasi selengkapnya, lihat Sertakan tanda tangan dalam URL. Nilai default: none
Cache-Control	String	Tidak	no-cache	Menentukan perilaku caching saat objek diunduh. Nilai yang valid: no-cache: Cache harus memvalidasi ulang konten dengan server asal sebelum menyajikannya. Jika konten berubah, server mengembalikan objek baru. Jika tidak, cache dikonfirmasi masih valid. no-store: Semua konten objek tidak di-cache. public: Semua konten objek di-cache. private: Semua konten objek hanya di-cache pada klien. max-age=<seconds>: Periode validitas konten yang di-cache. Satuan: detik. Opsi ini hanya tersedia di HTTP 1.1. Nilai default: none
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 jalur unduhan yang ditentukan browser dengan nama objek asli. Content-Disposition:attachment; filename="yourFileName": Objek diunduh ke jalur unduhan yang ditentukan browser dengan nama objek kustom. yourFileName menentukan nama kustom objek yang diunduh, misalnya example.jpg. Jika Anda ingin mengunduh objek ke jalur unduhan yang ditentukan browser, perhatikan hal-hal berikut: Catatan Jika nama objek berisi 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 nama objek yang berisi karakter non-ASCII (seperti bahasa Tionghoa) ditangani dengan benar saat diunduh dan tidak menghasilkan nama file yang rusak, Anda harus melakukan URL-encode terhadap 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. Untuk informasi selengkapnya, lihat Apa yang harus saya lakukan jika objek citra diunduh sebagai lampiran tetapi tidak dapat dipratinjau saat saya mengakses objek citra tersebut melalui URL-nya? Nilai default: none
Content-Encoding	String	Tidak	identity	Menyatakan codec objek. Anda harus menentukan codec aktual objek. Jika tidak, parsing atau kegagalan unduhan dapat terjadi di sisi klien. Jika objek tidak dikodekan, biarkan header ini kosong. Nilai yang valid: identity (default): OSS tidak mengompresi atau mengkodekan objek. gzip: OSS menggunakan algoritma kompresi LZ77 yang dibuat oleh Lempel dan Ziv pada tahun 1977 serta Pemeriksaan redundansi siklik (CRC) 32-bit untuk mengkodekan objek. compress: OSS menggunakan algoritma kompresi Lempel–Ziv–Welch (LZW) untuk mengkodekan objek. deflate: OSS menggunakan library zlib dan algoritma deflate untuk mengkodekan objek. br: OSS menggunakan algoritma Brotli untuk mengkodekan objek. Nilai default: none
Content-MD5	String	Tidak	eB5eJF1ptWaXm4bijSPyxw==	Digunakan untuk memeriksa integritas konten pesan. Content-MD5 adalah nilai yang dihasilkan oleh algoritma MD5. Jika Anda mengatur header ini, OSS menghitung hash Content-MD5 dari badan pesan dan memeriksa konsistensinya. Untuk informasi selengkapnya, lihat Cara menghitung Content-MD5. Untuk memastikan integritas data, OSS menyediakan beberapa metode untuk memverifikasi hash MD5 data. Untuk melakukan verifikasi MD5 menggunakan Content-MD5, tambahkan header Content-MD5 ke permintaan. Nilai default: none
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 yang ditransfer dalam badan permintaan, OSS tetap membuat objek. Namun, ukuran objek akan 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: none
x-oss-forbid-overwrite	String	Tidak	false	Menentukan apakah objek dengan nama yang sama akan ditimpa selama operasi PutObject. Jika bucket tujuan telah mengaktifkan atau menangguhkan pengendalian versi, header permintaan x-oss-forbid-overwrite tidak berlaku. Artinya, objek dengan nama yang sama dapat ditimpa. Jika Anda tidak menentukan x-oss-forbid-overwrite atau mengatur x-oss-forbid-overwrite ke false, objek dengan nama yang sama dapat ditimpa. Jika Anda mengatur x-oss-forbid-overwrite ke true, objek dengan nama yang sama tidak dapat ditimpa. Mengatur header permintaan x-oss-forbid-overwrite memengaruhi performa QPS. Jika banyak operasi (QPS>1000) memerlukan header permintaan x-oss-forbid-overwrite, hubungi dukungan teknis untuk mencegah dampak terhadap operasi bisnis Anda. Nilai default: false
x-oss-server-side-encryption	String	Tidak	AES256	Menentukan metode enkripsi sisi server saat Anda membuat objek. Nilai yang valid: AES256, KMS, Jika Anda menentukan header ini, header tersebut dikembalikan dalam header respons. OSS mengenkripsi dan menyimpan objek yang diunggah. Saat Anda mengunduh objek, header respons mencakup 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 izin akses objek saat objek dibuat di OSS. Nilai yang valid: default: Objek mewarisi izin akses bucket. private: Objek merupakan resource privat. Hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca-tulis terhadap objek. Pengguna lain tidak dapat mengakses objek. public-read: Objek merupakan resource baca-publik. Hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca-tulis terhadap objek. Pengguna lain hanya memiliki izin baca. Gunakan izin ini dengan hati-hati. public-read-write: Objek merupakan resource baca-tulis publik. Semua pengguna memiliki izin baca-tulis terhadap objek. Gunakan izin ini dengan hati-hati. Untuk informasi selengkapnya tentang izin akses, lihat Object ACL.
x-oss-storage-class	String	Tidak	Standard	Menentukan kelas penyimpanan objek. Untuk bucket dengan kelas penyimpanan apa pun, jika Anda menentukan parameter ini saat mengunggah objek, objek akan disimpan dalam kelas 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: Archive Storage ColdArchive: Penyimpanan Arsip Dingin DeepColdArchive: Deep Cold Archive Penting Mengatur kelas penyimpanan ke Deep Cold Archive saat pengunggahan mengakibatkan biaya PUT request fees yang lebih tinggi. Kami menyarankan 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 Kelas penyimpanan.
x-oss-meta-*	String	Tidak	x-oss-meta-location	Saat Anda menggunakan API PutObject, parameter yang diawali dengan x-oss-meta- dianggap sebagai metadata yang ditentukan pengguna, seperti `x-oss-meta-location`. Sebuah objek dapat memiliki beberapa parameter semacam ini, tetapi ukuran total semua metadata tidak boleh melebihi 8 KB. Metadata mendukung tanda hubung (-), angka, dan huruf kecil (a-z). Huruf kapital akan diubah menjadi huruf kecil. Karakter lain, termasuk garis bawah (_), tidak didukung.
x-oss-tagging	String	Tidak	TagA=A&TagB=B	Menentukan tag untuk objek dalam format pasangan kunci-nilai. Anda dapat mengatur beberapa tag sekaligus, seperti `TagA=A&TagB=B`. Catatan Kunci dan nilai harus di-URL-encode. Kunci wajib diisi, sedangkan nilai bersifat opsional. Misalnya, Anda dapat mengatur tag objek menjadi `TagA&TagB=B`.

Untuk informasi selengkapnya, lihat Header Respons Umum.

Parameter respons

Parameter	Tipe	Contoh	Deskripsi
Content-MD5	String	1B2M2Y8AsgTpgAmY7PhC****	Hash MD5 dari file yang diunggah. Penting Hash MD5 adalah hash file yang diperoleh setelah klien menyelesaikan pengunggahan, bukan hash MD5 dari badan respons.
x-oss-hash-crc64ecma	String	316181249502703****	Nilai CRC-64 dari file yang diunggah.
x-oss-version-id	String	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	ID versi file. Header respons ini hanya dikembalikan saat file diunggah ke bucket yang telah mengaktifkan pengendalian versi.

Untuk informasi selengkapnya, lihat Header Respons Umum.

Contoh

Pengunggahan sederhana

Contoh 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-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Transfer-Encoding: chunked

Contoh 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

Contoh 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/jpg 
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]

Contoh respons

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

Mengaktifkan pengendalian versi

Contoh 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

Contoh 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 error

Kode error	Kode status HTTP	Deskripsi
MissingContentLength	411	Header 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	Pengguna tidak memiliki izin akses yang diperlukan untuk bucket yang ditentukan saat menambahkan objek.
NoSuchBucket	404	Bucket yang ditentukan tidak ada saat menambahkan objek.
InvalidObjectName	400	Nama objek tidak valid. Hal ini bisa terjadi karena nama objek tidak ditentukan, melebihi batas panjang, atau tidak valid.
InvalidArgument	400	Error ini dapat dikembalikan karena alasan berikut: Ukuran objek yang akan ditambahkan 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, error ini dikembalikan.
KmsServiceNotEnabled	403	Anda menentukan KMS untuk x-oss-server-side-encryption tetapi belum membeli paket KMS sebelumnya.
FileAlreadyExists	409	Kemungkinan penyebab: Header permintaan mencakup `x-oss-forbid-overwrite=true` untuk mencegah penimpaan file dengan nama yang sama, tetapi file 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	Error ini dikembalikan jika Anda mencoba menghapus atau mengubah data di bucket yang berada dalam status terlindungi.

Metode integrasi

SDK
SDK untuk API PutObject dalam berbagai bahasa adalah sebagai berikut:
Java
Python V2
Go V2
C++
PHP V2
C
.NET
Android
iOS
Node.js
Browser.js
Ruby
Harmony
antarmuka baris perintah ossutil
Untuk perintah ossutil yang sesuai dengan API PutObject, lihat put-object.

FAQ

Bagaimana cara mengubah metadata file yang telah diunggah?

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

Mengapa header Expires yang saya atur 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 Pengaturan salah

Nilai header Expires harus berupa waktu mendatang dalam format GMT. Kode berikut memberikan contoh cara mengatur header ini menggunakan Node.js SDK:

// Komentar: Impor modul OSS
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 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('Error 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