CopyObject - Object Storage Service

Operasi CopyObject menyalin objek dalam bucket yang sama atau antar bucket berbeda di wilayah yang sama.

Pengendalian versi

Secara default, x-oss-copy-source menyalin versi terkini dari suatu objek. Untuk menyalin versi tertentu, tambahkan ID versi ke x-oss-copy-source. Jika versi yang ditentukan dari objek sumber merupakan penanda hapus (delete marker), Object Storage Service (OSS) mengembalikan error 404.

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

Jika pengendalian versi diaktifkan untuk bucket tujuan, OSS menghasilkan ID versi unik untuk objek yang disalin. ID 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 yang disalin. Versi baru ini akan menimpa versi yang sudah ada 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, ukuran objek dapat lebih besar dari 5 GB.
- Jika bucket sumber dan tujuan berbeda serta Anda tidak mengubah metode enkripsi atau kelas penyimpanan objek selama operasi salin, ukuran objek tidak boleh melebihi 5 GB.
- Jika Anda mengubah metode enkripsi atau kelas penyimpanan objek selama operasi salin, ukuran objek tidak boleh melebihi 1 GB. Untuk objek berukuran lebih dari 1 GB, gunakan operasi UploadPartCopy.
Izin
Operasi CopyObject dan UploadPartCopy keduanya memerlukan izin baca pada objek sumber.
Saat Anda menggunakan CopyObject di bucket dengan pengendalian versi dinonaktifkan dan objek sumber serta tujuan sama:
- Jika metode enkripsi atau kelas penyimpanan objek sumber tidak diubah, OSS hanya memodifikasi metadata objek sumber tanpa menyalin kontennya.
- Jika metode enkripsi atau kelas penyimpanan objek sumber diubah, OSS memodifikasi metadata dan menyalin konten objek sumber.
Objek sumber adalah tautan simbolik
Saat Anda menggunakan operasi CopyObject pada tautan simbolik, hanya tautannya yang disalin, bukan file yang ditunjuk oleh tautan tersebut.
Bucket memiliki hierarchical namespace yang diaktifkan
Anda tidak dapat menyalin direktori di bucket ini.

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

