Seznam blobů pomocí Pythonu

Tento článek ukazuje, jak zobrazit bloby pomocí klientské knihovny Azure Storage pro Python.

Chcete-li se dozvědět o seznamu blobů pomocí asynchronních API, viz Seznam blobů asynchronně.

Prerequisites

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řidejte příkazy importu

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobPrefix

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k výpisu objektu blob. Pro autorizaci s Microsoft Entra ID (doporučené) potřebujete vestavěnou roli Storage Blob Data Reader v Azure RBAC nebo vyšší. Další informace najdete v pokynech k autorizaci pro výpis objektů 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 pomocí DefaultAzureCredential vytvořit objekt klienta pro 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.

Informace o možnostech výpisu objektů blob

Když vypíšete bloby ze svého kódu, můžete nastavit mnoho možností, jak spravovat, jak se výsledky vracejí z Azure Storage. Můžete zadat počet výsledků, které se mají vrátit v každé sadě výsledků, a pak načíst následující sady. Můžete zadat předponu pro vrácení objektů blob, jejichž názvy začínají tímto znakem nebo řetězcem. Bloby můžete vypsat v ploché struktuře seznamu nebo hierarchicky. Hierarchický výpis zobrazuje objekty typu blob, jako by byly uspořádané ve složkách.

Pro zařazení blobů do kontejneru pomocí plochého seznamu zavolejte jednu z těchto metod:

Pro zařazení blobů v kontejneru pomocí hierarchického seznamu použijte následující metodu:

Filtrování výsledků pomocí předpony

Pokud chcete filtrovat seznam objektů blob, zadejte řetězec pro name_starts_with argument klíčového slova. Řetězec předpony může obsahovat jeden nebo více znaků. Azure Storage vrací pouze ty bloby, jejichž názvy začínají tímto prefixem.

Plochý výpis versus hierarchický výpis

Objekty blob ve službě Azure Storage jsou uspořádané do plochého paradigmatu místo hierarchického paradigmatu (jako je klasický systém souborů). Nicméně můžete bloby organizovat do virtuálních adresářů , které napodobují strukturu složek. Virtuální adresář tvoří část názvu objektu blob a je označen znakem oddělovače.

Pokud chcete objekty blob uspořádat do virtuálních adresářů, použijte v názvu objektu blob znak oddělovače. Výchozí znak oddělovače je lomítko (/), ale jako oddělovač můžete zadat libovolný znak.

Pokud pojmenováváte své bloby pomocí oddělovače, můžete zvolit hierarchický seznam blobů. Pro hierarchickou operaci výpisu vrátí Azure Storage všechny virtuální adresáře a blobové objekty pod nadřazeným objektem. Operaci výpisu můžete volat rekurzivně a procházet hierarchii podobně jako při procházení klasického systému souborů prostřednictvím kódu programu.

Použití plochého výpisu

Operace výpisu ve výchozím nastavení vrací objekty blob v plochém výpisu. V plochém výpisu nejsou blobs uspořádané podle virtuálního adresáře.

Následující příklad uvádí bloby ve specifikovaném kontejneru pomocí plochého seznamu:

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

Ukázkový výstup je podobný následujícímu:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

Můžete také nastavit možnosti filtrování výsledků seznamu nebo zobrazení více informací. V následujícím příkladu jsou uvedeny objekty blob a značky blobů:

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

Ukázkový výstup je podobný následujícímu:

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

Poznámka

Zobrazený ukázkový výstup předpokládá, že máte účet úložiště s plochým oborem názvů. Pokud povolíte funkci hierarchického jmenného prostoru pro svůj úložný účet, adresáře nejsou virtuální. Místo toho jsou to konkrétní, nezávislé objekty. V důsledku toho se adresáře v seznamu zobrazují jako objekty blob nulové délky.

Alternativní možnost výpisu při práci s hierarchickým oborem názvů najdete v tématu Výpis obsahu adresáře (Azure Data Lake Storage).

Použití hierarchického výpisu

