Lista blobar med Python

Den här artikeln visar hur man listar blobs med hjälp av Azure Storage-klientbiblioteket för Python.

För att lära dig om listning av blobs med hjälp av asynkrona API:er, se List blobs asynchronously.

Förutsättningar

• Azure-prenumeration – skapa en kostnadsfritt
• Azure Storage-konto – skapa ett lagringskonto
• Python 3,8+

Konfigurera din miljö

Om du inte har ett befintligt projekt visar det här avsnittet hur du konfigurerar ett projekt för att arbeta med Azure Blob Storage-klientbiblioteket för Python. Mer information finns i Kom igång med Azure Blob Storage och Python.

Följ de här stegen för att konfigurera projektet om du vill arbeta med kodexemplen i den här artikeln.

Installera paket

Installera följande paket med :pip install

pip install azure-storage-blob azure-identity

Lägga till importinstruktioner

Lägg till följande import-uttryck:

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

Auktorisering

Auktoriseringsmekanismen måste ha de behörigheter som krävs för att lista en blob. För auktorisation med Microsoft Entra ID (rekommenderas) behöver du Azure RBAC:s inbyggda roll Storage Blob Data Reader eller högre. Mer information finns i auktoriseringsvägledningen för REST-API (List Blobs).

Skapa ett klientobjekt

Om du vill ansluta en app till Blob Storage skapar du en instans av BlobServiceClient. I följande exempel visas hur du skapar ett klientobjekt med hjälp av DefaultAzureCredential för auktorisering:

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

Du kan också skapa klientobjekt för specifika containrar eller blobar, antingen direkt eller från objektet BlobServiceClient . Mer information om hur du skapar och hanterar klientobjekt finns i Skapa och hantera klientobjekt som interagerar med dataresurser.

Om alternativ för bloblistning

När du listar blobs från din kod kan du ange många alternativ för att hantera hur resultaten returneras från Azure Storage. Du kan ange hur många resultat som ska returneras i varje resultatuppsättning och sedan hämta efterföljande uppsättningar. Du kan ange ett prefix för att returnera blobar vars namn börjar med det tecknet eller strängen. Du kan lista blobbar i en platt struktur eller i en hierarkisk struktur. En hierarkisk lista returnerar blobar som om de vore ordnade i mappar.

Om du vill visa blobbarna i en container med hjälp av en platt listning anropar du någon av följande metoder:

• ContainerClient.list_blobs (tillsammans med namnet, eventuellt inkludera metadata, taggar och annan information kopplad till varje blob)
• ContainerClient.list_blob_names (returnerar endast blobnamn)

För att lista blobsen i en behållare med en hierarkisk listning, anropa följande metod:

• ContainerClient.walk_blobs (tillsammans med namnet, eventuellt inkludera metadata, taggar och annan information kopplad till varje blob)

Filtrera resultat med ett prefix

Om du vill filtrera listan över blobar anger du en sträng för nyckelordsargumentet name_starts_with . Prefixsträngen kan innehålla ett eller flera tecken. Azure Storage returnerar endast de blobs vars namn börjar med det prefixet.

Flat listning jämfört med hierarkisk lista

Blobar i Azure Storage är ordnade i ett platt paradigm snarare än ett hierarkiskt paradigm (som ett klassiskt filsystem). Du kan dock organisera blobs i virtuella kataloger för att efterlikna en mappstruktur. En virtuell katalog utgör en del av blobens namn och indikeras av avgränsartecknet.

Om du vill organisera blobar i virtuella kataloger använder du ett avgränsartecken i blobnamnet. Standardtecken för avgränsare är ett snedstreck (/), men du kan ange valfritt tecken som avgränsare.

Om du namnger dina blobs med en avgränsare kan du välja att lista blobs hierarkiskt. För en hierarkisk listningsåtgärd returnerar Azure Storage alla virtuella kataloger och blobbar under det överordnade objektet. Du kan anropa listningsåtgärden rekursivt för att korsa hierarkin, ungefär som du skulle gå igenom ett klassiskt filsystem programmatiskt.

Använd en platt lista

