全部产品
Search

搜索本产品

    Object Storage Service：Unggah multi-bagian menggunakan OSS SDK untuk Python 1.0

    文档中心

    Object Storage Service：Unggah multi-bagian menggunakan OSS SDK untuk Python 1.0

    更新时间：Aug 12, 2025

    Saat mengunggah objek besar lebih dari 5 GB ke Layanan Penyimpanan Objek (OSS), Anda mungkin mengalami kegagalan karena gangguan jaringan atau kerusakan program. Jika pengunggahan gagal setelah beberapa percobaan, Anda dapat menggunakan metode unggah multi-bagian. Bagi objek menjadi beberapa bagian dan unggah secara paralel untuk mempercepat proses. Setelah semua bagian diunggah, panggil operasi CompleteMultipartUpload untuk menggabungkan bagian-bagian tersebut menjadi satu objek lengkap.

    Catatan Penggunaan

    • Dalam topik ini, titik akhir publik wilayah Tiongkok (Hangzhou) digunakan. Untuk akses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Informasi lebih lanjut tentang wilayah dan titik akhir OSS dapat ditemukan di Wilayah dan Titik Akhir.

    • Kredensial akses dalam topik ini diperoleh dari variabel lingkungan. Untuk konfigurasi kredensial akses, lihat Konfigurasikan Kredensial Akses (Python SDK V1).

    • Instans OSSClient dibuat menggunakan titik akhir OSS. Untuk pembuatan instans dengan nama domain kustom atau Layanan Token Keamanan (STS), lihat Inisialisasi (Python SDK V1).

    • Untuk menyelesaikan alur kerja unggah multi-bagian, termasuk InitiateMultipartUpload, UploadPart, dan CompleteMultipartUpload, Anda memerlukan izin oss:PutObject. Detail lebih lanjut tersedia di Lampirkan Kebijakan Kustom ke Pengguna RAM.

    Proses

    Langkah-langkah untuk melaksanakan unggah multi-bagian adalah sebagai berikut:

    1. Mulai tugas unggah multi-bagian.

      Gunakan metode bucket.init_multipart_upload untuk mendapatkan ID unggah unik di OSS.

    2. Unggah bagian-bagian.

      Gunakan metode bucket.upload_part untuk mengunggah bagian-bagian tersebut.

      Catatan

      • Nomor bagian digunakan untuk mengidentifikasi posisi relatif bagian dalam objek. Jika nomor bagiannya digunakan untuk mengunggah bagian lain, bagian terakhir akan menimpa bagian sebelumnya.

      • OSS menyertakan Hash MD5 dari setiap bagian yang diunggah dalam header ETag pada tanggapan.

      • OSS menghitung Hash MD5 dari bagian yang diunggah dan membandingkannya dengan Hash MD5 yang dihitung oleh OSS SDK untuk Go. Jika hash berbeda, OSS mengembalikan kode kesalahan InvalidDigest.

    3. Selesaikan tugas unggah multi-bagian.

      Setelah semua bagian diunggah, gunakan metode bucket.complete_multipart_upload untuk menggabungkan bagian-bagian menjadi satu objek lengkap.

    Contoh

    Setelah semua bagian diunggah, Anda dapat menggabungkan bagian-bagian tersebut menjadi satu objek lengkap menggunakan salah satu metode berikut:

    • Gabungkan semua bagian menjadi satu objek lengkap dengan menyertakan informasi bagian dalam badan permintaan.

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

# Dapatkan 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 titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke 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 tanda tangan V4.
region = "cn-hangzhou"

# Tentukan nama bucket Anda.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Tentukan jalur lengkap objek. Jangan sertakan nama bucket dalam jalur lengkap. Contoh: exampledir/exampleobject.txt.
key = 'exampledir/exampleobject.txt'
# Tentukan jalur lengkap file lokal yang ingin Anda unggah. Contoh: D:\\localpath\\examplefile.txt.
filename = 'D:\\localpath\\examplefile.txt'

total_size = os.path.getsize(filename)
# Gunakan metode determine_part_size untuk menentukan ukuran bagian. Ukuran bagian minimum adalah 100 KB dan maksimum adalah 5 GB. Bagian terakhir bisa lebih kecil dari 100 KB. Dalam contoh ini, ukuran bagian diatur ke 1 MB.
part_size = determine_part_size(total_size, preferred_size=1 * 1024 * 1024)

