Sdílet prostřednictvím

Stažení objektu blob pomocí Pythonu

  • Článek

Tento článek ukazuje, jak stáhnout objekt blob pomocí klientské knihovny azure Storage pro Python. Data objektů blob si můžete stáhnout do různých cílů, včetně místní cesty k souboru, datového proudu nebo textového řetězce. Můžete také otevřít datový proud objektů blob a číst z něj.

Další informace o stahování objektů blob pomocí asynchronních rozhraní API najdete v tématu Asynchronní stahování objektů blob.

Požadavky

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro Python. Další podrobnosti najdete v tématu Začínáme se službou Azure Blob Storage a Pythonem.

Pokud chcete pracovat s příklady kódu v tomto článku, nastavte projekt pomocí následujícího postupu.

Instalace balíčků

Nainstalujte následující balíčky pomocí pip install:

pip install azure-storage-blob azure-identity

Přidání příkazů importu

Přidejte následující příkazy import:

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

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k provedení operace stahování. K autorizaci pomocí Microsoft Entra ID (doporučeno) potřebujete integrovanou roli Storage Blob Data Reader služby Azure RBAC nebo vyšší. Další informace najdete v pokynech pro autorizaci k získání objektu blob (REST API).

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient. Následující příklad ukazuje, jak vytvořit objekt klienta pro DefaultAzureCredential autorizaci:

# 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)

Můžete také vytvořit klientské objekty pro konkrétní kontejnery nebo objekty blob, a to buď přímo, nebo z objektu BlobServiceClient . Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Stažení objektu blob

Ke stažení objektu blob můžete použít následující metodu:

Metoda download_blob vrátí StorageStreamDownloader objektu. Během stahování rozdělí klientské knihovny žádost o stažení na bloky dat, kde se jednotlivé bloky stahují pomocí samostatné žádosti o získání rozsahu objektů blob . Toto chování závisí na celkové velikosti objektu blob a způsobu nastavení možností přenosu dat.

Stažení do cesty k souboru

Následující příklad stáhne objekt blob do cesty k souboru:

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())

Stažení do streamu

Následující příklad stáhne objekt blob do datového proudu. V tomto příkladu StorageStreamDownloader.read_into stáhne obsah objektu blob do datového proudu a vrátí počet přečtených bajtů:

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}")

Stažení objektu blob v blocích dat

Následující příklad stáhne objekt blob a iteruje bloky dat ve streamu stahování. V tomto příkladu storageStreamDownloader.chunks vrátí iterátor, který umožňuje číst obsah objektu blob v blocích:

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)

Stažení do řetězce

Následující příklad stáhne obsah objektů blob jako text. V tomto příkladu encoding je parametr nezbytný k readall() vrácení řetězce, jinak vrací bajty:

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}")

Stažení objektu blob bloku s možnostmi konfigurace

Při stahování objektu blob můžete definovat možnosti konfigurace klientské knihovny. Tyto možnosti je možné ladit, aby se zlepšil výkon a zvýšil spolehlivost. Následující příklady kódu ukazují, jak definovat možnosti konfigurace pro stahování na úrovni metody i na úrovni klienta při vytváření instance BlobClient. Tyto možnosti lze také nakonfigurovat pro instanci ContainerClient nebo instanci BlobServiceClient .

Určení možností přenosu dat při stahování

Při vytváření instance klienta můžete nastavit možnosti konfigurace pro optimalizaci výkonu operací přenosu dat. Při vytváření klientského objektu v Pythonu můžete předat následující argumenty klíčových slov:

  • max_chunk_get_size – Maximální velikost bloku dat používaná ke stažení objektu blob. Výchozí hodnota je 4 MiB.
  • max_single_get_size – Maximální velikost objektu blob, který se má stáhnout v jednom volání. Pokud celková velikost objektu blob překročí max_single_get_size, zbývající data objektu blob se stáhnou do bloků dat. Výchozí hodnota je 32 MiB.

Při operacích stahování můžete také předat max_concurrency argument při volání download_blob. Tento argument definuje maximální počet paralelních připojení pro operaci stahování.

Následující příklad kódu ukazuje, jak určit možnosti přenosu dat při vytváření objektu BlobClient a jak stáhnout data pomocí tohoto klientského objektu. Hodnoty uvedené v této ukázce nejsou určené jako doporučení. Pokud chcete tyto hodnoty správně vyladit, musíte zvážit konkrétní potřeby vaší aplikace.

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())

Asynchronní stahování objektů blob

Klientská knihovna Azure Blob Storage pro Python podporuje asynchronní stahování objektů blob. Další informace o požadavcích na nastavení projektu najdete v tématu Asynchronní programování.

Pomocí následujících kroků stáhněte objekt blob pomocí asynchronních rozhraní API:

  1. Přidejte následující příkazy importu:

    import asyncio

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

  2. Přidejte kód pro spuštění programu pomocí asyncio.run. Tato funkce spustí předanou korutinu v main() našem příkladu a spravuje smyčku asyncio událostí. Koroutiny jsou deklarovány syntaxí async/await. V tomto příkladu main() korutin nejprve vytvoří nejvyšší úroveň BlobServiceClient pomocí async witha pak zavolá metodu, která stáhne objekt blob. Mějte na paměti, že pouze klient nejvyšší úrovně musí používat async with, protože ostatní klienti, kteří z něj vytvořili, sdílejí stejný fond připojení.

    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. Přidejte kód pro stažení objektu blob. Následující příklad stáhne objekt blob do místní cesty k souboru pomocí objektu BlobClient . Kód je stejný jako synchronní příklad s tím rozdílem, že metoda je deklarována pomocí async klíčového await slova a klíčové slovo se používá při volání download_blob metody.

    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)

S tímto základním nastavením můžete implementovat další příklady v tomto článku jako koruty pomocí syntaxe async/await.

Zdroje informací

Další informace o tom, jak stáhnout objekty blob pomocí klientské knihovny služby Azure Blob Storage pro Python, najdete v následujících zdrojích informací.

Ukázky kódu

Operace rozhraní REST API

Sada Azure SDK pro Python obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat Pythonu. Metody klientské knihovny pro stahování objektů blob používají následující operaci rozhraní REST API:

Prostředky klientské knihovny

Související obsah

  • Tento článek je součástí příručky pro vývojáře služby Blob Storage pro Python. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace v Pythonu.