Som standard returnerar en liståtgärd blobar i en platt lista. I en enkel listvy organiseras inte blobbar enligt en virtuell katalog.

Följande exempel listar blobsen i den angivna behållaren med en platt listning:

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

Exempelutdata liknar:

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

Du kan också ange alternativ för att filtrera listresultat eller visa mer information. I följande exempel visas blobar och blobtaggar:

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

Exempelutdata liknar:

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'}

Använda en hierarkisk lista

När du anropar en liståtgärd hierarkiskt returnerar Azure Storage de virtuella katalogerna och blobarna på den första nivån i hierarkin.

Om du vill lista blobar hierarkiskt använder du följande metod:

• ContainerClient.walk_blobs

I följande exempel visas blobarna i den angivna containern med hjälp av en hierarkisk lista:

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

Exempelutdata liknar:

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

Visa en lista över blobar asynkront

Azure Blob Storage-klientbiblioteket för Python har stöd för att visa blobar asynkront. Mer information om krav för projektkonfiguration finns i Asynkron programmering.

Följ dessa steg för att lista blobs med hjälp av asynkrona API:er:

1. Lägg till följande importinstruktioner:

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

2. Lägg till kod för att köra programmet genom att använda asyncio.run. Denna funktion kör den passerade coroutinen, main() i detta exempel, och hanterar händelseloopen asyncio . Korutiner deklareras genom att använda async/await-syntaxen. I detta exempel skapar coroutinen main() först den högsta nivån BlobServiceClient genom att använda async with, och anropar sedan metoden som listar blobs. Endast klienten på den översta nivån behöver använda async with, eftersom andra klienter som skapats från den delar samma anslutningspool.

   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. Lägg till kod för att lista blobarna. Följande kodexempel listar blobs genom att använda en platt listning. Koden är densamma som det synkrona exemplet, förutom att metoden deklareras genom att använda async nyckelordet och async for används när metoden anropas 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}")
   

Med denna grundläggande uppsättning på plats kan du implementera andra exempel i denna artikel som coroutines genom att använda asynk/await-syntax.

Listablobbar i Apache Arrow-format (förhandsvisning)

Denna funktion bygger på det befintliga List Blobs API:et. Istället för att använda standard-XML använder den det kompakta, kolumnarformade Apache Arrow-formatet som svarsformat på tråden. Du aktiverar det genom att ställa in ett enda alternativ i containerlisting-anropet. Python SDK avkodar Apache Arrow bakom kulisserna och returnerar fortfarande samma BlobProperties objekt. Denna metod förbättrar listningskapaciteten och minskar klientsidans CPU vid uppräkning av stora containrar. Det bevarar det responsavtal som applikationer är beroende av.

För att begära Apache Arrow-formaterade resultat, ställ in nyckelordargumentet response_format till "arrow" när du anropar ContainerClient.list_blobs eller ContainerClient.list_blob_names. När du använder Apache Arrow-utdata kan du också ställa in start_from och end_before nyckelordsargumenten för att styra intervallet av vägar som returneras.

Följande exempel listar blobsen i en container och begär resultaten i Apache Arrow-format:

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

Resurser

För att lära dig mer om hur man listar blobs genom att använda Azure Blob Storage-klientbiblioteket för Python, se följande resurser.

Kodexempel

• Visa synkrona eller asynkrona kodexempel från denna artikel (GitHub).

REST API-åtgärder

Azure SDKs för Python innehåller bibliotek som bygger ovanpå Azure REST API. Genom att använda dessa bibliotek kan du interagera med REST API-operationer via välbekanta Python-paradigm. Klientbiblioteksmetoderna för att visa blobar använder följande REST API-åtgärd:

• Lista blobs (REST API)

Klientbiblioteksresurser

• Referensdokumentation för klientbibliotek
• Källkod för klientbibliotek
• Paket (PyPi)

Se även

• Räkna upp blobresurser
• Blobversionshantering

Relaterat innehåll

• Den här artikeln är en del av utvecklarguiden för Blob Storage för Python. Mer information finns i den fullständiga listan över utvecklarguideartiklar i Skapa din Python-app.