Při hierarchickém volání operace výpisu obsahu vrátí Azure Storage virtuální adresáře a objekty blob na první úrovni hierarchie.

Pokud chcete zobrazit seznam objektů blob hierarchicky, použijte následující metodu:

Následující příklad uvádí objekty blob v zadaném kontejneru pomocí hierarchického výpisu:

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

Ukázkový výstup je podobný následujícímu:

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

Poznámka

Snímky blobů nelze vypsat v operaci hierarchického výpisu.

Asynchronní seznamování objektů typu blob

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

Postupujte podle těchto kroků pro zařazení blobů pomocí asynchronních 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, ContainerClient, BlobPrefix

  2. Přidejte kód pro spuštění programu pomocí asyncio.run. Tato funkce v tomto příkladu spouští předanou korutinu main() a spravuje smyčku asyncio událostí. Korutiny jsou deklarovány pomocí syntaxe async/await. V tomto příkladu korutina main() nejprve vytvoří nejvyšší úroveň BlobServiceClient pomocí async with, poté zavolá metodu, která uvádí bloby. Pouze klient nejvyšší úrovně musí používat async with, protože ostatní klienti, kteří jsou z něj vytvořeni, 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.list_blobs_flat(blob_service_client, "sample-container")

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

  3. Přidejte kód pro seznam objektů blob. Následující příklad kódu uvádí bloby pomocí plochého seznamu. Kód je stejný jako u synchronního příkladu, s tím rozdílem, že metoda je deklarována pomocí async klíčového slova a async for používá se při volání metody list_blobs .

    async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    async for blob in container_client.list_blobs():
        print(f"Name: {blob.name}")

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

Seznam blobů ve formátu Apache Arrow (náhled)

Important

Seznam blobů ve formátu Apache Arrow je momentálně v PREVIEWS. Tento scénář vyžaduje beta (preview) verzi klientské knihovny Azure Blob Storage pro Python (například azure-storage-blobpreview verze 12.31.0b1 nebo novější). Funkce ve verzi Preview jsou poskytovány bez smlouvy o úrovni služeb a nedoporučuje se pro produkční úlohy. Některé funkce nemusí být podporovány nebo mohou mít omezené schopnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Tato schopnost je postavena na existujícím List Blobs API. Místo výchozího XML používá kompaktní, sloupcový formát Apache Arrow jako formát odpovědi na drátu. Povolíte to nastavením jedné možnosti při volání výpisu kontejnerů. Python SDK dekóduje Apache Arrow v pozadí a stále vrací stejné BlobProperties objekty. Tento přístup zlepšuje propustnost výpisů a snižuje CPU na straně klienta při enumeraci velkých kontejnerů. Zachovává kontrakt odpovědi, na který aplikace spoléhají.

Warning

Seznamování blobů ve formátu Apache Arrow není podporováno na úložných účtech, které mají povolený hierarchický jmenný prostor (Azure Data Lake Storage).

Chcete-li získat výsledky ve formátu Apache Arrow, nastavte argument klíčového slova response_format na hodnotu "arrow" při volání ContainerClient.list_blobs nebo ContainerClient.list_blob_names. Při použití výstupu Apache Arrow můžete také nastavit argumenty start_from a end_before klíčových slov pro kontrolu rozsahu vrácených cest.

Poznámka

Používání response_format="arrow" vyžaduje instalaci balíčku nanoarrow .

Následující příklad uvádí bloby v kontejneru a požaduje výsledky ve formátu Apache Arrow:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

Zdroje

Chcete-li se dozvědět více o tom, jak zobrazit bloby pomocí klientské knihovny Azure Blob Storage pro Python, podívejte se na následující zdroje.

Ukázky kódu

Operace rozhraní REST API

Azure SDK pro Python obsahuje knihovny, které se staví na Azure REST API. Použitím těchto knihoven můžete pracovat s operacími REST API prostřednictvím známých Python paradigmat. Metody klientské knihovny pro výpis objektů blob používají následující operaci rozhraní REST API:

Prostředky klientské knihovny

Viz také

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.
  • Last updated on