Elencare i blob con Python

Questo articolo mostra come elencare i blob utilizzando la libreria client Archiviazione di Azure per Python.

Per imparare a elencare blob utilizzando API asincrone, vedi Elenca blob asincroni.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Account di archiviazione di Azure: creare un account di archiviazione
• Python 3.8+

Configurazione dell'ambiente

Se non si dispone di un progetto esistente, questa sezione illustra come configurare un progetto per l’uso con la libreria client di Archiviazione BLOB di Azure per Python. Per ulteriori informazioni, vedi Introduzione all'archiviazione BLOB di Azure e a Python.

Per usare gli esempi di codice in questo articolo, seguire questa procedura per configurare il progetto.

Installare i pacchetti

Installare i pacchetti seguenti tramite pip install:

pip install azure-storage-blob azure-identity

Aggiungere le istruzioni di importazione

Aggiungere le istruzioni import seguenti:

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

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per elencare un blob. Per l'autorizzazione tramite Microsoft Entra ID (consigliato), è necessario il ruolo predefinito di Azure RBAC Storage Blob Data Reader o un ruolo superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per List Blobs (API REST).

Creare un oggetto client

Per connettere un'app all'archiviazione di BLOB, creare un'istanza di BlobServiceClient. Nell'esempio seguente viene illustrato come creare un oggetto client usando DefaultAzureCredential per l'autorizzazione:

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

È anche possibile creare oggetti client per contenitori o BLOB specifici, direttamente o dall'oggetto BlobServiceClient. Per altre informazioni sulla creazione e la gestione di oggetti client, vedere Creare e gestire oggetti client che interagiscono con le risorse dati.

Informazioni sulle opzioni di elenco dei blob

Quando elenchi i blob dal tuo codice, puoi specificare molte opzioni per gestire come i risultati tornano da Archiviazione di Azure. È possibile specificare il numero di risultati da restituire in ogni set di risultati e quindi recuperare i set successivi. È possibile specificare un prefisso per restituire i BLOB i cui nomi iniziano con tale carattere o stringa. Puoi elencare i blob in una struttura semplice o gerarchica. Un elenco gerarchico restituisce i BLOB come se fossero organizzati in cartelle.

Per elencare i BLOB in un contenitore con un elenco semplice, chiamare uno dei metodi seguenti:

• ContainerClient.list_blobs (insieme al nome, include opzionalmente metadati, tag e altre informazioni associate a ogni blob)
• ContainerClient.list_blob_names (restituisce solo il nome del BLOB)

Per elencare i blob in un contenitore usando un elenco gerarchico, si chiama il seguente metodo:

• ContainerClient.walk_blobs (insieme al nome, includere opzionalmente metadati, tag e altre informazioni associate a ogni blob)

Filtrare i risultati con un prefisso

Per filtrare l'elenco dei BLOB, specificare una stringa per l'argomento della parola chiave name_starts_with. La stringa di prefisso può includere uno o più caratteri. Archiviazione di Azure restituisce solo i blob i cui nomi iniziano con quel prefisso.

Confronto tra elenco semplice e gerarchico

I BLOB in Archiviazione di Azure sono organizzati secondo un paradigma semplice, anziché gerarchico (come un file system classico). Tuttavia, puoi organizzare i blob in directory virtuali per imitare una struttura di cartelle. Una directory virtuale costituisce parte del nome del BLOB ed è indicata dal carattere di delimitazione.

Per organizzare i BLOB in directory virtuali, usare un carattere di delimitazione nel nome del BLOB. Il delimitatore predefinito è la barra (/), ma è possibile specificare qualsiasi carattere.

Se dai un nome ai tuoi blob usando un delimiter, puoi scegliere di elencarli in modo gerarchico. Per un'operazione di elencazione gerarchica, Archiviazione di Azure restituisce tutte le directory virtuali e i blob presenti sotto l'oggetto padre. È possibile chiamare l'operazione di elenco in modo ricorsivo per attraversare la gerarchia in modo analogo a come si attraverserebbe un file system classico a livello di codice.

Usare un elenco semplice

Per impostazione predefinita, un'operazione di elenco restituisce i BLOB in un elenco semplice. In un elenco semplice, i BLOB non sono organizzati in base alla directory virtuale.

