Cara melakukan unggah multi-bagian menggunakan OSS SDK untuk Python V2 - Object Storage Service

Fitur unggah multi-bagian dari Object Storage Service (OSS) memungkinkan Anda membagi objek besar menjadi beberapa bagian. Setelah bagian-bagian tersebut diunggah, Anda dapat memanggil operasi CompleteMultipartUpload untuk menggabungkan bagian-bagian tersebut menjadi satu objek utuh.

Catatan

Kode contoh dalam topik ini menggunakan wilayah China (Hangzhou) (cn-hangzhou) dan titik akhir publiknya secara default. Jika Anda ingin mengakses OSS dari produk Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk informasi selengkapnya tentang wilayah dan titik akhir yang didukung oleh OSS, lihat Wilayah dan titik akhir.
Untuk melakukan unggah multi-bagian, Anda harus memiliki izin oss:PutObject. Untuk informasi selengkapnya, lihat Memberikan izin kustom kepada RAM user.

Proses unggah multi-bagian

Unggah multi-bagian terdiri dari tiga langkah berikut:

Inisialisasi event unggah multi-bagian.

Panggil metode Client.InitiateMultipartUpload untuk mendapatkan ID unggahan yang unik secara global dari OSS.
Unggah bagian-bagian.

Panggil metode Client.UploadPart untuk mengunggah data bagian.
Catatan
- Untuk ID unggahan yang sama, nomor bagian mengidentifikasi bagian tersebut dan posisi relatifnya dalam objek lengkap. Jika Anda mengunggah bagian baru dengan nomor bagian yang sudah ada, bagian yang ada di OSS akan ditimpa.
- OSS menyertakan hash MD5 dari data bagian yang diterima dalam header ETag pada respons.
- OSS menghitung hash MD5 dari data yang diunggah dan membandingkannya dengan hash MD5 yang dihitung oleh kit pengembangan perangkat lunak (SDK). Jika kedua hash MD5 berbeda, kode kesalahan InvalidDigest dikembalikan.
Selesaikan unggah multi-bagian.

Setelah semua bagian diunggah, Anda dapat memanggil metode Client.CompleteMultipartUpload untuk menggabungkan semua bagian menjadi satu objek utuh.

Kode contoh

Kode contoh berikut menunjukkan cara membagi file lokal besar menjadi beberapa bagian, mengunggah bagian-bagian tersebut secara konkuren ke bucket, lalu menggabungkannya menjadi satu objek utuh.

import os
import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen command line untuk contoh unggah multi-bagian.
parser = argparse.ArgumentParser(description="multipart upload sample")

# Tambahkan argumen command line wajib --region, yang menentukan wilayah tempat bucket berada.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)

# Tambahkan argumen command line wajib --bucket, yang menentukan nama bucket.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)

# Tambahkan argumen command line opsional --endpoint, yang menentukan nama domain yang dapat digunakan layanan lain untuk mengakses OSS.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

# Tambahkan argumen command line wajib --key, yang menentukan nama objek.
parser.add_argument('--key', help='The name of the object.', required=True)

# Tambahkan argumen command line wajib --file_path, yang menentukan path file yang akan diunggah.
parser.add_argument('--file_path', help='The path of Upload file.', required=True)


