全部产品
Search

搜索本产品

    Object Storage Service：Salin objek (Python SDK V1)

    文档中心

    Object Storage Service：Salin objek (Python SDK V1)

    更新时间：Nov 27, 2025

    Topik ini menjelaskan cara menyalin objek dalam satu bucket atau antar bucket di wilayah yang sama.

    Catatan penggunaan

    • Pada topik ini, titik akhir publik wilayah China (Hangzhou) digunakan. Jika Anda ingin mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama dengan OSS, gunakan titik akhir internal. Untuk informasi selengkapnya mengenai wilayah dan titik akhir OSS, lihat Wilayah dan titik akhir.

    • Pada topik ini, kredensial akses diperoleh dari variabel lingkungan. Untuk informasi selengkapnya tentang cara mengonfigurasi kredensial akses, lihat Konfigurasikan kredensial akses menggunakan OSS SDK untuk Python 1.0.

    • Pada topik ini, instans OSSClient dibuat menggunakan titik akhir OSS. Jika Anda ingin membuat instans OSSClient menggunakan nama domain kustom atau Security Token Service (STS), lihat Inisialisasi.

    • Untuk menyalin objek, Anda harus memiliki izin baca pada objek sumber serta izin baca dan tulis pada bucket tujuan.

    • Pastikan tidak ada kebijakan retensi yang dikonfigurasi untuk bucket sumber maupun bucket tujuan. Jika tidak, pesan error The object you specified is immutable. akan dikembalikan.

    • Bucket sumber dan bucket tujuan harus berada di wilayah yang sama. Misalnya, objek tidak dapat disalin dari bucket yang berlokasi di wilayah China (Hangzhou) ke bucket lain di wilayah China (Qingdao).

    Salin objek kecil

    Anda dapat menggunakan simple copy untuk menyalin objek yang ukurannya kurang dari 1 GB. Kode berikut memberikan contoh cara menggunakan simple copy untuk menyalin objek bernama srcexampleobject.txt dari bucket srcexamplebucket ke objek bernama destexampleobject.txt di destexamplebucket:

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Peroleh kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. 
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Tentukan nama bucket sumber. Contoh: srcexamplebucket. 
src_bucket_name = 'srcexamplebucket'
# Tentukan nama bucket tujuan. Bucket tujuan harus berada di wilayah yang sama dengan bucket sumber. Contoh: destexamplebucket. 
# Jika Anda menyalin objek dalam satu bucket, pastikan Anda menentukan nama bucket yang sama untuk bucket sumber dan bucket tujuan. 
dest_bucket_name = 'destexamplebucket'

# Tentukan titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur titik akhir menjadi https://oss-cn-hangzhou.aliyuncs.com. 
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Tentukan ID wilayah yang sesuai dengan titik akhir. Contoh: cn-hangzhou. Parameter ini diperlukan jika Anda menggunakan algoritma signature V4.
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, dest_bucket_name, region=region)


# Tentukan path lengkap objek sumber. Jangan sertakan nama bucket dalam path lengkap. Contoh: srcexampleobject.txt. 
src_object_name = 'srcexampleobject.txt'
# Tentukan path lengkap objek tujuan. Jangan sertakan nama bucket dalam path lengkap. Contoh: destexampleobject.txt. 
dest_object_name = 'destexampleobject.txt'

