Cara mengunduh file menggunakan OSS Python SDK V2 - Object Storage Service

Topik ini menjelaskan cara menggunakan modul Downloader dari Python SDK V2 untuk mengunduh file.

Catatan penggunaan

Kode contoh dalam topik ini menggunakan Wilayah China (Hangzhou) dengan ID wilayah cn-hangzhou sebagai contoh. Secara default, titik akhir publik digunakan. Jika Anda mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk informasi lebih lanjut tentang wilayah dan titik akhir yang didukung oleh OSS, lihat Wilayah dan Titik Akhir.
Untuk mengunduh file, Anda harus memiliki izin oss:GetObject. Untuk informasi lebih lanjut, lihat Melampirkan Kebijakan Kustom ke Pengguna RAM.

Definisi metode

Fitur Downloader

Modul Downloader dari Python SDK V2 menyediakan metode unduhan serbaguna yang mengabstraksi detail implementasi dasar untuk menawarkan fitur unduhan file yang nyaman.

Modul Downloader menggunakan unduhan rentang untuk secara otomatis membagi file menjadi bagian-bagian kecil dan mengunduh bagian-bagian tersebut secara paralel, yang meningkatkan kinerja unduhan.
Modul Downloader juga menyediakan fitur unduhan yang dapat dilanjutkan. Selama proses unduhan, status bagian yang telah selesai dicatat. Jika unduhan terganggu oleh masalah seperti kegagalan jaringan atau keluar program yang tidak terduga, Anda dapat melanjutkan unduhan dari titik henti terakhir.

Berikut adalah kode yang menunjukkan metode umum dari modul Downloader:

class Downloader:
  ...

def downloader(self, **kwargs) -> Downloader:
  ...

def download_file(self, request: models.GetObjectRequest, filepath: str, **kwargs: Any) -> DownloadResult:
  ...
  
def download_to(self, request: models.GetObjectRequest, writer: IO[bytes], **kwargs: Any) -> DownloadResult:
  ...

Parameter permintaan

Parameter	Tipe	Deskripsi
request	GetObjectRequest	Parameter permintaan untuk mengunduh objek. Parameter tersebut sama dengan yang digunakan pada metode GetObject. Untuk informasi lebih lanjut, lihat GetObjectRequest
filepath	str	Path file lokal.
writer	IO[bytes]	Aliran unduhan.
**kwargs	Any	(Opsional) Parameter arbitrer. Tipe: kamus

Parameter respons

Tipe	Deskripsi
DownloadResult	Parameter respons untuk mengunduh objek. Untuk informasi lebih lanjut, lihat DownloadResult

Saat menggunakan client.downloader untuk menginisialisasi instance downloader, Anda dapat menentukan opsi konfigurasi untuk menyesuaikan perilaku unduhan. Anda juga dapat menentukan opsi konfigurasi untuk setiap pemanggilan unduhan untuk menyesuaikan perilaku untuk setiap objek. Sebagai contoh, Anda dapat menentukan ukuran bagian sebagai berikut:

Tetapkan parameter konfigurasi downloader.

downloader = client.downloader(part_size=1024 * 1024)

Tetapkan parameter konfigurasi untuk setiap permintaan unduhan.

result = downloader.download_file(oss.GetObjectRequest(
    bucket="example_bucket",
    key="example_key",
),
    filepath="/local/dir/example",
    part_size=10 * 1024 * 1024,
)

Tabel berikut menjelaskan opsi konfigurasi umum.

