Avvio rapido: libreria client di Archiviazione BLOB di Azure per Python

Nota

L'opzione Compila da zero mostra i passaggi da seguire durante il processo di creazione di un nuovo progetto, l'installazione di pacchetti, la scrittura del codice e l'esecuzione di un'app console di base. Questo approccio è consigliato se si vogliono comprendere tutti i dettagli relativi alla creazione di un'app che si connette all'Archiviazione BLOB di Azure. Se si preferisce automatizzare le attività di distribuzione e iniziare con un progetto completato, scegliere Inizia con un modello.

Nota

L'opzione Inizia con un modello usa Azure Developer CLI per automatizzare le attività di distribuzione e inizia con un progetto completato. Questo approccio è consigliato se si vuole esplorare il codice il più rapidamente possibile, senza eseguire le attività di configurazione. Se si preferisce istruzioni dettagliate per compilare l'app, scegliere Compila da zero.

Introduzione alla libreria client di Archiviazione BLOB di Azure per Python per gestire BLOB e contenitori.

In questo articolo, vengono illustrati i passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

In questo articolo si usa Azure Developer CLI per distribuire le risorse di Azure ed eseguire un'app console completata con pochi comandi.

Documentazione di riferimento API | Codice sorgente della libreria | Pacchetto (PyPi) | Esempi

Questo video illustra come iniziare a usare la libreria client di Archiviazione BLOB di Azure per Python.

I passaggi del video sono descritti anche nelle sezioni seguenti.

Prerequisiti

Configurazione

Questa sezione illustra come preparare un progetto da usare con la libreria client di Archiviazione BLOB di Azure per Python.

Creare il progetto

Creare un'applicazione Python denominata blob-quickstart.

  1. In una finestra della console, ad esempio PowerShell o Bash, creare una nuova directory per il progetto:

    mkdir blob-quickstart

  2. Passare alla directory blob-quickstart appena creata:

    cd blob-quickstart

Installare i pacchetti

Nella directory del progetto installare i pacchetti per le librerie client Archiviazione BLOB di Azure e Azure Identity usando il comando pip install. È necessario il pacchetto azure-identity per le connessioni senza password ai servizi di Azure.

pip install azure-storage-blob azure-identity

Configurare il framework dell'app

Nella directory del progetto seguire questa procedura per creare la struttura di base dell'app:

  1. Aprire un nuovo file di testo nell'editor del codice.
  2. Aggiungere import istruzioni, creare la struttura per il programma e includere la gestione delle eccezioni di base, come illustrato nell'esempio seguente.
  3. Salvare il nuovo file come blob_quickstart.py nella directory blob-quickstart.
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

Quando si installa Azure Developer CLI, è possibile creare un account di archiviazione ed eseguire il codice di esempio con pochi comandi. È possibile eseguire il progetto nell'ambiente di sviluppo locale o in un DevContainer.

Inizializzare il modello Azure Developer CLI e distribuire le risorse

Da una directory vuota seguire questa procedura per inizializzare il modello azd, effettuare il provisioning delle risorse di Azure e iniziare a usare il codice:

  • Clona le risorse del repository quickstart da GitHub e inizializza il modello localmente:

    azd init --template blob-storage-quickstart-python

    Vengono richieste le informazioni seguenti:

    • Nome dell'ambiente: Azure Developer CLI usa questo valore come prefisso per tutte le risorse di Azure che crea. Il nome deve essere univoco in tutte le sottoscrizioni Azure e deve avere una lunghezza compresa tra 3 e 24 caratteri. Il nome può contenere solo lettere minuscole e numeri.

  • Accedere a Azure:

    azd auth login

  • Effettuare il provisioning e distribuire le risorse in Azure:

    azd up

    Vengono richieste le informazioni seguenti:

    • Sottoscrizione: sottoscrizione di Azure in cui vengono distribuite le risorse.
    • Località: l'area geografica di Azure in cui vengono distribuite le risorse.

    Il completamento della distribuzione può richiedere alcuni minuti. L'output del azd up comando include il nome dell'account di archiviazione appena creato, necessario in un secondo momento per eseguire il codice.

Eseguire il codice di esempio

A questo punto, le risorse sono state distribuite in Azure e il codice è quasi pronto per l'esecuzione. Seguire questa procedura per installare i pacchetti, aggiornare il nome dell'account di archiviazione nel codice ed eseguire l'app console di esempio:

  • Installare pacchetti: nella directory locale installare i pacchetti per le librerie client Archiviazione BLOB di Azure e Azure Identity eseguendo il comando seguente: pip install azure-storage-blob azure-identity
  • Aggiornare il nome dell'account di archiviazione: nella directory locale modificare il file denominato blob_quickstart.py. Trovare il segnaposto <storage-account-name> e sostituirlo con il nome effettivo dell'account di archiviazione creato dal comando azd up. Salvare le modifiche.
  • Eseguire il progetto: eseguire il comando seguente per eseguire l'app: python blob_quickstart.py.
  • Osserva l'output: l'app crea un file di test nella cartella locale data e lo carica in un contenitore nell'account di archiviazione. L'esempio elenca quindi i BLOB presenti nel contenitore e scarica il file con un nuovo nome per consentire il confronto tra i nuovi file e quelli precedenti.