# Mulai tugas unggah multi-bagian.
# Jika Anda ingin menentukan kelas penyimpanan objek saat memulai tugas unggah multi-bagian, konfigurasikan header terkait saat menggunakan metode init_multipart_upload.
# headers = dict()
# Tentukan perilaku caching halaman web untuk objek.
# headers['Cache-Control'] = 'no-cache'
# Tentukan nama objek saat diunduh.
# headers['Content-Disposition'] = 'oss_MultipartUpload.txt'
# Tentukan periode validitas. Satuan: milidetik.
# headers['Expires'] = '1000'
# Tentukan apakah objek yang diunggah dengan melakukan unggah multi-bagian menimpa objek yang ada dengan nama yang sama saat tugas unggah multi-bagian dimulai. Dalam contoh ini, parameter ini diatur ke true, yang menunjukkan bahwa objek dengan nama yang sama tidak dapat ditimpa.
# headers['x-oss-forbid-overwrite'] = 'true'
# Tentukan metode enkripsi sisi server yang ingin Anda gunakan untuk mengenkripsi setiap bagian.
# headers[OSS_SERVER_SIDE_ENCRYPTION] = SERVER_SIDE_ENCRYPTION_KMS
# Tentukan algoritma yang ingin Anda gunakan untuk mengenkripsi objek. Jika Anda tidak mengonfigurasi parameter ini, objek dienkripsi menggunakan AES-256.
# headers[OSS_SERVER_SIDE_DATA_ENCRYPTION] = SERVER_SIDE_ENCRYPTION_KMS
# Tentukan ID Customer Master Key (CMK) yang dikelola oleh Key Management Service (KMS).
# headers[OSS_SERVER_SIDE_ENCRYPTION_KEY_ID] = '9468da86-3509-4f8d-a61e-6eab1eac****'
# Tentukan kelas penyimpanan objek.
# headers['x-oss-storage-class'] = oss2.BUCKET_STORAGE_CLASS_STANDARD
# Tentukan tag untuk objek. Anda dapat menentukan beberapa tag untuk objek pada saat yang sama.
# headers[OSS_OBJECT_TAGGING] = 'k1=v1&k2=v2&k3=v3'
# upload_id = bucket.init_multipart_upload(key, headers=headers).upload_id
upload_id = bucket.init_multipart_upload(key).upload_id
# Batalkan tugas unggah multi-bagian atau daftar bagian yang diunggah berdasarkan ID unggah.
# Jika Anda ingin membatalkan tugas unggah multi-bagian berdasarkan ID unggah, dapatkan ID unggah setelah Anda memanggil operasi InitiateMultipartUpload untuk memulai tugas unggah multi-bagian.
# Jika Anda ingin mencantumkan bagian yang diunggah dalam tugas unggah multi-bagian berdasarkan ID unggah, dapatkan ID unggah setelah Anda memanggil operasi InitiateMultipartUpload untuk memulai tugas unggah multi-bagian tetapi sebelum Anda memanggil operasi CompleteMultipartUpload untuk menyelesaikan tugas unggah multi-bagian.
# print("UploadID:", upload_id)
parts = []

# Unggah bagian-bagian.
with open(filename, 'rb') as fileobj:
    part_number = 1
    offset = 0
    while offset < total_size:
        num_to_upload = min(part_size, total_size - offset)
        # Gunakan metode SizedFileAdapter(fileobj, size) untuk menghasilkan objek baru dan menghitung ulang posisi dari mana operasi tambah dimulai.
        result = bucket.upload_part(key, upload_id, part_number,
                                    SizedFileAdapter(fileobj, num_to_upload))
        parts.append(PartInfo(part_number, result.etag))

        offset += num_to_upload
        part_number += 1

