CopyObject - Object Storage Service

Anda dapat menggunakan operasi CopyObject untuk menyalin objek antara bucket yang sama atau berbeda dalam wilayah yang sama.

Pengendalian versi

Secara default, x-oss-copy-source menyalin versi terbaru suatu objek. Untuk menyalin versi tertentu, sertakan ID versi dalam x-oss-copy-source. Jika versi sumber yang ditentukan adalah penanda hapus (delete marker), OSS akan mengembalikan error 404, yang menunjukkan bahwa objek tersebut tidak ada.

Anda dapat memulihkan versi sebelumnya dari suatu objek sebagai versi terkini dengan menyalin versi tersebut ke bucket yang sama. OSS kemudian akan menetapkan versi sebelumnya tersebut sebagai versi terkini.

Jika pengendalian versi diaktifkan untuk bucket tujuan, OSS secara otomatis menghasilkan ID versi unik untuk objek yang baru disalin. ID versi ini dikembalikan dalam header respons x-oss-version-id. Jika pengendalian versi dinonaktifkan atau ditangguhkan untuk bucket tujuan, OSS menghasilkan versi dengan ID versi null untuk objek baru tersebut, yang akan menimpa versi sebelumnya yang memiliki ID versi null.

Batasan

Batas ukuran objek
- Jika bucket sumber dan tujuan sama serta Anda tidak mengubah metode enkripsi atau kelas penyimpanan objek selama operasi salin, objek dapat berukuran lebih dari 5 GB.
- Jika bucket sumber dan tujuan berbeda serta Anda tidak mengubah metode enkripsi atau kelas penyimpanan objek selama operasi salin, objek tidak boleh lebih besar dari 5 GB.
- Jika Anda mengubah metode enkripsi atau kelas penyimpanan objek selama operasi salin, objek tidak boleh lebih besar dari 1 GB. Untuk objek yang lebih besar dari 1 GB, gunakan operasi UploadPartCopy.
Izin
Baik operasi CopyObject maupun UploadPartCopy memerlukan izin baca pada objek sumber.
Jika Anda menggunakan operasi CopyObject pada bucket dengan pengendalian versi dinonaktifkan dan objek sumber serta tujuan sama:
- Jika metode enkripsi atau kelas penyimpanan tidak diubah, OSS hanya memodifikasi metadata objek tanpa menyalin kontennya.
- Jika metode enkripsi atau kelas penyimpanan diubah, OSS memodifikasi metadata sekaligus menyalin konten objek.
Objek sumber adalah tautan simbolik
Jika Anda menggunakan operasi CopyObject pada tautan simbolik, hanya tautan simbolik tersebut yang disalin; konten file yang ditunjuk oleh tautan simbolik tidak disalin.
Hierarchical namespace diaktifkan untuk bucket
Jika hierarchical namespace diaktifkan untuk bucket, Anda tidak dapat menyalin direktori.
Mencegah konflik penimpaan file
Jika Anda mengaktifkan fitur Prevent File Overwrite, Anda tidak dapat menggunakan CopyObject untuk mengubah kelas penyimpanan file, misalnya dari Standard ke Archive Storage. Sebagai gantinya, gunakan konversi lifecycle otomatis.

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 kebijakan RAM atau kebijakan Bucket.

API	Action	Definisi
CopyObject	`oss:GetObject`	Menyalin objek dalam satu bucket atau antar bucket dalam wilayah yang sama.
	`oss:PutObject`
	`oss:GetObjectVersion`	Jika Anda menentukan versi objek sumber melalui versionId, izin ini juga diperlukan.
	`oss:GetObjectTagging`	Jika Anda menyalin tag objek melalui x-oss-tagging, izin-izin ini diperlukan.
	`oss:PutObjectTagging`
	`oss:GetObjectVersionTagging`	Jika Anda menentukan tag untuk versi tertentu dari objek sumber melalui versionId, izin ini juga diperlukan.
	`kms:GenerateDataKey`	Saat menyalin objek, jika metadata objek tujuan berisi X-Oss-Server-Side-Encryption: KMS, kedua izin ini diperlukan.
	`kms:Decrypt`

Penagihan

