Salin objek menggunakan OSS SDK untuk Python 2.0 - Object Storage Service

Topik ini menjelaskan cara menggunakan modul Copier dari OSS SDK untuk Python V2 untuk menyalin file, terutama untuk transfer file besar.

Catatan

Kode contoh dalam topik ini menggunakan ID wilayah cn-hangzhou untuk Wilayah Tiongkok (Hangzhou). Titik akhir publik digunakan secara default. Jika Anda mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk informasi lebih lanjut tentang pemetaan antara wilayah OSS dan titik akhir, lihat Wilayah dan Titik Akhir.
Untuk menyalin objek, Anda harus memiliki izin baca pada objek sumber serta izin baca dan tulis pada bucket tujuan.
Penyalinan lintas wilayah tidak didukung. Sebagai contoh, Anda tidak dapat menyalin objek dari bucket di Wilayah Tiongkok (Hangzhou) ke bucket di Wilayah Tiongkok (Qingdao).
Saat menyalin objek, pastikan tidak ada kebijakan retensi yang dikonfigurasi untuk bucket sumber dan tujuan. Jika tidak, kesalahan Objek yang Anda tentukan tidak dapat diubah. akan dikembalikan.

Definisi metode

Pengenalan pengelola salinan

Untuk menyalin objek dari satu bucket ke bucket lain atau memodifikasi properti objek, Anda dapat menggunakan operasi salinan atau operasi salinan multipart. Setiap operasi cocok untuk skenario yang berbeda:

Operasi salinan (CopyObject) hanya cocok untuk menyalin objek yang lebih kecil dari 5 GiB.
Operasi salinan multipart (UploadPartCopy) mendukung penyalinan objek yang lebih besar dari 5 GiB. Namun, operasi ini tidak mendukung parameter (x-oss-metadata-directive) atau (x-oss-tagging-directive). Saat menggunakan operasi ini, Anda harus menentukan metadata dan tag yang ingin disalin.

Pengelola Salinan Copier adalah fitur baru di OSS SDK untuk Python V2 yang menyediakan antarmuka salinan universal. Antarmuka ini mengabstraksi detail implementasi tingkat rendah dan secara otomatis memilih operasi salinan yang sesuai berdasarkan parameter permintaan. Kode berikut menunjukkan metode umum dari Copier:

class CopyError(exceptions.BaseError):
  ...

def copier(self, **kwargs) -> Copier:
  ...

def copy(self, request: models.CopyObjectRequest, **kwargs: Any) -> CopyResult:
  ...

Parameter permintaan

Parameter	Tipe	Deskripsi
request	CopyObjectRequest	Parameter permintaan operasi. Untuk informasi lebih lanjut, lihat CopyObjectRequest.
**kwargs	Any	(Opsional) Parameter apa pun dengan tipe kamus.

Tabel berikut menjelaskan parameter umum dari CopyObjectRequest.

Parameter	Tipe	Deskripsi
bucket	str	Nama bucket tujuan.
key	str	Nama objek tujuan.
source_bucket	str	Nama bucket sumber.
source_key	str	Nama objek sumber.
forbid_overwrite	str	Menentukan apakah akan menimpa objek tujuan dengan nama yang sama selama operasi CopyObject.
tagging	str	Tag objek. Anda dapat menentukan beberapa tag sekaligus. Contoh: TagA=A&TagB=B.
tagging_directive	str	Menentukan cara menetapkan tag untuk objek tujuan. Nilai valid: Copy (default): menyalin tag objek sumber ke objek tujuan. Replace: mengabaikan tag objek sumber dan menggunakan tag yang ditentukan dalam permintaan untuk objek tujuan.

Anda dapat menyesuaikan perilaku salinan objek dengan menentukan opsi konfigurasi saat menginisialisasi instance pengelola salinan menggunakan client.copier. Anda juga dapat menentukan opsi konfigurasi untuk setiap panggilan salinan untuk menyesuaikan perilaku untuk objek tertentu.

Tetapkan parameter konfigurasi untuk Copier

copier = client.copier(
    part_size=100 * 1024 * 1024,
)

Tetapkan parameter konfigurasi untuk setiap permintaan salinan

result = copier.copy(oss.CopyObjectRequest(
        bucket="example_bucket",
        key="example_key",
        source_bucket="example_source_bucket",
        source_key="example_source_key",
    ),
    part_size=100 * 1024 * 1024,
)

Tabel berikut menjelaskan opsi konfigurasi umum.