# Selesaikan tugas unggah multi-bagian.
# Konfigurasikan header (jika Anda mau) saat menyelesaikan tugas unggah multi-bagian.
headers = dict()
# Tentukan daftar kontrol akses (ACL) objek. Dalam contoh ini, ACL diatur ke OBJECT_ACL_PRIVATE, yang menunjukkan bahwa ACL objek bersifat pribadi.
# headers["x-oss-object-acl"] = oss2.OBJECT_ACL_PRIVATE
bucket.complete_multipart_upload(key, upload_id, parts, headers=headers)
# bucket.complete_multipart_upload(key, upload_id, parts)
      Penting

      Disarankan untuk meningkatkan ukuran setiap bagian saat kondisi jaringan stabil. Jika tidak, kurangi ukuran setiap bagian.

    • Gabungkan bagian menjadi objek lengkap dengan mencantumkan bagian di server.

      Catatan

      Pastikan beberapa bagian telah diunggah menggunakan ID unggah yang ditentukan dalam kode contoh berikut.

      # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Dapatkan 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 titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke 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 tanda tangan V4.
region = "cn-hangzhou"

# Tentukan nama bucket Anda.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Tentukan jalur lengkap objek. Jangan sertakan nama bucket dalam jalur lengkap. Contoh: exampledir/exampleobject.txt.
key = 'exampledir/exampleobject.txt'
# Tentukan jalur lengkap file lokal yang ingin Anda unggah. Contoh: D:\\localpath\\examplefile.txt.
filename = 'D:\\localpath\\examplefile.txt'
# Tentukan ID unggah. Anda dapat memperoleh ID unggah setelah Anda memanggil operasi InitiateMultipartUpload untuk memulai tugas unggah multi-bagian tetapi sebelum Anda memanggil operasi CompleteMultipartUpload untuk menyelesaikan tugas unggah multi-bagian.
upload_id = '0004B9894A22E5B1888A1E29F823****'

# Selesaikan tugas unggah multi-bagian.
# Jika Anda ingin menentukan ACL objek saat menyelesaikan tugas unggah multi-bagian, konfigurasikan header terkait dalam fungsi complete_multipart_upload.
headers = dict()
# headers["x-oss-object-acl"] = oss2.OBJECT_ACL_PRIVATE
# Jika Anda menentukan x-oss-complete-all:yes dalam permintaan, OSS mencantumkan semua bagian yang diunggah dengan menggunakan ID unggah saat ini, mengurutkan bagian berdasarkan nomor bagian, dan kemudian melakukan operasi CompleteMultipartUpload.
# Jika x-oss-complete-all:yes ditentukan dalam permintaan, badan permintaan tidak dapat ditentukan. Jika tidak, terjadi kesalahan.
headers["x-oss-complete-all"] = 'yes'
bucket.complete_multipart_upload(key, upload_id, None, headers=headers)

    Batalkan tugas unggah multi-bagian

    Gunakan metode bucket.abort_multipart_upload untuk membatalkan tugas unggah multi-bagian. Jika tugas dibatalkan, ID unggah tidak dapat digunakan lagi, dan bagian yang diunggah akan dihapus.

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

# Dapatkan 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 titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke 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 tanda tangan V4.
region = "cn-hangzhou"

# Tentukan nama bucket Anda.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Tentukan jalur lengkap objek. Jangan sertakan nama bucket dalam jalur lengkap. Contoh: exampledir/exampleobject.txt.
key = 'exampledir/exampleobject.txt'
# Tentukan ID unggah. Anda dapat memperoleh ID unggah dari tanggapan operasi InitiateMultipartUpload.
upload_id = 'yourUploadId'

# Batalkan tugas unggah multi-bagian dengan ID unggah tertentu. Bagian yang diunggah dihapus.
bucket.abort_multipart_upload(key, upload_id)

    Daftarkan bagian yang diunggah

    Berikut adalah contoh cara mencantumkan bagian yang diunggah:

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

# Dapatkan 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 titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke 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 tanda tangan V4.
region = "cn-hangzhou"

# Tentukan nama bucket Anda.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Tentukan jalur lengkap objek. Jangan sertakan nama bucket dalam jalur lengkap. Contoh: exampledir/exampleobject.txt.
key = 'exampledir/exampleobject.txt'
# Tentukan ID unggah. Anda dapat memperoleh ID unggah dari tanggapan operasi InitiateMultipartUpload. Anda harus memperoleh ID unggah sebelum Anda memanggil operasi CompleteMultipartUpload untuk menyelesaikan tugas unggah multi-bagian.
upload_id = 'yourUploadId'