Setiap panggilan ke operasi CopyObject dihitung sebagai satu permintaan PUT untuk bucket tujuan.
Operasi CopyObject meningkatkan penggunaan penyimpanan bucket tujuan.
Mengubah kelas penyimpanan objek menggunakan operasi CopyObject melibatkan penimpaan data. Misalnya, jika objek Infrequent Access (IA) ditimpa dan kelas penyimpanannya diubah menjadi Standard dalam waktu 10 hari sejak pembuatannya, biaya akan dikenakan untuk 20 hari penyimpanan IA karena durasi penyimpanan minimum tidak terpenuhi. Untuk informasi lebih lanjut tentang biaya penyimpanan, lihat Biaya penyimpanan.
Saat Anda memanggil operasi CopyObject, biaya pengambilan data akan dikenakan tergantung pada jenis objek sumber. Jika objek sumber merupakan objek IA, biaya pengambilan data untuk penyimpanan IA akan dikenakan. Jika objek sumber merupakan objek Archive Storage yang belum dipulihkan melalui RestoreObject dan fitur Akses waktu nyata untuk objek Arsip diaktifkan pada bucket tersebut, biaya pengambilan data untuk akses waktu nyata akan dikenakan. Biaya ini dibebankan ke akun pemilik bucket sumber. Untuk informasi selengkapnya mengenai penagihan, lihat Biaya pemrosesan data.

Sintaksis permintaan

PUT /DestObjectName HTTP/1.1
Host: DestBucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
x-oss-copy-source: /SourceBucketName/SourceObjectName

Header permintaan

Semua header permintaan untuk operasi salin dimulai dengan x-oss-. Oleh karena itu, Anda harus menyertakan semua header permintaan ini dalam string signature.

Nama	Tipe	Wajib	Nilai	Deskripsi
x-oss-forbid-overwrite	String	Tidak	true	Menentukan apakah objek tujuan yang sudah ada dengan nama yang sama akan ditimpa. Jika pengendalian versi diaktifkan atau ditangguhkan untuk bucket tujuan, header permintaan x-oss-forbid-overwrite tidak berlaku. Artinya, penimpaan objek dengan nama yang sama tetap diizinkan. Jika x-oss-forbid-overwrite tidak ditentukan atau x-oss-forbid-overwrite disetel ke false, Anda dapat menimpa Objek tujuan dengan nama yang sama. Jika Anda mengatur x-oss-forbid-overwrite ke true, objek tujuan yang sudah ada dengan nama yang sama tidak akan ditimpa. Mengatur header permintaan x-oss-forbid-overwrite menurunkan performa pemrosesan QPS. Untuk menggunakan header permintaan x-oss-forbid-overwrite dalam banyak operasi (QPS > 1000), hubungi dukungan teknis agar tidak memengaruhi bisnis Anda. Nilai default: false
x-oss-copy-source	String	Ya	/oss-example/oss.jpg	Menentukan alamat sumber untuk operasi salin. Nilai default: tidak ada
x-oss-copy-source-if-match	String	Tidak	5B3C1A2E053D763E1B002CC607C5****	Operasi salin dilakukan dan respons 200 OK dikembalikan hanya jika ETag objek sumber sesuai dengan ETag yang Anda berikan. Nilai default: tidak ada
x-oss-copy-source-if-none-match	String	Tidak	5B3C1A2E053D763E1B002CC607C5****	Operasi salin dilakukan dan respons 200 OK dikembalikan hanya jika ETag objek sumber tidak sesuai dengan ETag yang Anda berikan. Nilai default: tidak ada
x-oss-copy-source-if-unmodified-since	String	Tidak	Mon, 11 May 2020 08:16:23 GMT	Objek disalin dan respons 200 OK dikembalikan hanya jika waktu yang Anda tentukan sama dengan atau lebih baru daripada waktu modifikasi aktual objek. Nilai default: tidak ada
x-oss-copy-source-if-modified-since	String	Tidak	Mon, 11 May 2020 08:16:23 GMT	Objek disalin dan respons 200 OK dikembalikan hanya jika waktu yang Anda tentukan lebih awal daripada waktu modifikasi aktual objek. Nilai default: tidak ada
x-oss-metadata-directive	String	Tidak	COPY	Menentukan cara mengatur metadata objek tujuan. COPY (default): Menyalin metadata dari objek sumber ke objek tujuan. OSS tidak menyalin properti x-oss-server-side-encryption dari objek sumber ke objek tujuan. Metode enkripsi sisi server untuk objek tujuan bergantung pada apakah x-oss-server-side-encryption ditentukan dalam operasi salin. REPLACE: Mengabaikan metadata objek sumber dan menggunakan metadata yang ditentukan dalam permintaan. Penting Jika objek sumber dan tujuan sama serta pengendalian versi tidak diaktifkan, metadata objek sumber diabaikan terlepas dari nilai x-oss-metadata-directive. Objek tujuan menggunakan metadata yang ditentukan dalam permintaan.
x-oss-server-side-encryption	String	Tidak	AES256	Menentukan algoritma enkripsi sisi server yang digunakan OSS untuk membuat objek tujuan. Nilai yang valid: AES256 dan KMS Penting Anda tidak dapat menentukan x-oss-server-side-encryption saat menyalin objek tautan simbolik. Anda hanya dapat menggunakan algoritma enkripsi KMS setelah membeli paket KMS. Jika tidak, OSS mengembalikan error KmsServiceNotEnabled. Jika x-oss-server-side-encryption tidak ditentukan dalam operasi salin, objek tujuan tidak dienkripsi sisi server, terlepas dari apakah objek sumber dienkripsi atau tidak. Jika x-oss-server-side-encryption ditentukan dalam operasi salin, objek tujuan dienkripsi sisi server, terlepas dari apakah objek sumber dienkripsi atau tidak. Header respons untuk operasi salin mencakup x-oss-server-side-encryption, dan nilainya adalah algoritma enkripsi objek tujuan. Saat objek tujuan diunduh, header respons juga mencakup x-oss-server-side-encryption, dan nilainya adalah algoritma enkripsi objek tersebut.
x-oss-server-side-encryption-key-id	String	Tidak	9468da86-3509-4f8d-a61e-6eab1eac****	Menentukan kunci master pelanggan (CMK) yang dikelola oleh KMS. Parameter ini hanya berlaku ketika x-oss-server-side-encryption diatur ke KMS.
x-oss-object-acl	String	Tidak	private	Menentukan izin akses objek tujuan saat dibuat di OSS. Nilai yang valid: default (default): Objek mewarisi izin 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 izin ini dengan hati-hati. public-read-write: Objek merupakan resource publik-baca-tulis. Semua pengguna memiliki izin baca dan tulis pada objek tersebut. Gunakan izin ini dengan hati-hati. Untuk informasi lebih lanjut 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 header ini saat mengunggah objek, objek yang diunggah akan disimpan dalam kelas penyimpanan yang ditentukan. Misalnya, jika Anda mengatur x-oss-storage-class ke Standard saat mengunggah objek ke bucket IA, objek tersebut akan disimpan sebagai objek Standard. Nilai yang valid: Standard (default): Standard IA: Infrequent Access Archive: Archive Storage ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Penting Untuk menyalin banyak file, langsung menentukan Deep Cold Archive sebagai kelas penyimpanan untuk file yang disalin mengakibatkan biaya tinggi untuk permintaan PUT. Kami menyarankan Anda menggunakan aturan siklus hidup untuk mengubah file ke kelas penyimpanan Deep Cold Archive guna mengurangi biaya permintaan PUT. Untuk informasi lebih lanjut tentang kelas penyimpanan, lihat Kelas penyimpanan.
x-oss-tagging	String	Tidak	a:1	Menentukan tag objek. Anda dapat menentukan beberapa tag sekaligus, misalnya TagA=A&TagB=B. Catatan Kunci dan nilai harus di-URL-encoded. Jika suatu item tidak mengandung tanda sama dengan (=), nilai dianggap sebagai string kosong.
x-oss-tagging-directive	String	Tidak	Copy	Menentukan cara mengatur tag objek tujuan. Nilai yang valid: Copy (default): Menyalin tag dari objek sumber ke objek tujuan. Replace: Mengabaikan tag objek sumber dan menggunakan tag yang ditentukan dalam permintaan.

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