def main():
    # Uraikan argumen command line.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region

    # Jika endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

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

    # Inisiasi permintaan unggah multi-bagian untuk mendapatkan ID unggahan guna unggahan bagian selanjutnya.
    result = client.initiate_multipart_upload(oss.InitiateMultipartUploadRequest(
        bucket=args.bucket,
        key=args.key,
    ))

    # Tentukan ukuran setiap bagian sebesar 5 MB.
    part_size = 5 * 1024 * 1024

    # Dapatkan ukuran total file yang akan diunggah.
    data_size = os.path.getsize(args.file_path)

    # Inisialisasi nomor bagian, dimulai dari 1.
    part_number = 1

    # Simpan hasil unggahan setiap bagian.
    upload_parts = []

    # Buka file dalam mode baca biner.
    with open(args.file_path, 'rb') as f:
        # Telusuri file dan unggah secara bertahap berdasarkan part_size.
        for start in range(0, data_size, part_size):
            n = part_size
            if start + n > data_size:  # Tangani kasus di mana bagian terakhir mungkin lebih kecil dari part_size.
                n = data_size - start

            # Buat SectionReader untuk membaca bagian tertentu dari file.
            reader = oss.io_utils.SectionReader(oss.io_utils.ReadAtReader(f), start, n)

            # Unggah bagian tersebut.
            up_result = client.upload_part(oss.UploadPartRequest(
                bucket=args.bucket,
                key=args.key,
                upload_id=result.upload_id,
                part_number=part_number,
                body=reader
            ))

            # Cetak hasil unggahan setiap bagian.
            print(f'status code: {up_result.status_code},'
                  f' request id: {up_result.request_id},'
                  f' part number: {part_number},'
                  f' content md5: {up_result.content_md5},'
                  f' etag: {up_result.etag},'
                  f' hash crc64: {up_result.hash_crc64},'
                  )

            # Simpan hasil unggahan bagian ke dalam daftar.
            upload_parts.append(oss.UploadPart(part_number=part_number, etag=up_result.etag))

            # Tambahkan nomor bagian.
            part_number += 1

    # Urutkan bagian yang diunggah berdasarkan nomor bagian.
    parts = sorted(upload_parts, key=lambda p: p.part_number)

    # Kirim permintaan untuk menyelesaikan unggah multi-bagian dan menggabungkan semua bagian menjadi satu objek utuh.
    result = client.complete_multipart_upload(oss.CompleteMultipartUploadRequest(
        bucket=args.bucket,
        key=args.key,
        upload_id=result.upload_id,
        complete_multipart_upload=oss.CompleteMultipartUpload(
            parts=parts
        )
    ))

    # Kode berikut menyediakan metode alternatif untuk mencantumkan dan menggabungkan semua data bagian menjadi satu objek utuh di sisi server.
    # Metode ini cocok jika Anda tidak yakin apakah semua bagian berhasil diunggah.
    # Gabungkan data terfragmentasi menjadi Objek utuh melalui metode List di sisi server
    # result = client.complete_multipart_upload(oss.CompleteMultipartUploadRequest(
    #     bucket=args.bucket,
    #     key=args.key,
    #     upload_id=result.upload_id,
    #     complete_all='yes'
    # ))

    # Cetak hasil unggah multi-bagian yang telah selesai.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' bucket: {result.bucket},'
          f' key: {result.key},'
          f' location: {result.location},'
          f' etag: {result.etag},'
          f' encoding type: {result.encoding_type},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Titik masuk skrip. Fungsi main dipanggil saat file dijalankan secara langsung.

Skenario umum

Lakukan unggah multi-bagian dan atur callback unggahan

Jika Anda ingin memberi notifikasi ke server aplikasi setelah unggah multi-bagian selesai, lihat kode contoh berikut.

import os
import argparse
import base64
import alibabacloud_oss_v2 as oss

# Buat parser argumen command line untuk contoh unggah multi-bagian.
parser = argparse.ArgumentParser(description="multipart upload sample")

# Tambahkan argumen command line wajib --region, yang menentukan wilayah tempat bucket berada.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)

# Tambahkan argumen command line wajib --bucket, yang menentukan nama bucket.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)

# Tambahkan argumen command line opsional --endpoint, yang menentukan nama domain yang dapat digunakan layanan lain untuk mengakses OSS.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

# Tambahkan argumen command line wajib --key, yang menentukan nama objek.
parser.add_argument('--key', help='The name of the object.', required=True)

# Tambahkan argumen command line wajib --file_path, yang menentukan path file yang akan diunggah.
parser.add_argument('--file_path', help='The path of Upload file.', required=True)