Parameter	Tipe	Deskripsi
part_size	int	Menentukan ukuran bagian. Nilai default adalah 6 MiB.
parallel_num	int	Menentukan jumlah tugas unduhan bersamaan. Nilai default adalah 3. Parameter ini menentukan batas konkurensi untuk satu panggilan, bukan batas konkurensi global.
enable_checkpoint	bool	Menentukan apakah akan mengaktifkan fitur unduhan yang dapat dilanjutkan. Secara default, fitur ini dinonaktifkan.
checkpoint_dir	str	Menentukan path untuk menyimpan file rekaman. Contoh: /local/dir/. Parameter ini valid hanya jika enable_checkpoint disetel ke True.
verify_data	bool	Menentukan apakah akan memverifikasi nilai CRC-64 dari data yang diunduh saat unduhan dilanjutkan. Secara default, nilai tersebut tidak diverifikasi. Parameter ini valid hanya jika enable_checkpoint disetel ke True.
use_temp_file	bool	Menentukan apakah akan menggunakan file sementara saat Anda mengunduh file. Secara default, file sementara digunakan. File pertama kali diunduh ke file sementara. Setelah unduhan berhasil, file sementara diubah namanya menjadi file objek.

Untuk informasi lebih lanjut tentang definisi metode manajer unduhan file, lihat Downloader.

Kode contoh

Anda dapat menggunakan kode berikut untuk mengunduh file dari bucket ke perangkat lokal.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah dan jelaskan tujuan skrip: contoh unduhan file.
parser = argparse.ArgumentParser(description="contoh unduhan file")

# Tambahkan argumen baris perintah --region, yang menunjukkan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menunjukkan nama bucket dari mana Anda ingin mengunduh file. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menunjukkan nama domain yang dapat digunakan layanan lain untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menunjukkan kunci objek (file) di OSS. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)
# Tambahkan argumen baris perintah --file_path, yang menunjukkan path lokal untuk menyimpan file yang diunduh. Argumen ini wajib. Contoh: "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='Path untuk menyimpan file yang diunduh.', required=True)

def main():
    # Parsing argumen baris perintah untuk mendapatkan nilai yang dimasukkan oleh pengguna.
    args = parser.parse_args()

    # Muat informasi autentikasi yang diperlukan untuk mengakses OSS dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default dari SDK untuk membuat objek konfigurasi dan atur penyedia autentikasi.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # Atur properti region objek konfigurasi berdasarkan argumen baris perintah yang diberikan oleh pengguna.
    cfg.region = args.region

    # Jika titik akhir kustom diberikan, perbarui properti endpoint objek konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Gunakan konfigurasi di atas untuk menginisialisasi klien OSS untuk berinteraksi dengan OSS.
    client = oss.Client(cfg)

    # Buat objek untuk mengunduh file.
    downloader = client.downloader()

    # Panggil metode untuk melakukan operasi unduhan file.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Tentukan bucket tujuan.
            key=args.key,        # Tentukan nama file di OSS.
        ),
        filepath=args.file_path  # Tentukan path lokal untuk menyimpan file yang diunduh.
    )

    # Cetak informasi tentang hasil unduhan, termasuk jumlah byte yang ditulis.
    print(f'written: {result.written}')

# Saat skrip ini dieksekusi langsung, panggil fungsi utama untuk memulai logika pemrosesan.
if __name__ == "__main__":
    main()  # Titik masuk skrip, tempat alur program dimulai.

Skenario umum

Gunakan downloader untuk menetapkan ukuran bagian dan konkurensi

Anda dapat menggunakan kode berikut untuk mengonfigurasi downloader agar menetapkan ukuran bagian dan konkurensi.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah dan jelaskan tujuan skrip: contoh unduhan file.
parser = argparse.ArgumentParser(description="contoh unduhan file")

# Tambahkan argumen baris perintah --region, yang menunjukkan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menunjukkan nama bucket dari mana Anda ingin mengunduh file. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menunjukkan nama domain yang dapat digunakan layanan lain untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menunjukkan kunci objek (file) di OSS. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)
# Tambahkan argumen baris perintah --file_path, yang menunjukkan path lokal untuk menyimpan file yang diunduh. Argumen ini wajib. Contoh: "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='Path untuk menyimpan file yang diunduh.', required=True)

