Bagikan melalui

Mengunduh blob dengan Python

Artikel ini memperlihatkan cara mengunduh blob menggunakan pustaka klien Azure Storage untuk Python. Anda dapat mengunduh data blob ke berbagai tujuan, termasuk jalur file lokal, aliran, atau string teks. Anda juga dapat membuka stream blob dan membacanya.

Untuk mempelajari tentang mengunduh blob menggunakan API asinkron, lihat Mengunduh blob secara asinkron.

Prasyarat

Menyiapkan lingkungan Anda

Jika Anda tidak memiliki proyek yang sudah ada, bagian ini menunjukkan kepada Anda cara menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk Python. Untuk detail selengkapnya, lihat Mulai menggunakan Azure Blob Storage dan Python.

Untuk bekerja dengan contoh kode dalam artikel ini, ikuti langkah-langkah ini untuk menyiapkan proyek Anda.

Memasang paket

Instal paket berikut menggunakan pip install:

pip install azure-storage-blob azure-identity

Menambahkan pernyataan impor

Tambahkan pernyataan import berikut:

import io
import os
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient

Otorisasi

Mekanisme otorisasi harus memiliki izin yang diperlukan untuk melakukan operasi pengunduhan. Untuk otorisasi dengan Microsoft Entra ID (disarankan), Anda memerlukan peran bawaan Azure RBAC Storage Blob Data Reader atau yang lebih tinggi. Untuk mempelajari lebih lanjut, lihat panduan otorisasi untuk Get Blob (REST API).

Membuat objek klien

Untuk menyambungkan aplikasi ke Blob Storage, buat instans BlobServiceClient. Contoh berikut menunjukkan cara membuat objek klien menggunakan DefaultAzureCredential untuk otorisasi:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

Anda juga dapat membuat objek klien untuk kontainer atau blob tertentu, baik secara langsung atau dari BlobServiceClient objek. Untuk mempelajari selengkapnya tentang membuat dan mengelola objek klien, lihat Membuat dan mengelola objek klien yang berinteraksi dengan sumber daya data.

Unduh blob

Anda dapat menggunakan metode berikut untuk mengunduh blob:

Metode mengembalikan download_blobobjek StorageStreamDownloader . Selama pengunduhan, perpustakaan klien membagi permintaan unduhan menjadi gugus, di mana setiap gugus diunduh dengan permintaan rentang Get Blob yang terpisah. Perilaku ini tergantung pada ukuran total blob dan bagaimana opsi transfer data diatur.

Mengunduh ke jalur file

Contoh berikut mengunduh blob ke jalur file:

def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob()
        sample_blob.write(download_stream.readall())

Mengunduh ke stream

Contoh berikut akan mengunduh blob ke dalam stream. Dalam contoh ini, StorageStreamDownloader.read_into mengunduh konten blob ke streaming dan mengembalikan jumlah byte yang dibaca:

def download_blob_to_stream(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # readinto() downloads the blob contents to a stream and returns the number of bytes read
    stream = io.BytesIO()
    num_bytes = blob_client.download_blob().readinto(stream)
    print(f"Number of bytes: {num_bytes}")

Mengunduh blob dalam potongan

Contoh berikut mengunduh blob dan melakukan iterasi atas potongan dalam aliran unduhan. Dalam contoh ini, StorageStreamDownloader.chunks mengembalikan iterator, yang memungkinkan Anda membaca konten blob dalam gugus:

def download_blob_chunks(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # This returns a StorageStreamDownloader
    stream = blob_client.download_blob()
    chunk_list = []

    # Read data in chunks to avoid loading all into memory at once
    for chunk in stream.chunks():
        # Process your data (anything can be done here - 'chunk' is a byte array)
        chunk_list.append(chunk)

Mengunduh ke string

Contoh berikut mengunduh konten blob sebagai teks. Dalam contoh ini, encoding parameter diperlukan untuk readall() mengembalikan string, jika tidak, parameter mengembalikan byte:

def download_blob_to_string(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # encoding param is necessary for readall() to return str, otherwise it returns bytes
    downloader = blob_client.download_blob(max_concurrency=1, encoding='UTF-8')
    blob_text = downloader.readall()
    print(f"Blob contents: {blob_text}")

Mengunduh blok blob dengan opsi konfigurasi

Anda dapat menentukan opsi konfigurasi pustaka klien saat mengunduh blob. Opsi ini dapat disetel untuk meningkatkan performa dan meningkatkan keandalan. Contoh kode berikut menunjukkan cara menentukan opsi konfigurasi untuk unduhan baik di tingkat metode, maupun di tingkat klien saat membuat instans BlobClient. Opsi ini juga dapat dikonfigurasi untuk instans ContainerClient atau instans BlobServiceClient .

Tentukan opsi transfer data saat diunduh

Anda dapat mengatur opsi konfigurasi saat membuat instans klien untuk mengoptimalkan performa operasi transfer data. Anda dapat meneruskan argumen kata kunci berikut saat membuat objek klien di Python:

  • max_chunk_get_size - Ukuran gugus maksimum yang digunakan untuk mengunduh blob. Secara bawaan adalah 4 MiB.
  • max_single_get_size - Ukuran maksimum untuk blob yang akan diunduh dalam satu panggilan. Jika ukuran blob total melebihi max_single_get_size, sisa data blob diunduh dalam gugus. Secara default menjadi 32 MiB.

Untuk operasi pengunduhan, Anda juga dapat meneruskan max_concurrency argumen saat memanggil download_blob. Argumen ini menentukan jumlah maksimum koneksi paralel untuk operasi pengunduhan.

Contoh kode berikut menunjukkan cara menentukan opsi transfer data saat membuat BlobClient objek, dan cara mengunduh data menggunakan objek klien tersebut. Nilai yang disediakan dalam sampel ini tidak dimaksudkan untuk menjadi rekomendasi. Untuk menyetel nilai-nilai ini dengan benar, Anda perlu mempertimbangkan kebutuhan spesifik aplikasi Anda.

def download_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for download
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_single_get_size=1024*1024*32, # 32 MiB
        max_chunk_get_size=1024*1024*4 # 4 MiB
    )

    with open(file=os.path.join(r'file_path', 'file_name'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob(max_concurrency=2)
        sample_blob.write(download_stream.readall())

Mengunduh blob secara asinkron

Pustaka klien Azure Blob Storage untuk Python mendukung pengunduhan blob secara asinkron. Untuk mempelajari selengkapnya tentang persyaratan penyiapan proyek, lihat Pemrograman asinkron.

Ikuti langkah-langkah berikut untuk mengunduh blob menggunakan API asinkron:

  1. Tambahkan pernyataan import berikut:

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient

  2. Tambahkan kode untuk menjalankan program menggunakan asyncio.run. Fungsi ini menjalankan coroutine yang diteruskan, main() dalam contoh kami, dan mengelola loop peristiwa asyncio. Korutin dinyatakan dengan sintaks async/await. Dalam contoh ini, coroutine main() pertama-tama membuat level BlobServiceClient tertinggi dengan menggunakan async with, lalu memanggil metode yang mengunduh blob. Perhatikan bahwa hanya klien tingkat atas yang perlu menggunakan async with, karena klien lain yang dibuat darinya berbagi kumpulan koneksi yang sama.

    async def main():
    sample = BlobSamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        await sample.download_blob_to_file(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())

  3. Tambahkan kode untuk mengunduh blob. Contoh berikut mengunduh blob ke jalur file lokal menggunakan BlobClient objek. Kode sama dengan contoh sinkron, kecuali bahwa metode dideklarasikan dengan async kata kunci dan await kata kunci digunakan saat memanggil download_blob metode .

    async def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = await blob_client.download_blob()
        data = await download_stream.readall()
        sample_blob.write(data)

Dengan pengaturan dasar ini, Anda dapat menerapkan contoh lain dalam artikel ini sebagai korutin menggunakan sintaks async/await.

Sumber

Untuk mempelajari selengkapnya tentang cara mengunduh blob menggunakan pustaka klien Azure Blob Storage untuk Python, lihat sumber daya berikut ini.

Sampel kode

Operasi REST API

Azure SDK untuk Python berisi pustaka yang dibangun di atas Azure REST API, memungkinkan Anda berinteraksi dengan operasi REST API melalui paradigma Python yang sudah dikenal. Metode pustaka klien untuk mengunduh blob menggunakan operasi REST API berikut:

Sumber daya pustaka klien

Konten terkait

  • Artikel ini adalah bagian dari panduan pengembang Blob Storage untuk Python. Untuk mempelajari lebih lanjut, lihat daftar lengkap artikel panduan pengembang di Membangun aplikasi Python Anda.
  • Last updated on