Il seguente esempio elenca i blob nel contenitore specificato usando un elenco piatto:

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

L'esempio di output è simile al seguente:

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

Puoi anche specificare opzioni per filtrare i risultati delle liste o mostrare maggiori informazioni. L'esempio seguente elenca i blob e i relativi tag:

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

L'esempio di output è simile al seguente:

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

Usare un elenco gerarchico

Quando si chiama un'operazione di elencazione in modo gerarchico, Archiviazione di Azure restituisce le directory virtuali e i blob al primo livello della gerarchia.

Per elencare i BLOB in modo gerarchico, usare il metodo seguente:

• ContainerClient.walk_blobs

L'esempio seguente elenca i BLOB nel contenitore specificato usando un elenco gerarchico:

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

L'esempio di output è simile al seguente:

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

Elenco dei blob in modo asincrono

La libreria client di Archiviazione BLOB di Azure per Python supporta l’elencazione dei BLOB in modo asincrono. Per altre informazioni sui requisiti di configurazione del progetto, consultare Programmazione asincrona.

Segui questi passaggi per elencare i blob usando API asincrone:

1. Aggiungere le seguenti istruzioni di importazione:

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

2. Aggiungi codice per eseguire il programma usando asyncio.run. Questa funzione esegue la coroutine passata, main() in questo esempio, e gestisce il asyncio ciclo eventi. Le coroutine vengono dichiarate utilizzando la sintassi async/await. In questo esempio, la main() coroutine crea prima il livello BlobServiceClient superiore usando async with, poi chiama il metodo che elenca i blob. Solo il client di primo livello deve usare async with, come altri client creati da esso condividono lo stesso pool di connessioni.

   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. Aggiungere codice per elencare i BLOB. Il seguente esempio di codice elenca i blob utilizzando un elenco piatto. Il codice è lo stesso dell'esempio sincrono, tranne per il fatto che il metodo viene dichiarato usando la async parola chiave e async for viene usato quando si chiama il list_blobs metodo.

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

Con questa configurazione di base, puoi implementare altri esempi in questo articolo come coroutine usando la sintassi async/await.

Elenco dei blob in formato Apache Arrow (anteprima)

Questa funzionalità è costruita sull'API esistente List Blobs . Invece di usare l'XML predefinito, utilizza il formato compatto e columnare Apache Arrow come formato di risposta sul filo. Lo si abilita impostando una singola opzione nella chiamata di elenco dei contenitori. L'SDK Python decodifica Apache Arrow dietro le quinte e restituisce comunque gli stessi BlobProperties oggetti. Questo approccio migliora la velocità di elencazione e riduce l'utilizzo della CPU lato client durante l'enumerazione di contenitori di grandi dimensioni. Preserva il contratto di risposta su cui si basano le domande.

Per richiedere risultati formattati con Apache Arrow, imposta l'argomento response_format della parola chiave su "arrow" quando chiami ContainerClient.list_blobs o ContainerClient.list_blob_names. Quando utilizzi l'output Apache Arrow, puoi anche impostare gli argomenti con nome start_from e end_before per controllare la gamma di percorsi restituiti.

Il seguente esempio elenca i blob in un contenitore e richiede i risultati in formato 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)

Risorse

Per saperne di più su come elencare i blob utilizzando la libreria client Archiviazione BLOB di Azure per Python, consulta le seguenti risorse.

Esempi di codice

• Visualizza esempi di codice sincrono o asincrono da questo articolo (GitHub).

Operazioni dell'API REST

L'Azure SDK per Python contiene librerie che si costruiscono sopra l'API REST di Azure. Utilizzando queste librerie, puoi interagire con le operazioni API REST attraverso paradigmi Python familiari. I metodi della libreria client per elencare i BLOB usano l'operazione API REST seguente:

• List Blobs (API REST)

Risorse della libreria client

• Documentazione di riferimento della libreria client
• Codice sorgente della libreria client
• Pacchetto (PyPi)

Vedi anche

• Enumerare le risorse BLOB
• Controllo delle versioni per i BLOB

Contenuto correlato

• Questo articolo fa parte della Guida per sviluppatori di Archiviazione BLOB per Python. Per altre informazioni, vedere l’elenco completo degli articoli della Guida per sviluppatori in Creare la propria app Python.