Header respons

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

Elemen respons

Nama	Tipe	Contoh	Deskripsi
CopyObjectResult	Kontainer	N/A	Kontainer untuk hasil operasi CopyObject. Nilai default: tidak ada
ETag	String	5B3C1A2E053D763E1B002CC607C5****	ETag objek tujuan. Elemen induk: CopyObjectResult
LastModified	String	Fri, 24 Feb 2012 07:18:48 GMT	Waktu terakhir objek tujuan diperbarui. Elemen induk: CopyObjectResult

Contoh

Pengendalian versi dinonaktifkan

Permintaan contoh

PUT /test%2FAK.txt HTTP/1.1
Host: tesx.oss-cn-zhangjiakou.aliyuncs.com
Accept-Encoding: identity
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: text/html
Connection: keep-alive
x-oss-copy-source: /test/AK.txt
date: Fri, 28 Dec 2018 09:41:55 GMT
authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Content-Length: 0

Respons contoh

x-oss-hash-crc64ecma menunjukkan nilai CRC 64-bit objek. Nilai CRC 64-bit ini dihitung berdasarkan standar CRC-64/XZ. Operasi CopyObject tidak menjamin bahwa objek hasil salinan memiliki nilai CRC 64-bit yang sama.

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Fri, 28 Dec 2018 09:41:56 GMT
Content-Type: application/xml
Content-Length: 184
Connection: keep-alive
x-oss-request-id: 5C25EFE4462CE00EC6D87156
ETag: "F2064A169EE92E9775EE5324D0B1****"
x-oss-hash-crc64ecma: 12753002859196105360
x-oss-server-time: 150
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <ETag>"F2064A169EE92E9775EE5324D0B1****"</ETag>
  <LastModified>2018-12-28T09:41:56.000Z</LastModified>