def main():
    # Uraikan argumen command line.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region

    # Jika endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

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

    # Inisiasi permintaan unggah multi-bagian untuk mendapatkan ID unggahan guna unggahan bagian selanjutnya.
    result = client.initiate_multipart_upload(oss.InitiateMultipartUploadRequest(
        bucket=args.bucket,
        key=args.key,
    ))

    # Tentukan ukuran setiap bagian sebesar 1 MB.
    part_size = 1 * 1024 * 1024

    # Dapatkan ukuran total file yang akan diunggah.
    data_size = os.path.getsize(args.file_path)

    # Inisialisasi nomor bagian, dimulai dari 1.
    part_number = 1

    # Simpan hasil unggahan setiap bagian.
    upload_parts = []

    # Buka file dalam mode baca biner.
    with open(args.file_path, 'rb') as f:
        # Telusuri file dan unggah secara bertahap berdasarkan part_size.
        for start in range(0, data_size, part_size):
            n = part_size
            if start + n > data_size:  # Tangani kasus di mana bagian terakhir mungkin lebih kecil dari part_size.
                n = data_size - start

            # Buat SectionReader untuk membaca bagian tertentu dari file.
            reader = oss.io_utils.SectionReader(oss.io_utils.ReadAtReader(f), start, n)

            # Unggah bagian tersebut.
            up_result = client.upload_part(oss.UploadPartRequest(
                bucket=args.bucket,
                key=args.key,
                upload_id=result.upload_id,
                part_number=part_number,
                body=reader
            ))

            # Cetak hasil unggahan setiap bagian.
            print(f'status code: {up_result.status_code},'
                  f' request id: {up_result.request_id},'
                  f' part number: {part_number},'
                  f' content md5: {up_result.content_md5},'
                  f' etag: {up_result.etag},'
                  f' hash crc64: {up_result.hash_crc64},'
                  )

            # Simpan hasil unggahan bagian ke dalam daftar.
            upload_parts.append(oss.UploadPart(part_number=part_number, etag=up_result.etag))

            # Tambahkan nomor bagian.
            part_number += 1

    # Urutkan bagian yang diunggah berdasarkan nomor bagian.
    parts = sorted(upload_parts, key=lambda p: p.part_number)

    # Tentukan alamat webhook.
    call_back_url = "http://www.example.com/callback"
    # Buat parameter callback: tentukan alamat webhook dan badan permintaan, lalu encode dalam Base64.
    callback=base64.b64encode(str('{\"callbackUrl\":\"' + call_back_url + '\",\"callbackBody\":\"bucket=${bucket}&object=${object}&my_var_1=${x:var1}&my_var_2=${x:var2}\"}').encode()).decode()
    # Buat variabel kustom (callback-var) dan encode dalam Base64.
    callback_var=base64.b64encode('{\"x:var1\":\"value1\",\"x:var2\":\"value2\"}'.encode()).decode()

    # Kirim permintaan untuk menyelesaikan unggah multi-bagian dan menggabungkan semua bagian menjadi satu objek utuh.
    result = client.complete_multipart_upload(oss.CompleteMultipartUploadRequest(
        bucket=args.bucket,
        key=args.key,
        upload_id=result.upload_id,
        complete_multipart_upload=oss.CompleteMultipartUpload(
            parts=parts
        ),
        callback=callback,
        callback_var=callback_var
    ))

    # Kode berikut menyediakan metode alternatif untuk mencantumkan dan menggabungkan semua data bagian menjadi satu objek utuh di sisi server.
    # Metode ini cocok jika Anda tidak yakin apakah semua bagian berhasil diunggah.
    # Gabungkan data terfragmentasi menjadi Objek utuh melalui metode List di sisi server
    # result = client.complete_multipart_upload(oss.CompleteMultipartUploadRequest(
    #     bucket=args.bucket,
    #     key=args.key,
    #     upload_id=result.upload_id,
    #     complete_all='yes'
    # ))

    # Cetak hasil unggah multi-bagian yang telah selesai.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' bucket: {result.bucket},'
          f' key: {result.key},'
          f' location: {result.location},'
          f' etag: {result.etag},'
          f' encoding type: {result.encoding_type},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Titik masuk skrip. Fungsi main dipanggil saat file dijalankan secara langsung.

Tampilkan bilah progres untuk unggah multi-bagian

import os
import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen command line untuk contoh unggah multi-bagian.
parser = argparse.ArgumentParser(description="multipart upload sample")

# Tambahkan argumen command line wajib --region, yang menentukan wilayah tempat bucket berada.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)

# Tambahkan argumen command line wajib --bucket, yang menentukan nama bucket.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)

# Tambahkan argumen command line opsional --endpoint, yang menentukan nama domain yang dapat digunakan layanan lain untuk mengakses OSS.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

# Tambahkan argumen command line wajib --key, yang menentukan nama objek.
parser.add_argument('--key', help='The name of the object.', required=True)

# Tambahkan argumen command line wajib --file_path, yang menentukan path file yang akan diunggah.
parser.add_argument('--file_path', help='The path of Upload file.', required=True)