# Daftarkan bagian yang diunggah yang menggunakan ID unggah tertentu.
for part_info in oss2.PartIterator(bucket, key, upload_id):
    print('nomor_bagian:', part_info.part_number)
    print('etag:', part_info.etag)
    print('ukuran:', part_info.size)

    Daftarkan tugas unggah multi-bagian

    • Daftarkan tugas unggah multi-bagian objek tertentu.

      Berikut adalah contoh cara mencantumkan tugas unggah multi-bagian objek tertentu:

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

# Dapatkan 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 titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke 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 tanda tangan V4.
region = "cn-hangzhou"

# Tentukan nama bucket Anda.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Tentukan jalur lengkap objek. Jangan sertakan nama bucket dalam jalur lengkap. Contoh: exampledir/exampleobject.txt.
key = 'exampledir/exampleobject.txt'

# Daftarkan semua tugas unggah multi-bagian objek. Setiap kali metode init_multipart_upload digunakan untuk objek yang sama, ID unggah yang berbeda dikembalikan.
# ID unggah secara unik mengidentifikasi tugas unggah multi-bagian.
for upload_info in oss2.ObjectUploadIterator(bucket, key):
    print('kunci:', upload_info.key)
    print('upload_id:', upload_info.upload_id)

    • Daftarkan semua tugas unggah multi-bagian dalam bucket.

      Berikut adalah contoh cara mencantumkan semua tugas unggah multi-bagian dalam bucket:

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

# Pasangan AccessKey dari akun Alibaba Cloud memiliki izin untuk semua operasi API. Menggunakan kredensial ini untuk melakukan operasi di OSS merupakan operasi berisiko tinggi. Kami merekomendasikan Anda menggunakan Pengguna RAM untuk memanggil operasi API atau melakukan pemeliharaan rutin. Untuk membuat Pengguna RAM, masuk ke Konsol RAM.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Tentukan titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke 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 tanda tangan V4.
region = "cn-hangzhou"

# Tentukan nama bucket Anda.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Daftarkan semua tugas unggah multi-bagian dalam bucket.
for upload_info in oss2.MultipartUploadIterator(bucket):
    print('kunci:', upload_info.key)
    print('upload_id:', upload_info.upload_id)

    • Daftarkan tugas unggah multi-bagian objek dengan awalan tertentu dalam bucket.

      Berikut adalah contoh cara mencantumkan tugas unggah multi-bagian objek dengan awalan tertentu dalam bucket:

      # -*- coding: utf-8 -*-
import os
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Pasangan AccessKey dari akun Alibaba Cloud memiliki izin untuk semua operasi API. Menggunakan kredensial ini untuk melakukan operasi di OSS merupakan operasi berisiko tinggi. Kami merekomendasikan Anda menggunakan Pengguna RAM untuk memanggil operasi API atau melakukan pemeliharaan rutin. Untuk membuat Pengguna RAM, masuk ke Konsol RAM.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Tentukan titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke 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 tanda tangan V4.
region = "cn-hangzhou"

# Tentukan nama bucket Anda.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Daftarkan tugas unggah multi-bagian objek yang namanya mengandung awalan test dalam bucket.
for upload_info in oss2.MultipartUploadIterator(bucket, prefix='test'):
    print('kunci:', upload_info.key)
    print('upload_id:', upload_info.upload_id)

    Tanya Jawab Umum

    Bagaimana cara menghapus bagian?

    Jika tugas unggah multi-bagian terganggu dan operasi AbortMultipartUpload tidak dipanggil, bagian yang diunggah tetap disimpan di bucket. Untuk mencegah biaya penyimpanan yang tidak perlu, gunakan salah satu metode berikut untuk menghapus bagian:

    Referensi

    • Unggah multi-bagian melibatkan tiga operasi API. Informasi lebih lanjut tentang operasi tersebut dapat ditemukan di topik berikut:

    • Informasi lebih lanjut tentang operasi API untuk membatalkan tugas unggah multi-bagian tersedia di AbortMultipartUpload.

    • Informasi lebih lanjut tentang operasi API untuk mencantumkan bagian yang diunggah tersedia di ListParts.

    • Informasi lebih lanjut tentang operasi API untuk mencantumkan semua tugas unggah multi-bagian yang sedang berlangsung tersedia di ListMultipartUploads.