Libreria client BLOB di Archiviazione di Azure per Python - versione 12.19.0

Articolo
11/07/2023

L'archivio BLOB di Azure è la soluzione di archiviazione di oggetti Microsoft per il cloud. L'archivio BLOB è ottimizzato per l'archiviazione di enormi quantità di dati non strutturati, come dati di testo o binari.

È ideale per:

Invio di immagini o documenti direttamente in un browser
Archiviazione di file per l'accesso distribuito
Streaming di audio e video
Archiviazione di dati per backup e ripristino, ripristino di emergenza e archiviazione
Archiviazione di dati a scopo di analisi da parte di un servizio locale o ospitato in Azure

Introduzione

Prerequisiti

Python 3.7 o versione successiva è necessario per usare questo pacchetto. Per altre informazioni, leggere la pagina relativa ai criteri di supporto delle versioni di Azure SDK per Python.
Per usare questo pacchetto, è necessario avere una sottoscrizione di Azure e un account di archiviazione di Azure .

Installare il pacchetto

Installare la libreria client dei BLOB di Archiviazione di Azure per Python con pip:

pip install azure-storage-blob

Creare un account di archiviazione

Se si vuole creare un nuovo account di archiviazione, è possibile usare il portale di Azure, Azure PowerShell o l'interfaccia della riga di comando di Azure:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Creare il client

La libreria client BLOB di Archiviazione di Azure per Python consente di interagire con tre tipi di risorse: l'account di archiviazione stesso, i contenitori di archiviazione BLOB e i BLOB. L'interazione con queste risorse inizia con un'istanza di un client. Per creare un oggetto client, è necessario l'URL dell'account del servizio BLOB dell'account di archiviazione e una credenziale che consente di accedere all'account di archiviazione:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

Ricerca dell'URL dell'account

È possibile trovare l'URL del servizio BLOB dell'account di archiviazione usando il portale di Azure, Azure PowerShell o l'interfaccia della riga di comando di Azure:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

Tipi di credenziali

Il credential parametro può essere fornito in diversi formati, a seconda del tipo di autorizzazione che si vuole usare:

Per usare una credenziale del token di Azure Active Directory (AAD), specificare un'istanza del tipo di credenziale desiderato ottenuto dalla libreria azure-identity . Ad esempio, DefaultAzureCredential può essere usato per autenticare il client.