Parameter	Tipe	Deskripsi
part_size	int	Ukuran bagian. Nilai default adalah 64 MiB.
parallel_num	int	Jumlah tugas salinan konkuren. Nilai default: 3. Parameter ini menentukan batas konkurensi untuk satu panggilan, bukan batas konkurensi global.
multipart_copy_threshold	int64	Ambang batas untuk salinan multipart. Nilai default adalah 200 MiB.
leave_parts_on_error	bool	Menentukan apakah akan mempertahankan bagian yang disalin jika salinan gagal. Secara default, bagian yang disalin tidak dipertahankan.
disable_shallow_copy	bool	Menentukan apakah akan menonaktifkan salinan dangkal. Secara default, salinan dangkal digunakan.

Kode contoh

Kode contoh berikut menunjukkan cara menyalin objek dari bucket sumber ke bucket tujuan.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="copier sample")

# Tambahkan parameter baris perintah: region (wajib), yang menentukan wilayah tempat bucket berada.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# Tambahkan parameter baris perintah: bucket (wajib), yang menentukan nama bucket tujuan.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# Tambahkan parameter baris perintah: endpoint (opsional), yang menentukan titik akhir untuk mengakses OSS.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')

# Tambahkan parameter baris perintah: key (wajib), yang menentukan nama objek tujuan.
parser.add_argument('--key', help='Nama objek.', required=True)

# Tambahkan parameter baris perintah: source_key (wajib), yang menentukan nama objek sumber.
parser.add_argument('--source_key', help='Nama alamat sumber untuk objek.', required=True)

# Tambahkan parameter baris perintah: source_bucket (wajib), yang menentukan nama bucket sumber.
parser.add_argument('--source_bucket', help='Nama alamat sumber untuk bucket.', required=True)


def main():
    # Parsing argumen baris perintah.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan.
    # Gunakan EnvironmentVariableCredentialsProvider untuk membaca ID AccessKey dan Rahasia AccessKey dari variabel lingkungan.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default dari SDK.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider  # Tetapkan penyedia kredensial.
    cfg.region = args.region  # Tetapkan wilayah tempat bucket berada.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint  # Jika titik akhir diberikan, tetapkan titik akhir kustom.

    # Buat instance klien OSS.
    client = oss.Client(cfg)

    # Buat instance Copier dan lakukan operasi salinan objek.
    copier = client.copier()

    # Lakukan operasi salinan objek.
    result = copier.copy(
        oss.CopyObjectRequest(
            bucket=args.bucket,          # Nama bucket tujuan.
            key=args.key,                # Nama objek tujuan.
            source_bucket=args.source_bucket,  # Nama bucket sumber.
            source_key=args.source_key   # Nama objek sumber.
        )
    )

    # Cetak hasil salinan.
    # Gunakan vars(result) untuk mengonversi objek hasil ke format kamus dan cetak hasilnya.
    print(vars(result))


if __name__ == "__main__":
    main()

Skenario

Gunakan pengelola salinan untuk menetapkan ukuran bagian dan konkurensi

Kode contoh berikut menunjukkan cara mengonfigurasi parameter pengelola salinan untuk menetapkan ukuran bagian dan konkurensi.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="copier sample")

# Tambahkan parameter baris perintah: region (wajib), yang menentukan wilayah tempat bucket berada.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# Tambahkan parameter baris perintah: bucket (wajib), yang menentukan nama bucket tujuan.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# Tambahkan parameter baris perintah: endpoint (opsional), yang menentukan titik akhir untuk mengakses OSS.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')

# Tambahkan parameter baris perintah: key (wajib), yang menentukan nama objek tujuan.
parser.add_argument('--key', help='Nama objek.', required=True)

# Tambahkan parameter baris perintah: source_key (wajib), yang menentukan nama objek sumber.
parser.add_argument('--source_key', help='Nama alamat sumber untuk objek.', required=True)

# Tambahkan parameter baris perintah: source_bucket (wajib), yang menentukan nama bucket sumber.
parser.add_argument('--source_bucket', help='Nama alamat sumber untuk bucket.', required=True)


