Libreria client code di Archiviazione di Azure per Python - versione 12.9.0

Articolo
12/05/2023

Il servizio di archiviazione di accodamento di Azure consente di archiviare grandi quantità di messaggi ai quali è possibile accedere da qualsiasi parte del mondo mediante chiamate autenticate tramite HTTP o HTTPS. Un singolo messaggio di coda può essere fino a 64 KiB di dimensioni e una coda può contenere milioni di messaggi, fino al limite totale di capacità di un account di archiviazione.

Di seguito sono riportati gli utilizzi più comuni per il servizio di archiviazione di accodamento.

Creazione di un backlog di lavoro da elaborare in modo asincrono
Passaggio di messaggi tra parti diverse di un'applicazione distribuita

Introduzione

Prerequisiti

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

Installare il pacchetto

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

pip install azure-storage-queue

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 code di archiviazione di Azure per Python consente di interagire con tre tipi di risorse: l'account di archiviazione stesso, le code e i messaggi. L'interazione con queste risorse inizia con un'istanza di un client. Per creare un oggetto client, sarà necessario l'URL dell'endpoint del servizio di coda dell'account di archiviazione e una credenziale che consente di accedere all'account di archiviazione:

from azure.storage.queue import QueueServiceClient

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

Ricerca dell'URL dell'account

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

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

Tipi di credenziali

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

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 delle credenziali. È possibile generare un token di firma di accesso condiviso dal portale di Azure in "Firma di accesso condiviso" o usare una delle generate_sas() funzioni per creare un token sas per l'account di archiviazione o la coda:

from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, 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),
    start=datetime.utcnow(),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

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

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Usare la chiave come parametro delle credenziali per autenticare il client:
```
from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")
```
Per usare una credenziale token di Azure Active Directory (AAD), specificare un'istanza del tipo di credenziali desiderato ottenuto dalla libreria azure-identity . Ad esempio, DefaultAzureCredential può essere usato per autenticare il client.

Questa operazione richiede 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 della coda di Azure con 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.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )
```

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 l'archiviazione stringa di connessione al metodo di classe del from_connection_string client:

from azure.storage.queue import QueueServiceClient

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

Il stringa di connessione per l'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 code di Azure:

L'account di archiviazione stesso
Coda all'interno dell'account di archiviazione che contiene un set di messaggi
Messaggio all'interno di una coda, in qualsiasi formato, fino a 64 KiB

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

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 gestioni contesto asincrone e definiscono metodi asincroni close .

Client

Vengono forniti due client diversi per interagire con i vari componenti del servizio code:

QueueServiceClient : questo client rappresenta l'interazione con l'account di archiviazione di Azure stesso e consente di acquisire istanze client preconfigurate per accedere alle code all'interno. Fornisce operazioni per recuperare e configurare le proprietà dell'account e l'elenco, creare ed eliminare code all'interno dell'account. Per eseguire operazioni su una coda specifica, recuperare un client usando il get_queue_client metodo .
QueueClient : questo client rappresenta l'interazione con una coda specifica (che non esiste ancora). Fornisce operazioni per creare, eliminare o configurare una coda e include operazioni da inviare, ricevere, visualizzare, eliminare e aggiornare i messaggi all'interno di esso.

Messaggi

Send : aggiunge un messaggio alla coda e imposta facoltativamente un timeout di visibilità per il messaggio.
Ricezione : recupera un messaggio dalla coda e lo rende invisibile ad altri consumer.
Anteprima rapida: recupera un messaggio dalla parte anteriore della coda, senza modificare la visibilità del messaggio.
Aggiornamento: Aggiornamenti il timeout di visibilità di un messaggio e/o del contenuto del messaggio.
Elimina : elimina un messaggio specificato dalla coda.
Cancella : cancella tutti i messaggi dalla coda.

Esempio

Le sezioni seguenti forniscono diversi frammenti di codice che coprono alcune delle attività più comuni della coda di archiviazione, tra cui:

Creazione di una coda
Invio di messaggi
Ricezione di messaggi

Creazione di una coda

Creare una coda nell'account di archiviazione

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.create_queue()

Usare il client asincrono per creare una coda

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await queue.create_queue()

Invio di messaggi

Inviare messaggi alla coda

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

Inviare messaggi in modo asincrono

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

Ricezione di messaggi

Ricevere ed elaborare messaggi dalla coda

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

Ricevere ed elaborare i messaggi in batch

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

Ricevere ed elaborare i messaggi in modo asincrono

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

Configurazione facoltativa

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

Configurazione dei criteri di ripetizione dei tentativi

Usare gli argomenti delle parole 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 da consentire. Ha la precedenza su altri conteggi. retry_total=0 Passare se non si vuole ripetere i tentativi sulle richieste. Il valore predefinito è 10.
retry_connect (int): numero di errori correlati alla connessione da ripetere. Il valore predefinito è 3.
retry_read (int): numero di tentativi di ripetizione degli errori di lettura. Il valore predefinito è 3.
retry_status (int): quante volte ripetere i tentativi sui codici di stato non valido. Il valore predefinito è 3.
retry_to_secondary (bool): se la richiesta deve essere riprovata a secondaria, se in grado. Questa opzione deve essere abilitata solo per gli account RA-GRS e i dati potenzialmente non aggiornati possono essere gestiti. Il valore predefinito è False.

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 della coda 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.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
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 = QueueServiceClient.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 code.

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

queue_samples_hello_world.py (versione asincrona): esempi disponibili in questo articolo:
- Creazione del client
- Creare una coda
- Inviare messaggi
- Ricevere messaggi
queue_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 Azure Active Directory
queue_samples_service.py (versione asincrona): esempi per l'interazione con il servizio di accodamento:
- Ottenere e impostare le proprietà del servizio
- Elencare le code in un account di archiviazione
- Creare ed eliminare una coda dal servizio
- Ottenere QueueClient
queue_samples_message.py (versione asincrona): esempi per l'uso di code e messaggi:
- Impostare un criterio di accesso
- Ottenere e impostare i metadati della coda
- Inviare e ricevere messaggi
- Eliminare i messaggi specificati e cancellare tutti i messaggi
- Anteprima rapida e aggiornare i messaggi

Documentazione aggiuntiva

Per una documentazione più completa sull'archiviazione code di Azure, vedere la documentazione sull'archiviazione code 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.

Condividi tramite