</CopyObjectResult>

Menyalin objek tanpa menentukan ID versi

Permintaan contoh

PUT /dest-object-example HTTP/1.1
Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 03:45:32 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-copy-source: /versioning-copy-source/source-object

Respons contoh

Dalam contoh ini, x-oss-copy-source-version-id adalah ID versi objek sumber, yaitu versi terkini. x-oss-version-id adalah ID versi objek yang baru disalin.

HTTP/1.1 200 OK
x-oss-copy-source-version-id: CAEQNRiBgIC28uaA0BYiIDY5OGIwNmNlNjYyMTRjNTc4N2M2OGNiMjZkZTQ2****
x-oss-version-id: CAEQNxiBgIDG8uaA0BYiIGZhZDRkZTk5Zjg3YzRhNzdiMWEwZGViNDM1NTFh****
x-oss-request-id: 5CAC155CB7AEADE01700****
Content-Type: application/xml
Content-Length: 184
Connection: keep-alive
Date: Tue, 09 Apr 2019 03:45:32 GMT
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <ETag>"C81E728D9D4C2F636F067F89CC14****"</ETag>
  <LastModified>2019-04-09T03:45:32.000Z</LastModified>
</CopyObjectResult>

Menyalin objek dengan menentukan ID versi

Permintaan contoh

PUT /dest-object-example HTTP/1.1
Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 03:45:32 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-copy-source: /versioning-copy-source/source-object?versionId=CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****

Respons contoh

Dalam contoh ini, x-oss-copy-source-version-id adalah ID versi objek sumber, yaitu versi yang ditentukan dalam header permintaan x-oss-copy-source. x-oss-version-id adalah ID versi objek yang baru disalin.

HTTP/1.1 200 OK
x-oss-copy-source-version-id: CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****
x-oss-version-id: CAEQNxiBgMDP8uaA0BYiIDIyNGNhZDQ1M2M3NzRkZThiNzE0N2I3ZDkxOWY4****
x-oss-request-id: 5CAC155CB7AEADE01700****
Content-Type: application/xml
Content-Length: 184
Connection: keep-alive
Date: Tue, 09 Apr 2019 03:45:32 GMT
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
  <LastModified>2019-04-09T03:45:32.000Z</LastModified>
</CopyObjectResult>

SDK

Anda dapat menggunakan kit pengembangan perangkat lunak (SDK) untuk bahasa-bahasa berikut untuk memanggil operasi ini.

Alat baris perintah ossutil

Untuk perintah ossutil yang sesuai dengan operasi CopyObject, lihat copy-object.

Kode error

Kode error	Kode status HTTP	Deskripsi
InvalidArgument	400	Nilai parameter, seperti x-oss-storage-class, tidak valid.
Precondition Failed	412	Error ini dikembalikan karena salah satu alasan berikut: Header permintaan x-oss-copy-source-if-match ditentukan, tetapi ETag objek sumber tidak sesuai dengan ETag yang Anda berikan. Header permintaan x-oss-copy-source-if-unmodified-since ditentukan, tetapi waktu yang Anda tentukan lebih awal daripada waktu modifikasi aktual objek.
Not Modified	304	Error ini dikembalikan karena salah satu alasan berikut: Header permintaan x-oss-copy-source-if-none-match ditentukan, tetapi ETag objek sumber sesuai dengan ETag yang Anda berikan. Header permintaan x-oss-copy-source-if-modified-since ditentukan, tetapi objek sumber belum dimodifikasi sejak waktu yang Anda tentukan.
KmsServiceNotEnabled	403	Anda mengatur x-oss-server-side-encryption ke KMS, tetapi Anda belum membeli paket KMS.
FileAlreadyExists	409	Error ini dikembalikan karena salah satu alasan berikut: Header permintaan menyertakan `x-oss-forbid-overwrite=true` untuk mencegah penimpaan objek dengan nama yang sama, tetapi objek dengan nama yang sama sudah ada di bucket. Fitur hierarchical namespace diaktifkan untuk bucket, dan Anda mencoba menyalin objek di mana objek sumber atau tujuan adalah direktori.
FileImmutable	409	Error ini dikembalikan jika Anda mencoba menghapus atau memodifikasi data di bucket yang berada dalam keadaan terlindungi.

FAQ

Apakah CopyObject mendukung penyalinan file secara batch?

Tidak. Operasi CopyObject digunakan untuk menyalin satu file saja. Untuk menyalin beberapa file sekaligus, Anda dapat menggunakan ossutil. Untuk informasi selengkapnya, lihat cp (copy files).