Per altre informazioni sul funzionamento del codice di esempio, vedere Esempi di codice.

Al termine del test del codice, vedere la sezione Pulire le risorse per eliminare le risorse create dal comando azd up.

Modello a oggetti

Il servizio Archiviazione BLOB di Azure è ottimizzato per archiviare enormi quantità di dati non strutturati. I dati non strutturati sono dati che non seguono una definizione o un modello di dati specifico, ad esempio dati di testo o binari. L'archiviazione BLOB offre tre tipi di risorse:

  • L'account di archiviazione
  • Un contenitore nell'account di archiviazione
  • Un BLOB in un contenitore

Il diagramma seguente mostra la relazione tra queste risorse:

Screenshot dell'architettura di archiviazione BLOB che mostra un account di archiviazione, un contenitore e BLOB.

Per interagire con queste risorse, usare le classi Python seguenti:

  • BlobServiceClient: usare la classe BlobServiceClient per lavorare con risorse e contenitori BLOB Archiviazione di Azure.
  • ContainerClient: usare la classe ContainerClient per usare i contenitori Archiviazione di Azure e i relativi BLOB.
  • BlobClient: usare la classe BlobClient per usare i BLOB Archiviazione di Azure.

Esempi di codice

Questi frammenti di codice di esempio illustrano come eseguire le attività seguenti con la libreria client di Archiviazione BLOB di Azure per Python:

Nota

Il modello Azure Developer CLI include un file con codice di esempio già disponibile. Negli esempi seguenti vengono forniti dettagli per ogni parte del codice di esempio. Il modello implementa il metodo di autenticazione senza password consigliato, come descritto nella sezione Eseguire l'autenticazione in Azure. Il metodo della stringa di connessione viene visualizzato come alternativa, ma non viene usato nel modello e non è consigliato per il codice di produzione.

Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB

Le richieste dell'applicazione all'Archiviazione BLOB di Azure devono essere autorizzate. L'uso della classe DefaultAzureCredential fornita dalla libreria client Azure Identity è l'approccio consigliato per implementare connessioni senza password ai servizi di Azure nel proprio codice, incluso gestione rete virtuale di Azure.

È anche possibile autorizzare le richieste all'Archiviazione BLOB di Azure usando la chiave di accesso dell'account. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai la chiave di accesso in una posizione non sicura. Chiunque abbia la chiave di accesso può autorizzare richieste all'account di archiviazione e di fatto ha accesso a tutti i dati. DefaultAzureCredential offre maggiore sicurezza e semplicità di gestione rispetto alla chiave dell'account per consentire l'autenticazione senza password. Entrambe le opzioni sono mostrate nell'esempio seguente.

DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

È possibile trovare l'ordine e le posizioni in cui DefaultAzureCredential cerca le credenziali nella panoramica della libreria delle identità Azure.

Ad esempio, l'app può eseguire l'autenticazione usando le credenziali di accesso interfaccia della riga di comando di Azure durante lo sviluppo in locale. L'app può quindi usare un'identità managed una volta distribuita in Azure. Per questa transizione non sono necessarie modifiche al codice.

Assegnare ruoli all'account utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. Per leggere e scrivere i dati dei BLOB, è necessario disporre del ruolo Storage Blob Data Contributor. Per assegnarti questo ruolo, devi disporre del ruolo Amministratore dell'accesso utente oppure di un altro ruolo che includa l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per ulteriori informazioni sul ruolo di Collaboratore ai dati BLOB, vedere Collaboratore ai dati BLOB. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere Comprendere l'ambito per Azure RBAC.

In questo scenario, assegnerai le autorizzazioni al tuo account utente, limitate all'account di archiviazione, per seguire il Principio del privilegio minimo. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo Storage Blob Data Contributor al tuo account utente, che fornisce l'accesso in lettura e scrittura ai dati dei BLOB nel tuo account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nel portale di Azure, individua il tuo account di archiviazione tramite la barra di ricerca principale o il menu di navigazione a sinistra.

  2. Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM), selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    Screenshot che mostra come assegnare un ruolo.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. In questo esempio, cercare Storage Blob Data Contributor e selezionare il risultato corrispondente, quindi scegliere Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain) e quindi scegliere Selezionare nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi Rivedi e assegna di nuovo per completare il processo.

Accedere e connettere il codice dell'app a Azure usando DefaultAzureCredential