def main():
    # Parsing argumen baris perintah untuk mendapatkan nilai yang dimasukkan oleh pengguna.
    args = parser.parse_args()

    # Muat informasi autentikasi yang diperlukan untuk mengakses OSS dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default dari SDK untuk membuat objek konfigurasi dan atur penyedia autentikasi.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # Atur properti region objek konfigurasi berdasarkan argumen baris perintah yang diberikan oleh pengguna.
    cfg.region = args.region

    # Jika titik akhir kustom diberikan, perbarui properti endpoint objek konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Gunakan konfigurasi di atas untuk menginisialisasi klien OSS untuk berinteraksi dengan OSS.
    client = oss.Client(cfg)

    # Buat objek untuk mengunduh file dan tetapkan opsi lanjutan.
    downloader = client.downloader(
        part_size=1024 * 1024,  # Tetapkan ukuran setiap bagian menjadi 1 MB.
        parallel_num=5,         # Tetapkan jumlah thread unduhan bersamaan menjadi 5.
        block_size=1024 * 1024  # Tetapkan ukuran blok data yang dibaca setiap kali menjadi 1 MB.
    )

    # Panggil metode untuk melakukan operasi unduhan file.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Tentukan bucket tujuan.
            key=args.key,        # Tentukan nama file di OSS.
        ),
        filepath=args.file_path  # Tentukan path lokal untuk menyimpan file yang diunduh.
    )

    # Cetak informasi tentang hasil unduhan, termasuk jumlah byte yang ditulis.
    print(f'written: {result.written}')

# Saat skrip ini dieksekusi langsung, panggil fungsi utama untuk memulai logika pemrosesan.
if __name__ == "__main__":
    main()  # Titik masuk skrip, tempat alur program dimulai.

Gunakan downloader untuk mengaktifkan unduhan yang dapat dilanjutkan

Anda dapat menggunakan kode berikut untuk mengonfigurasi downloader agar mengaktifkan fitur unduhan yang dapat dilanjutkan.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah dan jelaskan tujuan skrip: contoh unduhan file.
parser = argparse.ArgumentParser(description="contoh unduhan file")

# Tambahkan argumen baris perintah --region, yang menunjukkan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menunjukkan nama bucket dari mana Anda ingin mengunduh file. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menunjukkan nama domain yang dapat digunakan layanan lain untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menunjukkan kunci objek (file) di OSS. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)
# Tambahkan argumen baris perintah --file_path, yang menunjukkan path lokal untuk menyimpan file yang diunduh. Argumen ini wajib. Contoh: "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='Path untuk menyimpan file yang diunduh.', required=True)

def main():
    # Parsing argumen baris perintah untuk mendapatkan nilai yang dimasukkan oleh pengguna.
    args = parser.parse_args()

    # Muat informasi autentikasi yang diperlukan untuk mengakses OSS dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default dari SDK untuk membuat objek konfigurasi dan atur penyedia autentikasi.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # Atur properti region objek konfigurasi berdasarkan argumen baris perintah yang diberikan oleh pengguna.
    cfg.region = args.region

    # Jika titik akhir kustom diberikan, perbarui properti endpoint objek konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Gunakan konfigurasi di atas untuk menginisialisasi klien OSS untuk berinteraksi dengan OSS.
    client = oss.Client(cfg)

    # Buat objek untuk mengunduh file dan tetapkan opsi lanjutan.
    downloader = client.downloader(
        use_temp_file=True,            # Gunakan file sementara.
        enable_checkpoint=True,        # Aktifkan unduhan yang dapat dilanjutkan.
        checkpoint_dir=args.file_path, # Direktori untuk menyimpan file rekaman unduhan yang dapat dilanjutkan.
        verify_data=True               # Menentukan apakah akan memverifikasi data.
    )

    # Panggil metode untuk melakukan operasi unduhan file.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Tentukan bucket tujuan.
            key=args.key,        # Tentukan nama file di OSS.
        ),
        filepath=args.file_path  # Tentukan path lokal untuk menyimpan file yang diunduh.
    )

    # Cetak informasi tentang hasil unduhan, termasuk jumlah byte yang ditulis.
    print(f'written: {result.written}')