API	Action	Definisi
CopyObject	`oss:GetObject`	Menyalin objek dalam satu bucket atau antar bucket di 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 ditagih sebagai satu permintaan Put ke bucket tujuan.
Memanggil operasi CopyObject meningkatkan penggunaan penyimpanan bucket tujuan, yang mengakibatkan biaya penyimpanan.
Jika Anda menggunakan CopyObject untuk mengubah kelas penyimpanan objek, data akan ditimpa. Misalnya, jika Anda mengubah kelas penyimpanan objek Infrequent Access (IA) menjadi Standard 10 hari setelah pembuatannya, Anda tetap dikenai biaya untuk sisa 20 hari durasi penyimpanan minimum untuk objek IA. Untuk informasi selengkapnya, lihat Biaya penyimpanan.
Saat Anda memanggil operasi CopyObject, biaya pengambilan data akan dikenakan jika objek sumber merupakan objek IA. Jika objek sumber adalah objek Arsip yang belum dipulihkan melalui operasi RestoreObject, biaya pengambilan data untuk Akses waktu nyata untuk objek Arsip akan dikenakan—dengan catatan fitur tersebut telah diaktifkan untuk bucket tersebut. Biaya ini dibebankan ke akun pemilik bucket sumber. Untuk informasi selengkapnya, 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, semua header permintaan ini harus dimasukkan 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 selama operasi CopyObject. Jika pengendalian versi diaktifkan atau ditangguhkan untuk bucket tujuan, 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 menyetel x-oss-forbid-overwrite ke false, objek tujuan yang sudah ada dengan nama yang sama akan ditimpa. Jika Anda menyetel x-oss-forbid-overwrite ke true, objek tujuan yang sudah ada dengan nama yang sama tidak akan ditimpa. Menyetel header permintaan x-oss-forbid-overwrite mengurangi kinerja pemrosesan permintaan per detik (QPS). Untuk melakukan banyak operasi yang menggunakan header permintaan x-oss-forbid-overwrite (QPS > 1000), hubungi dukungan teknis untuk mencegah gangguan bisnis. Nilai default: false
x-oss-copy-source	String	Ya	/oss-example/oss.jpg	Menentukan objek sumber yang ingin Anda salin. Nilai default: tidak ada
x-oss-copy-source-if-match	String	Tidak	5B3C1A2E053D763E1B002CC607C5****	Operasi salin hanya dilakukan jika ETag objek sumber sesuai dengan ETag yang ditentukan. Jika kondisi terpenuhi, kode status 200 OK dikembalikan. Nilai default: tidak ada
x-oss-copy-source-if-none-match	String	Tidak	5B3C1A2E053D763E1B002CC607C5****	Operasi salin hanya dilakukan jika ETag objek sumber tidak sesuai dengan ETag yang ditentukan. Jika kondisi terpenuhi, kode status 200 OK dikembalikan. Nilai default: tidak ada
x-oss-copy-source-if-unmodified-since	String	Tidak	Mon, 11 May 2020 08:16:23 GMT	Objek disalin hanya jika waktu yang ditentukan sama dengan atau lebih baru daripada waktu modifikasi aktual objek. Jika kondisi terpenuhi, kode status 200 OK dikembalikan. Nilai default: tidak ada
x-oss-copy-source-if-modified-since	String	Tidak	Mon, 11 May 2020 08:16:23 GMT	Objek disalin hanya jika waktu yang ditentukan lebih awal daripada waktu modifikasi aktual objek. Jika kondisi terpenuhi, kode status 200 OK dikembalikan. Nilai default: tidak ada
x-oss-metadata-directive	String	Tidak	COPY	Menentukan cara mengonfigurasi 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 objek tujuan bergantung pada apakah x-oss-server-side-encryption ditentukan dalam operasi salin saat ini. REPLACE: Mengabaikan metadata objek sumber dan menggunakan metadata yang ditentukan dalam permintaan. Penting Jika objek sumber dan tujuan sama serta pengendalian versi dinonaktifkan, 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 mengenkripsi 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 sisi server atau tidak. Jika x-oss-server-side-encryption ditentukan dalam operasi salin, objek tujuan dienkripsi sisi server, terlepas dari apakah objek sumber dienkripsi sisi server atau tidak. Respons operasi salin mencakup header x-oss-server-side-encryption, yang diatur ke algoritma enkripsi objek tujuan. Saat objek tujuan diunduh, respons mencakup header x-oss-server-side-encryption, yang diatur ke algoritma enkripsi objek tersebut.
x-oss-server-side-encryption-key-id	String	Tidak	9468da86-3509-4f8d-a61e-6eab1eac****	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): Izin akses objek sama dengan izin bucket tempat objek disimpan. private: Objek merupakan resource privat. Hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca dan tulis pada objek tersebut. Pengguna lain tidak memiliki izin untuk mengakses objek. public-read: Objek merupakan resource 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. Gunakan izin ini dengan hati-hati. public-read-write: Objek merupakan resource 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	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 menyetel 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 Jika Anda menyalin banyak file, menyetel langsung kelas penyimpanannya ke Deep Cold Archive akan mengakibatkan biaya permintaan PUT yang tinggi. Kami menyarankan Anda menggunakan aturan siklus hidup untuk mentransisikan file ke kelas penyimpanan Deep Cold Archive guna mengurangi biaya permintaan PUT. Untuk informasi selengkapnya tentang kelas penyimpanan, lihat Kelas penyimpanan.
x-oss-tagging	String	Tidak	a:1	Menentukan tag untuk objek. Anda dapat menentukan beberapa tag sekaligus, seperti TagA=A&TagB=B. Catatan Kunci dan nilai harus di-URL-encoded. Jika tag tidak mengandung tanda sama dengan (=), nilainya dianggap sebagai string kosong.
x-oss-tagging-directive	String	Tidak	Copy	Menentukan cara mengonfigurasi 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 ini dihitung berdasarkan algoritma CRC-64/XZ. Saat Anda menggunakan operasi CopyObject, objek yang disalin tidak dijamin 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. 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 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

SDK untuk operasi ini dalam berbagai bahasa adalah sebagai berikut:

ossutil

Untuk informasi selengkapnya tentang 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 alasan berikut: Header permintaan x-oss-copy-source-if-match ditentukan, tetapi ETag objek sumber tidak sesuai dengan ETag yang ditentukan. Header permintaan x-oss-copy-source-if-unmodified-since ditentukan, tetapi waktu yang ditentukan lebih awal daripada waktu modifikasi aktual objek.
Not Modified	304	Error ini dikembalikan karena alasan berikut: Header permintaan x-oss-copy-source-if-none-match ditentukan, tetapi ETag objek sumber sesuai dengan ETag yang ditentukan. Header permintaan x-oss-copy-source-if-modified-since ditentukan, tetapi objek sumber belum dimodifikasi sejak waktu yang ditentukan.
KmsServiceNotEnabled	403	x-oss-server-side-encryption diatur ke KMS, tetapi Anda belum membeli paket KMS.
FileAlreadyExists	409	Error ini dikembalikan karena alasan berikut: Header `x-oss-forbid-overwrite=true` disertakan dalam permintaan untuk mencegah penimpaan objek dengan nama yang sama, tetapi objek dengan nama yang sama sudah ada di bucket. Setelah hierarchical namespace diaktifkan untuk bucket, objek sumber atau tujuan yang Anda tentukan adalah direktori saat menyalin objek di bucket tersebut.
FileImmutable	409	Error ini dikembalikan jika Anda mencoba menghapus atau memodifikasi data di bucket yang berada dalam keadaan terlindungi.

FAQ

Apakah operasi CopyObject mendukung penyalinan file secara batch?

Tidak. Operasi CopyObject hanya menyalin satu file. Untuk menyalin beberapa file sekaligus, Anda dapat menggunakan ossutil. Untuk informasi selengkapnya, lihat cp (Copy files).