# headers = dict()
# Tentukan apakah operasi CopyObject akan menimpa objek yang memiliki nama yang sama. Pada contoh ini, parameter diatur ke true, yang berarti operasi tidak akan menimpa objek yang memiliki nama yang sama. 
# headers['x-oss-forbid-overwrite'] = 'true'
# Tentukan path objek sumber. 
# headers[OSS_COPY_OBJECT_SOURCE] = '/example-bucket-by-util/recode-test.txt'
# Jika nilai ETag objek sumber sama dengan nilai ETag yang ditentukan dalam permintaan, OSS akan menyalin objek dan mengembalikan 200 OK. 
# headers['x-oss-copy-source-if-match'] = '5B3C1A2E053D763E1B002CC607C5****'
# Jika nilai ETag objek sumber berbeda dari nilai ETag yang ditentukan dalam permintaan, OSS akan menyalin objek dan mengembalikan 200 OK. 
# headers['x-oss-copy-source-if-none-match'] = '5B3C1A2E053D763E1B002CC607C5****'
# Jika waktu yang ditentukan dalam permintaan sama dengan atau lebih baru daripada waktu modifikasi aktual objek, OSS akan menyalin objek dan mengembalikan 200 OK. 
# headers['x-oss-copy-source-if-unmodified-since'] = '2021-12-09T07:01:56.000Z'
# Jika objek sumber dimodifikasi setelah waktu yang ditentukan dalam permintaan, OSS akan menyalin objek. 
# headers['x-oss-copy-source-if-modified-since'] = '2021-12-09T07:01:56.000Z'
# Tentukan metode yang digunakan untuk mengonfigurasi metadata objek tujuan. Jika Anda mengatur metode ke COPY, metadata objek sumber akan disalin ke objek tujuan. 
# headers[OSS_METADATA_DIRECTIVE] = 'COPY'
# Tentukan algoritma enkripsi sisi server yang digunakan untuk mengenkripsi objek tujuan saat OSS membuat objek tersebut. 
# headers[OSS_SERVER_SIDE_ENCRYPTION] = 'KMS'
# Tentukan customer master key (CMK) yang dikelola oleh Key Management Service (KMS). Parameter ini hanya berlaku jika x-oss-server-side-encryption diatur ke KMS. 
# headers['x-oss-server-side-encryption-key-id'] = '9468da86-3509-4f8d-a61e-6eab1eac****'
# Tentukan daftar kontrol akses (ACL) objek tujuan. Pada contoh ini, parameter diatur ke OBJECT_ACL_PRIVATE, yang berarti hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca dan tulis pada objek tersebut. 
# headers[OSS_OBJECT_ACL] = oss2.OBJECT_ACL_PRIVATE
# Tentukan kelas penyimpanan objek tujuan. Pada contoh ini, kelas penyimpanan diatur ke Standard. 
# headers['x-oss-storage-class'] = oss2.BUCKET_STORAGE_CLASS_STANDARD
# Tentukan tag untuk objek. Anda dapat menentukan beberapa tag sekaligus untuk objek tersebut. 
# headers[OSS_OBJECT_TAGGING] = 'k1=v1&k2=v2&k3=v3'
# Tentukan metode yang digunakan untuk mengonfigurasi tag objek tujuan. Jika Anda mengatur metode ke COPY, tag objek sumber akan disalin ke objek tujuan. 
# headers[OSS_OBJECT_TAGGING_COPY_DIRECTIVE] = 'COPY'
# result = bucket.copy_object(src_bucket_name, src_object_name, dest_object_name, headers=headers)

# Salin objek dari bucket sumber ke bucket tujuan. 
result = bucket.copy_object(src_bucket_name, src_object_name, dest_object_name)

# Lihat respons. Jika kode status HTTP 200 dikembalikan, operasi berhasil. 
print('result.status:', result.status)

    Salin objek besar

    Untuk menyalin objek yang ukurannya lebih dari 1 GB, Anda harus membagi objek menjadi beberapa bagian dan menyalin bagian-bagian tersebut secara berurutan menggunakan UploadPartCopy. Untuk menerapkan salinan multi-bagian, lakukan langkah-langkah berikut:

    1. Gunakan bucket.init_multipart_upload untuk memulai tugas salinan multi-bagian.

    2. Gunakan bucket.upload_part_copy untuk menyalin bagian-bagian tersebut. Setiap bagian harus berukuran lebih dari 100 KB, kecuali bagian terakhir.

    3. Gunakan bucket.complete_multipart_upload untuk menyelesaikan tugas salinan multi-bagian.

    Kode berikut memberikan contoh cara menggunakan salinan multi-bagian untuk menyalin objek bernama srcexampleobject.txt dari bucket srcexamplebucket ke objek bernama destexampleobject.txt di destexamplebucket:

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import PartInfo
from oss2 import determine_part_size

# Peroleh kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. 
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Tentukan nama bucket sumber. Contoh: srcexamplebucket. 
src_bucket_name = 'srcexamplebucket'
# Tentukan nama bucket tujuan. Bucket tujuan harus berada di wilayah yang sama dengan bucket sumber. Contoh: destexamplebucket. 
# Jika Anda menyalin objek dalam satu bucket, pastikan Anda menentukan nama bucket yang sama untuk bucket sumber dan bucket tujuan.
dest_bucket_name = 'destexamplebucket'

# Tentukan titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur titik akhir menjadi https://oss-cn-hangzhou.aliyuncs.com. 
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Tentukan ID wilayah yang sesuai dengan titik akhir. Contoh: cn-hangzhou. Parameter ini diperlukan jika Anda menggunakan algoritma signature V4.
region = "cn-hangzhou"