def main():
    # Parsing argumen baris perintah.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan.
    # Gunakan EnvironmentVariableCredentialsProvider untuk membaca ID AccessKey dan Rahasia AccessKey dari variabel lingkungan.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default dari SDK.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider  # Tetapkan penyedia kredensial.
    cfg.region = args.region  # Tetapkan wilayah tempat bucket berada.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint  # Jika titik akhir diberikan, tetapkan titik akhir kustom.

    # Buat instance klien OSS.
    client = oss.Client(cfg)

    # Buat instance Copier dan lakukan operasi salinan objek.
    copier = client.copier()

    # Lakukan operasi salinan objek.
    result = copier.copy(
        oss.CopyObjectRequest(
            bucket=args.bucket,          # Nama bucket tujuan.
            key=args.key,                # Nama objek tujuan.
            source_bucket=args.source_bucket,  # Nama bucket sumber.
            source_key=args.source_key   # Nama objek sumber.
        ),
        part_size= 1 * 1024 * 1024,          # Ukuran bagian dalam byte. Dalam contoh ini, ukuran bagian diatur menjadi 1 MiB.
        parallel_num=5,                 # Jumlah tugas konkuren. Parameter ini menentukan jumlah bagian yang dapat disalin pada saat yang sama.
        leave_parts_on_error=True,      # Jika salinan gagal, pertahankan bagian yang telah disalin.
    )

    # Cetak hasil salinan.
    # Gunakan vars(result) untuk mengonversi objek hasil ke format kamus dan cetak hasilnya.
    print(vars(result))


if __name__ == "__main__":
    main()

Gunakan pengelola salinan untuk menampilkan grafik bilah kemajuan

Kode contoh berikut menunjukkan cara menggunakan grafik bilah kemajuan untuk melihat kemajuan salinan.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah.
parser = argparse.ArgumentParser(description="copier sample")

# Tambahkan parameter baris perintah: region (wajib), yang menentukan wilayah tempat bucket berada.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)

# Tambahkan parameter baris perintah: bucket (wajib), yang menentukan nama bucket tujuan.
parser.add_argument('--bucket', help='Nama bucket.', required=True)

# Tambahkan parameter baris perintah: endpoint (opsional), yang menentukan titik akhir untuk mengakses OSS.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')

# Tambahkan parameter baris perintah: key (wajib), yang menentukan nama objek tujuan.
parser.add_argument('--key', help='Nama objek.', required=True)

# Tambahkan parameter baris perintah: source_key (wajib), yang menentukan nama objek sumber.
parser.add_argument('--source_key', help='Nama alamat sumber untuk objek.', required=True)

# Tambahkan parameter baris perintah: source_bucket (wajib), yang menentukan nama bucket sumber.
parser.add_argument('--source_bucket', help='Nama alamat sumber untuk bucket.', required=True)


def main():
    # Parsing argumen baris perintah.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan.
    # Gunakan EnvironmentVariableCredentialsProvider untuk membaca ID AccessKey dan Rahasia AccessKey dari variabel lingkungan.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default dari SDK.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider  # Tetapkan penyedia kredensial.
    cfg.region = args.region  # Tetapkan wilayah tempat bucket berada.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint  # Jika titik akhir diberikan, tetapkan titik akhir kustom.

    # Buat instance klien OSS.
    client = oss.Client(cfg)

    # Definisikan variabel kamus bernama progress_state untuk menyimpan kemajuan salinan. Nilai awal adalah 0.
    progress_state = {'saved': 0}
    def _progress_fn(n, written, total):
        # Gunakan kamus untuk menyimpan jumlah byte yang ditulis secara kumulatif untuk menghindari penggunaan variabel global.
        progress_state['saved'] += n

        # Hitung persentase salinan saat ini. Nilainya diperoleh dengan membagi jumlah byte yang ditulis dengan jumlah total byte dan membulatkan hasilnya ke bawah.
        rate = int(100 * (float(written) / float(total)))

        # Cetak kemajuan salinan saat ini. \r menunjukkan kembali ke awal baris untuk menerapkan refresh real-time di baris perintah.
        # end='' menunjukkan tidak ada baris baru, yang memungkinkan cetakan berikutnya menimpa baris saat ini.
        print(f'\rKemajuan salinan: {rate}% ', end='')

    # Buat instance Copier dan lakukan operasi salinan objek.
    copier = client.copier()

    # Lakukan operasi salinan objek.
    result = copier.copy(
        oss.CopyObjectRequest(
            bucket=args.bucket,          # Nama bucket tujuan.
            key=args.key,                # Nama objek tujuan.
            source_bucket=args.source_bucket,  # Nama bucket sumber.
            source_key=args.source_key,   # Nama objek sumber.
            progress_fn=_progress_fn,   # Tetapkan fungsi callback kemajuan.
        )
    )

    # Cetak hasil salinan.
    # Gunakan vars(result) untuk mengonversi objek hasil ke format kamus dan cetak hasilnya.
    print(vars(result))


if __name__ == "__main__":
    main()

Referensi

Untuk informasi lebih lanjut tentang pengelola salinan, lihat Panduan Pengembang.
Untuk kode contoh lengkap pengelola salinan, lihat copier.py.