Per questa operazione è necessaria una configurazione iniziale:
- Installare azure-identity
- Registrare una nuova applicazione AAD e concedere le autorizzazioni per accedere ad Archiviazione di Azure
- Concedere l'accesso ai dati BLOB di Azure con il controllo degli accessi in base al ruolo nel portale di Azure
- Impostare i valori dell'ID client, dell'ID tenant e del segreto client dell'applicazione AAD come variabili di ambiente: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
Usare le credenziali del token restituite per autenticare il client:
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```

Per usare un token di firma di accesso condiviso (SAS), specificare il token come stringa. Se l'URL dell'account include il token di firma di accesso condiviso, omettere il parametro credential. È possibile generare un token di firma di accesso condiviso dal portale di Azure in "Firma di accesso condiviso" o usare una delle funzioni per creare un token di firma di generate_sas() accesso condiviso per l'account di archiviazione, il contenitore o il BLOB:

from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

Per usare una chiave condivisa dell'account di archiviazione (nota anche come chiave dell'account o chiave di accesso), specificare la chiave come stringa. Questo è disponibile nel portale di Azure nella sezione "Chiavi di accesso" o eseguendo il comando seguente dell'interfaccia della riga di comando di Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Usare la chiave come parametro delle credenziali per autenticare il client:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
Se si usa un URL personalizzato (ovvero l'URL non è in questo formato <my_account_name>.blob.core.windows.net), creare un'istanza del client usando le credenziali seguenti:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
Per usare l'accesso in lettura pubblico anonimo, è sufficiente omettere il parametro delle credenziali.

Creazione del client da un stringa di connessione

A seconda del caso d'uso e del metodo di autorizzazione, è consigliabile inizializzare un'istanza client con un stringa di connessione di archiviazione anziché fornire separatamente l'URL e le credenziali dell'account. A tale scopo, passare il stringa di connessione di archiviazione al metodo della classe del from_connection_string client:

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

Il stringa di connessione all'account di archiviazione è disponibile nel portale di Azure nella sezione "Chiavi di accesso" o eseguendo il comando dell'interfaccia della riga di comando seguente:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Concetti chiave

I componenti seguenti costituiscono il servizio BLOB di Azure:

Account di archiviazione stesso
Contenitore all'interno dell'account di archiviazione
BLOB all'interno di un contenitore

La libreria client BLOB di Archiviazione di Azure per Python consente di interagire con ognuno di questi componenti tramite l'uso di un oggetto client dedicato.

Client

Vengono forniti quattro client diversi per interagire con i vari componenti del servizio BLOB:

BlobServiceClient : questo client rappresenta l'interazione con l'account di archiviazione di Azure stesso e consente di acquisire istanze client preconfigurate per accedere ai contenitori e ai BLOB all'interno. Fornisce operazioni per recuperare e configurare le proprietà dell'account, nonché l'elenco, la creazione e l'eliminazione di contenitori all'interno dell'account. Per eseguire operazioni su un contenitore o un BLOB specifico, recuperare un client usando i get_container_client metodi o get_blob_client .
ContainerClient : questo client rappresenta l'interazione con un contenitore specifico (che non esiste ancora) e consente di acquisire istanze client preconfigurate per accedere ai BLOB all'interno. Fornisce operazioni per creare, eliminare o configurare un contenitore e include operazioni per elencare, caricare ed eliminare i BLOB al suo interno. Per eseguire operazioni su un BLOB specifico all'interno del contenitore, recuperare un client usando il get_blob_client metodo .
BlobClient : questo client rappresenta l'interazione con un BLOB specifico (che non è ancora presente). Fornisce operazioni per caricare, scaricare, eliminare e creare snapshot di un BLOB, nonché operazioni specifiche per tipo di BLOB.
BlobLeaseClient : questo client rappresenta le interazioni di lease con o ContainerClientBlobClient. Fornisce operazioni per acquisire, rinnovare, rilasciare, modificare e interrompere un lease in una risorsa specificata.

Client asincroni

Questa libreria include un'API asincrona completa supportata in Python 3.5+. Per usarlo, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di azure-core .

I client e le credenziali asincroni devono essere chiusi quando non sono più necessari. Questi oggetti sono gestori di contesti asincroni e definiscono metodi asincroni close .

Tipi di BLOB

Dopo aver inizializzato un client, è possibile scegliere tra i diversi tipi di BLOB:

I BLOB in blocchi archiviano dati di testo e binari, fino a circa 4,75 TiB. I BLOB in blocchi sono costituiti da blocchi di dati che possono essere gestiti singolarmente
I BLOB di aggiunta sono costituiti da blocchi, analogamente ai BLOB in blocchi, ma sono ottimizzati per le operazioni di aggiunta. I BLOB di accodamento sono ideali per scenari come la registrazione dei dati dalle macchine virtuali
I BLOB di pagine archiviano file ad accesso casuale con dimensioni fino a 8 TiB. I BLOB di pagine archiviano i file del disco rigido virtuale (VHD) e fungono da dischi per le macchine virtuali di Azure

Esempio

Le sezioni seguenti forniscono diversi frammenti di codice relativi ad alcune delle attività BLOB di archiviazione più comuni, tra cui:

Creare un contenitore
Caricamento di un BLOB
Download di un BLOB
Enumerazione di BLOB

Si noti che è necessario creare un contenitore prima di caricare o scaricare un BLOB.

Creare un contenitore

Creare un contenitore da cui è possibile caricare o scaricare BLOB.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

Usare il client asincrono per caricare un BLOB

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Caricamento di un BLOB

Caricare un BLOB nel contenitore

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Usare il client asincrono per caricare un BLOB

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Download di un BLOB

Scaricare un BLOB dal contenitore

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

Scaricare un BLOB in modo asincrono

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Enumerazione di BLOB

Elencare i BLOB nel contenitore

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

Elencare i BLOB in modo asincrono

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

Configurazione facoltativa

Argomenti di parole chiave facoltativi che possono essere passati al client e a livello di operazione.

Configurazione dei criteri di ripetizione

Usare gli argomenti della parola chiave seguenti quando si crea un'istanza di un client per configurare i criteri di ripetizione dei tentativi:

retry_total (int): numero totale di tentativi consentiti. Ha la precedenza su altri conteggi. retry_total=0 Passare se non si vuole riprovare alle richieste. Il valore predefinito è 10.
retry_connect (int): numero di errori relativi alla connessione da ritentare. Il valore predefinito è 3.
retry_read (int): numero di tentativi di ripetizione degli errori di lettura. Il valore predefinito è 3.
retry_status (int): numero di tentativi per i codici di stato non corretti. Il valore predefinito è 3.
retry_to_secondary (bool): indica se la richiesta deve essere ritentata a secondaria, se possibile. Questa opzione deve essere abilitata solo per gli account RA-GRS e i dati potenzialmente non aggiornati possono essere gestiti. Il valore predefinito è False.

Configurazione della crittografia

Usare gli argomenti della parola chiave seguenti quando si crea un'istanza di un client per configurare la crittografia:

require_encryption (bool): se impostata su True, imposterà che gli oggetti siano crittografati e decrittografati.
encryption_version (str): specifica la versione della crittografia da usare. Le opzioni correnti sono '2.0' o '1.0' e il valore predefinito è '1.0'. La versione 1.0 è deprecata ed è consigliabile usare la versione 2.0.
key_encryption_key (oggetto): chiave-crittografia-chiave fornita dall'utente. L'istanza deve implementare i metodi seguenti:
- wrap_key(key)esegue il wrapping della chiave specificata usando un algoritmo di scelta dell'utente.
- get_key_wrap_algorithm()--restituisce l'algoritmo utilizzato per eseguire il wrapping della chiave simmetrica specificata.
- get_kid()--restituisce un ID chiave stringa per questa chiave-crittografia-chiave.
key_resolver_function (chiamabile): resolver di chiavi fornito dall'utente. Usa la stringa kid per restituire una chiave di crittografia chiave che implementa l'interfaccia definita in precedenza.

Altra configurazione client/per operazione

Altri argomenti di parole chiave di configurazione facoltativi che possono essere specificati nel client o per ogni operazione.

Argomenti di parole chiave client:

connection_timeout (int): numero di secondi in cui il client attenderà di stabilire una connessione al server. Il valore predefinito è 20 secondi.
read_timeout (int): numero di secondi in cui il client attenderà, tra le operazioni di lettura consecutive, una risposta dal server. Si tratta di un timeout a livello di socket e non è influenzato dalle dimensioni complessive dei dati. I timeout di lettura lato client verranno ritentati automaticamente. Il valore predefinito è 60 secondi.
transport (Any): trasporto fornito dall'utente per inviare la richiesta HTTP.

Argomenti per parola chiave per operazione:

raw_response_hook (chiamabile): il callback specificato usa la risposta restituita dal servizio.
raw_request_hook (chiamabile): il callback specificato usa la richiesta prima di essere inviata al servizio.
client_request_id (str): identificazione specificata dall'utente facoltativo della richiesta.
user_agent (str): aggiunge il valore personalizzato all'intestazione user-agent da inviare con la richiesta.
logging_enable (bool): abilita la registrazione a livello DI DEBUG. Il valore predefinito è False. Può anche essere passato a livello di client per abilitarlo per tutte le richieste.
logging_body (bool): abilita la registrazione del corpo della richiesta e della risposta. Il valore predefinito è False. Può anche essere passato a livello di client per abilitarlo per tutte le richieste.
intestazioni (dict): passare intestazioni personalizzate come coppie chiave-valore. Ad esempio headers={'CustomValue': value}

Risoluzione dei problemi

Generale

I client BLOB di archiviazione generano eccezioni definite in Azure Core.

Questo elenco può essere usato per fare riferimento alle eccezioni generate. Per ottenere il codice di errore specifico dell'eccezione, usare l'attributo error_code , ad esempio exception.error_code.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata a livello di DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate, può essere abilitata in un client con l'argomento logging_enable :

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

service_client.get_service_stats(logging_enable=True)

Passaggi successivi

Altro codice di esempio

Introduzione agli esempi di BLOB.

Sono disponibili diversi esempi di PYTHON SDK per BLOB di archiviazione nel repository GitHub dell'SDK. Questi esempi forniscono codice di esempio per scenari aggiuntivi comunemente rilevati durante l'uso dei BLOB di archiviazione:

blob_samples_container_access_policy.py (versione asincrona): esempi per impostare i criteri di accesso:
- Configurare i criteri di accesso per il contenitore
blob_samples_hello_world.py (versione asincrona): esempi di attività comuni del BLOB di archiviazione:
- Configurare un contenitore
- Creare un blocco, una pagina o un BLOB di accodamento
- Caricare i BLOB
- Scaricare BLOB
- Eliminare BLOB
blob_samples_authentication.py (versione asincrona): esempi per l'autenticazione e la creazione del client:
- Da un stringa di connessione
- Da una chiave di accesso condiviso
- Da un token di firma di accesso condiviso
- Da Active Directory
blob_samples_service.py (versione asincrona): esempi per l'interazione con il servizio BLOB:
- Ottenere le informazioni sull'account
- Ottenere e impostare le proprietà del servizio
- Ottenere le statistiche del servizio
- Creare, elencare ed eliminare contenitori
- Ottenere il client BLOB o contenitore
blob_samples_containers.py (versione asincrona): esempi per l'interazione con i contenitori:
- Creare un contenitore ed eliminare contenitori
- Impostare i metadati nei contenitori
- Ottenere le proprietà del contenitore
- Acquisire un lease nel contenitore
- Impostare un criterio di accesso in un contenitore
- Caricare, elencare, eliminare BLOB nel contenitore
- Ottenere il client BLOB per interagire con un BLOB specifico
blob_samples_common.py (versione asincrona): esempi comuni a tutti i tipi di BLOB:
- Creare uno snapshot
- Eliminare uno snapshot del BLOB
- Eliminazione temporanea di un BLOB
- Annullare l'eliminazione di un BLOB
- Acquisire un lease in un BLOB
- Copiare un BLOB da un URL
blob_samples_directory_interface.py : esempi di interfacciamento con l'archiviazione BLOB come se fosse una directory in un file system:
- Copiare (caricare o scaricare) un singolo file o una directory
- Elencare file o directory a livello singolo o ricorsivo
- Eliminare un singolo file o eliminare in modo ricorsivo una directory

Documentazione aggiuntiva

Per una documentazione più completa sull'archiviazione BLOB di Azure, vedere la documentazione sull'archiviazione BLOB di Azure in docs.microsoft.com.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.