CopyObject - Object Storage Service - Alibaba Cloud Documentation Center

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

Pengendalian versi

Secara default, header x-oss-copy-source menyalin versi terkini dari suatu objek. Untuk menyalin versi tertentu, sertakan ID versi dalam header x-oss-copy-source. Jika versi sumber yang ditentukan adalah penanda hapus, OSS 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 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. Versi baru ini akan menimpa versi yang sudah ada sebelumnya dengan 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. Jika objek lebih besar dari 1 GB, Anda harus menggunakan operasi UploadPartCopy.
Izin
Kedua operasi CopyObject dan UploadPartCopy memerlukan izin baca pada objek sumber.
Jika Anda menggunakan operasi CopyObject pada bucket tempat Pengendalian versi dinonaktifkan dan objek sumber serta tujuan sama:
- Jika metode enkripsi atau kelas penyimpanan tidak diubah, OSS hanya memodifikasi metadata objek dan tidak 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 siklus hidup 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 Bucket Policy.

API	Action	Deskripsi
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 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, jika objek sumber adalah objek IA, biaya pengambilan data untuk penyimpanan IA akan dikenakan. Jika objek sumber adalah objek Archive Storage yang belum dipulihkan menggunakan RestoreObject dan akses waktu nyata untuk objek Arsip diaktifkan untuk bucket tersebut, biaya pengambilan data untuk akses waktu nyata akan dikenakan. Biaya-biaya ini dibebankan ke akun pemilik bucket sumber. Untuk informasi lebih lanjut tentang 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 diawali dengan x-oss-. Oleh karena itu, Anda harus menambahkan semua header permintaan ini ke 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 diperbolehkan. Jika x-oss-forbid-overwrite tidak ditentukan atau x-oss-forbid-overwrite diatur 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 untuk menghindari dampak pada 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 mentransisikan 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 (=), nilainya 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 lebih lanjut, lihat Header permintaan umum.

Header respons

Operasi ini hanya menggunakan header respons umum. Untuk informasi lebih lanjut, 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 yang dihasilkan memiliki nilai CRC 64-bit.

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 mencakup `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. Untuk menyalin beberapa file sekaligus, Anda dapat menggunakan ossutil. Untuk informasi lebih lanjut, lihat cp (copy files).