# Jika Anda menyalin objek dalam satu bucket, beri komentar pada baris kode ini dan ubah src_bucket menjadi bucket. 
bucket = oss2.Bucket(auth, endpoint, dest_bucket_name, region=region)

src_bucket = oss2.Bucket(auth, endpoint, src_bucket_name, region=region)

# Tentukan path lengkap objek sumber. Jangan sertakan nama bucket dalam path lengkap. Contoh: srcexampleobject.txt. 
src_object_name = 'srcexampleobject.txt'
# Tentukan path lengkap objek tujuan. Jangan sertakan nama bucket dalam path lengkap. Contoh: destexampleobject.txt. 
dest_object_name = 'destexampleobject.txt'
# Peroleh ukuran objek sumber. Jika Anda menyalin objek dalam satu bucket, ubah src_bucket menjadi bucket. 
head_info = src_bucket.head_object(src_object_name)
total_size = head_info.content_length
print('src object size:', total_size)

# Gunakan metode determine_part_size untuk menentukan ukuran bagian. 
part_size = determine_part_size(total_size, preferred_size=100 * 1024)
print('part_size:', part_size)

# Mulai tugas unggah multi-bagian. 
upload_id = bucket.init_multipart_upload(dest_object_name).upload_id
parts = []

# Unggah bagian-bagian tersebut. 
part_number = 1
offset = 0
while offset < total_size:
    num_to_upload = min(part_size, total_size - offset)
    end = offset + num_to_upload - 1
    # headers = dict()
    # Tentukan path objek sumber.     
    # headers[OSS_COPY_OBJECT_SOURCE] = '/example-bucket-by-util/recode-test.txt'
    # Tentukan rentang data yang ingin Anda salin. Misalnya, jika Anda mengatur bytes ke 0~1023, 1024 byte pertama objek sumber akan disalin. 
    # headers[OSS_COPY_OBJECT_SOURCE_RANGE] = 'bytes=0~1023'
    # Jika nilai ETag objek sumber sama dengan nilai ETag yang ditentukan dalam permintaan, OSS akan menyalin objek dan mengembalikan 200 OK. 
    # headers['x-oss-copy-source-if-match'] = '5B3C1A2E053D763E1B002CC6****'
    # Jika nilai ETag objek sumber berbeda dari nilai ETag yang ditentukan dalam permintaan, OSS akan menyalin objek dan mengembalikan 200 OK. 
    # headers['x-oss-copy-source-if-none-match'] = '5B3C1A2E053D763E1B002CC6****'
    # Jika waktu yang ditentukan dalam permintaan sama dengan atau lebih baru daripada waktu modifikasi aktual objek, OSS akan menyalin objek dan mengembalikan 200 OK. 
    # headers['x-oss-copy-source-if-unmodified-since'] = '2021-12-09T07:01:56.000Z'
    # Jika waktu yang ditentukan dalam permintaan lebih awal daripada waktu modifikasi aktual objek, OSS akan menyalin objek dan mengembalikan 200 OK. 
    # headers['x-oss-copy-source-if-modified-since'] = '2021-12-09T07:01:56.000Z'
    # result = bucket.upload_part_copy(src_bucket_name, src_object_name, (offset, end), dest_object_name, upload_id, part_number, headers=headers)
    
    result = bucket.upload_part_copy(src_bucket_name, src_object_name, (offset, end), dest_object_name, upload_id, part_number)
    # Simpan informasi bagian. 
    parts.append(PartInfo(part_number, result.etag))

    offset += num_to_upload
    part_number += 1

# Selesaikan tugas salinan multi-bagian. 
result = bucket.complete_multipart_upload(dest_object_name, upload_id, parts)
# Lihat kode status HTTP dalam respons yang dikembalikan. 
print('result :', result.status)
# Kueri metadata objek. 
head_info = bucket.head_object(dest_object_name)
# Kueri ukuran objek tujuan. 
dest_object_size = head_info.content_length
print('dest object size:', dest_object_size)
# Bandingkan ukuran objek sumber dan objek tujuan. 
assert dest_object_size == total_size

    Referensi

    • Salin objek kecil

      • Untuk kode contoh lengkap yang digunakan untuk menyalin objek kecil, kunjungi GitHub.

      • Untuk informasi selengkapnya mengenai operasi API yang dapat Anda panggil untuk menyalin objek kecil, lihat CopyObject.

    • Salin objek besar

      Untuk informasi selengkapnya mengenai operasi API yang dapat Anda panggil untuk menyalin objek besar, lihat UploadPartCopy.