Per autorizzare l'accesso ai dati nell'account di archiviazione, seguire questa procedura:

  1. Assicurati di essere autenticato con lo stesso account Microsoft Entra a cui hai assegnato il ruolo nel tuo account di archiviazione. È possibile eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure, Visual Studio Code o Azure PowerShell.

    Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

    az login

  2. Per usare DefaultAzureCredential, assicurarsi che il pacchetto azure-identity sia installatoe che la classe venga importata:

    from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

  3. Aggiungere questo codice all'interno del blocco try. Quando il codice viene eseguito sulla workstation locale, DefaultAzureCredential usa le credenziali dello sviluppatore dello strumento con la priorità più alta a cui hai effettuato l'accesso per autenticarsi ad Azure. Esempi di questi strumenti includono l'interfaccia della riga di comando di Azure o Visual Studio Code.

    account_url = "https://<storageaccountname>.blob.core.windows.net"
default_credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=default_credential)

  4. Aggiorna il nome dell'account di archiviazione nell'URI dell'oggetto BlobServiceClient. È possibile trovare il nome dell'account di archiviazione nella pagina di panoramica del portale di Azure.

    Screenshot della pagina del portale di Azure che evidenzia il nome dell'account di archiviazione.

    Nota

    Quando viene distribuito in Azure, lo stesso codice può autorizzare le richieste a Archiviazione di Azure da un'applicazione in esecuzione in Azure. Tuttavia, è necessario abilitare l'identità gestita nell'app in Azure. Configurare quindi l'account di archiviazione per consentire la connessione a tale identità gestita. Per istruzioni dettagliate sulla configurazione di questa connessione tra i servizi di Azure, vedere l'esercitazione Autenticazione dalle app ospitate in Azure.

Creazione di un contenitore

Creare un nuovo contenitore nell'account di archiviazione chiamando il metodo create_container sull'oggetto blob_service_client. In questo esempio il codice aggiunge un valore GUID al nome del contenitore per assicurarsi che sia univoco.

Aggiungere questo codice alla fine del blocco try:

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

Per altre informazioni sulla creazione di un contenitore e per esplorare altri esempi di codice, vedere Creare un contenitore BLOB con Python.

Importante

I nomi dei contenitori devono essere in minuscolo. Per altre informazioni sulla denominazione di contenitori e BLOB, vedere Naming and Referencing Containers, Blobs, and Metadata (Assegnazione di nome e riferimento a contenitori, BLOB e metadati).

Carica i blob in un contenitore

Caricare un BLOB in un contenitore usando upload_blob. Il codice di esempio crea un file di testo nella directory dati locale da caricare nel contenitore.

Aggiungere questo codice alla fine del blocco try:

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

Per altre informazioni sul caricamento di BLOB e per esplorare altri esempi di codice, vedere Upload a BLOB con Python.

Elencare i BLOB in un contenitore

Elencare i BLOB presenti nel contenitore chiamando il metodo list_blobs. In questo caso, al contenitore è stato aggiunto un solo blob, quindi l'operazione di elencazione restituisce solo quel blob.

Aggiungere questo codice alla fine del blocco try:

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

Per altre informazioni sull'elenco di BLOB e per esplorare altri esempi di codice, vedere List BLOB con Python.

Scarica blob

Scaricare il BLOB creato in precedenza chiamando il metodo download_blob. Il codice di esempio aggiunge il suffisso "DOWNLOAD" al nome del file in modo da consentire la visualizzazione di entrambi i file nel file system locale.

Aggiungere questo codice alla fine del blocco try:

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

Per altre informazioni sul download di BLOB e per esplorare altri esempi di codice, vedere Scaricare un BLOB con Python.

Eliminare un contenitore

Il codice seguente pulisce le risorse create dall'app rimuovendo l'intero contenitore usando il metodo delete_container . Se si desidera, è anche possibile eliminare i file locali.

L'app si interrompe in attesa dell'input dell'utente chiamando input() prima di eliminare il blob, il contenitore e i file locali. Verificare che le risorse siano state create correttamente prima dell'eliminazione.

Aggiungere questo codice alla fine del blocco try:

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

Per altre informazioni sull'eliminazione di un contenitore e sull'esplorazione di altri esempi di codice, vedere Delete e ripristinare un contenitore BLOB con Python.

Eseguire il codice

Questa app crea un file di test nella cartella locale e lo carica nell'Archiviazione BLOB di Azure. L'esempio elenca quindi i BLOB nel contenitore e scarica il file con un nuovo nome. È possibile confrontare i file vecchi e nuovi.

Passare alla directory contenente il file blob_quickstart.py ed eseguire il comando seguente python per eseguire l'app:

python blob_quickstart.py

L'output dell'app è simile all'esempio seguente (i valori UUID omessi per la leggibilità):

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Prima di iniziare il processo di pulizia, controllare che nella cartella dati siano presenti due file. È possibile confrontarli e vedere che sono identici.

Pulire le risorse

Dopo aver verificato i file e aver completato il test, premere INVIO per eliminare i file di test insieme al contenitore creato nell'account di archiviazione. È anche possibile usare l'interfaccia della riga di comando di Azure per eliminare le risorse.

Al termine dell'avvio rapido, pulire le risorse create eseguendo il comando seguente:

azd down

Verrà richiesto di confermare l'eliminazione delle risorse. Immettere y per confermare.

Passaggio successivo

Esempi e guide per sviluppatori di Archiviazione di Azure per Python

  • Last updated on