def main():
    # Uraikan argumen command line.
    args = parser.parse_args()

    # Muat kredensial dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default SDK dan atur penyedia kredensial.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Atur wilayah dalam konfigurasi.
    cfg.region = args.region

    # Jika endpoint disediakan, atur endpoint dalam konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

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

    # Tentukan variabel dictionary bernama progress_state untuk menyimpan progres unggahan. Nilai awal adalah 0.
    progress_state = {'saved': 0}
    def _progress_fn(n, written, total):
        # Gunakan dictionary untuk menyimpan jumlah byte yang telah ditulis guna menghindari penggunaan variabel global.
        progress_state['saved'] += n

        # Hitung persentase unggahan saat ini. Bagi jumlah byte yang telah ditulis dengan jumlah total byte dan bulatkan ke bawah.
        rate = int(100 * (float(written) / float(total)))

        # Cetak progres unggahan saat ini. \r mengembalikan kursor ke awal baris agar pembaruan real-time di command line berfungsi.
        # end='' mencegah pembuatan baris baru, sehingga print berikutnya dapat menimpa baris saat ini.
        print(f'\rUpload progress: {rate}% ', end='')

    # Inisiasi permintaan unggah multi-bagian untuk mendapatkan ID unggahan guna unggahan bagian selanjutnya.
    result = client.initiate_multipart_upload(oss.InitiateMultipartUploadRequest(
        bucket=args.bucket,
        key=args.key,
    ))

    # Tentukan ukuran setiap bagian sebesar 5 MB.
    part_size = 5 * 1024 * 1024

    # Dapatkan ukuran total file yang akan diunggah.
    data_size = os.path.getsize(args.file_path)

    # Inisialisasi nomor bagian, dimulai dari 1.
    part_number = 1

    # Simpan hasil unggahan setiap bagian.
    upload_parts = []

    # Buka file dalam mode baca biner.
    with open(args.file_path, 'rb') as f:
        # Telusuri file dan unggah secara bertahap berdasarkan part_size.
        for start in range(0, data_size, part_size):
            n = part_size
            if start + n > data_size:  # Tangani kasus di mana bagian terakhir mungkin lebih kecil dari part_size.
                n = data_size - start

            # Buat SectionReader untuk membaca bagian tertentu dari file.
            reader = oss.io_utils.SectionReader(oss.io_utils.ReadAtReader(f), start, n)

            # Unggah bagian tersebut.
            up_result = client.upload_part(oss.UploadPartRequest(
                bucket=args.bucket,
                key=args.key,
                upload_id=result.upload_id,
                part_number=part_number,
                body=reader,
                progress_fn=_progress_fn
            ))

            # Cetak hasil unggahan setiap bagian.
            print(f'status code: {up_result.status_code},'
                  f' request id: {up_result.request_id},'
                  f' part number: {part_number},'
                  f' content md5: {up_result.content_md5},'
                  f' etag: {up_result.etag},'
                  f' hash crc64: {up_result.hash_crc64},'
                  )

            # Simpan hasil unggahan bagian ke dalam daftar.
            upload_parts.append(oss.UploadPart(part_number=part_number, etag=up_result.etag))

            # Tambahkan nomor bagian.
            part_number += 1

    # Urutkan bagian yang diunggah berdasarkan nomor bagian.
    parts = sorted(upload_parts, key=lambda p: p.part_number)

    # Kirim permintaan untuk menyelesaikan unggah multi-bagian dan menggabungkan semua bagian menjadi satu objek utuh.
    result = client.complete_multipart_upload(oss.CompleteMultipartUploadRequest(
        bucket=args.bucket,
        key=args.key,
        upload_id=result.upload_id,
        complete_multipart_upload=oss.CompleteMultipartUpload(
            parts=parts
        )
    ))

    # Kode berikut menyediakan metode alternatif untuk mencantumkan dan menggabungkan semua data bagian menjadi satu objek utuh di sisi server.
    # Metode ini cocok jika Anda tidak yakin apakah semua bagian berhasil diunggah.
    # Gabungkan data terfragmentasi menjadi Objek utuh melalui metode List di sisi server
    # result = client.complete_multipart_upload(oss.CompleteMultipartUploadRequest(
    #     bucket=args.bucket,
    #     key=args.key,
    #     upload_id=result.upload_id,
    #     complete_all='yes'
    # ))

    # Cetak hasil unggah multi-bagian yang telah selesai.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' bucket: {result.bucket},'
          f' key: {result.key},'
          f' location: {result.location},'
          f' etag: {result.etag},'
          f' encoding type: {result.encoding_type},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Titik masuk skrip. Fungsi main dipanggil saat file dijalankan secara langsung.

Referensi

Untuk kode contoh lengkap unggah multi-bagian, lihat complete_multipart_upload.py.