# Saat skrip ini dieksekusi langsung, panggil fungsi utama untuk memulai logika pemrosesan.
if __name__ == "__main__":
    main()  # Titik masuk skrip, tempat alur program dimulai.

Gunakan downloader dan tampilkan bilah kemajuan

Kode contoh berikut menunjukkan cara menggunakan bilah kemajuan untuk melihat kemajuan unduhan saat menggunakan downloader untuk mengunduh file.

import argparse
import alibabacloud_oss_v2 as oss

# Buat parser argumen baris perintah dan jelaskan tujuan skrip: contoh unduhan file.
parser = argparse.ArgumentParser(description="contoh unduhan file")

# Tambahkan argumen baris perintah --region, yang menunjukkan wilayah tempat bucket berada. Argumen ini wajib.
parser.add_argument('--region', help='Wilayah tempat bucket berada.', required=True)
# Tambahkan argumen baris perintah --bucket, yang menunjukkan nama bucket dari mana Anda ingin mengunduh file. Argumen ini wajib.
parser.add_argument('--bucket', help='Nama bucket.', required=True)
# Tambahkan argumen baris perintah --endpoint, yang menunjukkan nama domain yang dapat digunakan layanan lain untuk mengakses OSS. Argumen ini opsional.
parser.add_argument('--endpoint', help='Nama domain yang dapat digunakan layanan lain untuk mengakses OSS')
# Tambahkan argumen baris perintah --key, yang menunjukkan kunci objek (file) di OSS. Argumen ini wajib.
parser.add_argument('--key', help='Nama objek.', required=True)
# Tambahkan argumen baris perintah --file_path, yang menunjukkan path lokal untuk menyimpan file yang diunduh. Argumen ini wajib. Contoh: "/Users/yourLocalPath/yourFileName".
parser.add_argument('--file_path', help='Path untuk menyimpan file yang diunduh.', required=True)

def main():
    # Parsing argumen baris perintah untuk mendapatkan nilai yang dimasukkan oleh pengguna.
    args = parser.parse_args()

    # Muat informasi autentikasi yang diperlukan untuk mengakses OSS dari variabel lingkungan untuk verifikasi identitas.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Gunakan konfigurasi default dari SDK untuk membuat objek konfigurasi dan atur penyedia autentikasi.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Atur properti region objek konfigurasi berdasarkan argumen baris perintah yang diberikan oleh pengguna.
    cfg.region = args.region

    # Jika titik akhir kustom diberikan, perbarui properti endpoint objek konfigurasi.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Gunakan konfigurasi di atas untuk menginisialisasi klien OSS untuk berinteraksi dengan OSS.
    client = oss.Client(cfg)

    # Buat objek untuk mengunduh file.
    downloader = client.downloader()

    # Definisikan variabel kamus progress_state untuk menyimpan status kemajuan unduhan. Nilai awal adalah 0.
    progress_state = {'saved': 0}

    # Definisikan fungsi callback kemajuan _progress_fn.
    def _progress_fn(n, written, total):
        # Gunakan kamus untuk menyimpan jumlah byte yang ditulis secara kumulatif.
        progress_state['saved'] += n

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

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

    # Panggil metode untuk melakukan operasi unduhan file.
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # Tentukan bucket tujuan.
            key=args.key,        # Tentukan nama file di OSS.
            progress_fn=_progress_fn,  # Tetapkan fungsi callback kemajuan.
        ),
        filepath=args.file_path  # Tentukan path lokal untuk menyimpan file yang diunduh.
    )

    # Cetak informasi tentang hasil unduhan, termasuk jumlah byte yang ditulis.
    print(f'written: {result.written}')

# Saat skrip ini dieksekusi langsung, panggil fungsi utama untuk memulai logika pemrosesan.
if __name__ == "__main__":
    main()  # Titik masuk skrip, tempat alur program dimulai.

Referensi

Untuk informasi lebih lanjut tentang manajer unduhan, lihat Panduan Pengembang.
Untuk kode contoh lengkap manajer unduhan, lihat download_file.py.