Mengunduh blob dengan Python

  • Artikel

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 aliran blob dan membacanya.

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

Prasyarat

  • Artikel ini mengasumsikan Anda sudah menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk Python. Untuk mempelajari tentang menyiapkan proyek Anda, termasuk penginstalan paket, menambahkan import pernyataan, dan membuat objek klien resmi, lihat Mulai menggunakan Azure Blob Storage dan Python.
  • Untuk menggunakan API asinkron dalam kode Anda, lihat persyaratan di bagian Pemrograman asinkron.
  • Mekanisme otorisasi harus memiliki izin untuk melakukan operasi pengunduhan. Untuk mempelajari lebih lanjut, lihat panduan otorisasi untuk operasi REST API berikut:

Mengunduh blob

Anda dapat menggunakan metode berikut untuk mengunduh blob:

Metode mengembalikan download_blobobjek StorageStreamDownloader . Selama pengunduhan, pustaka klien membagi permintaan unduhan menjadi potongan, di mana setiap gugus diunduh dengan permintaan rentang Get Blob 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 aliran

Contoh berikut mengunduh blob ke aliran. 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 gugus

Contoh berikut mengunduh blob dan melakukan iterasi atas gugus 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 blob blok 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. Default ke 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. Default ke 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 perulangan asyncio peristiwa. Koroutin dinyatakan dengan sintaks asinkron/tunggu. Dalam contoh ini, main() coroutine pertama-tama membuat tingkat BlobServiceClient atas 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 koroutin menggunakan sintaks asinkron/tunggu.

Sumber daya

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

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:

Sampel kode

Sumber daya pustaka klien