Guida introduttiva: Libreria client di Archiviazione coda di Azure per Python

Introduzione alla libreria client di Archiviazione coda di Azure per Python. Archiviazione code di Azure è un servizio che consente di archiviare un numero elevato di messaggi per recuperali ed elaborarli successivamente. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

Documentazione di riferimento delle API | Codice sorgente della libreria | Pacchetto (Indice dei pacchetti Python) | Esempi

Usare la libreria client Archiviazione coda di Azure per Python per:

• Crea una coda
• Aggiungere messaggi a una coda
• Visualizzare in anteprima i messaggi in una coda
• Aggiornare un messaggio in una coda
• Recuperare la lunghezza della coda
• Ricevere messaggi da una coda
• Eliminare messaggi da una coda
• Eliminare una coda

Prerequisiti

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

Configurazione

Questa sezione illustra come preparare un progetto per l'uso con la libreria client Archiviazione coda di Azure per Python.

Creare il progetto

Creare un'applicazione Python denominata queues-quickstart.

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

   mkdir queues-quickstart
   

2. Passare alla directory queues-quickstart appena creata.

   cd queues-quickstart
   

Installare i pacchetti

Nella directory del progetto installare la libreria client Archiviazione coda di Azure per il pacchetto Python usando il pip install comando . Il pacchetto azure-identity è necessario per le connessioni senza password ai servizi di Azure.

pip install azure-storage-queue azure-identity

Configurare il framework dell'app

1. Aprire un nuovo file di testo nell'editor del codice

2. Aggiungere le istruzioni import

3. Creare la struttura per il programma, inclusa la gestione delle eccezioni di base

   Ecco il codice:

   import os, uuid
   from azure.identity import DefaultAzureCredential
   from azure.storage.queue import QueueServiceClient, QueueClient, QueueMessage, BinaryBase64DecodePolicy, BinaryBase64EncodePolicy
   
   try:
       print("Azure Queue storage - Python quickstart sample")
       # Quickstart code goes here
   except Exception as ex:
       print('Exception:')
       print(ex)
   
   

4. Salvare il nuovo file come queues-quickstart.py nella directory queues-quickstart .

Autenticazione con Azure

Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. L'uso della DefaultAzureCredential classe fornita dalla libreria client di Identità di Azure è l'approccio consigliato per implementare connessioni senza password ai servizi di Azure nel codice.

È anche possibile autorizzare le richieste ai servizi di Azure usando password, stringa di connessione o altre credenziali direttamente. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai questi segreti in una posizione non sicura. Chiunque possa accedere alla password o alla chiave privata è in grado di eseguire l'autenticazione. DefaultAzureCredential offre vantaggi di gestione e sicurezza migliorati rispetto alla chiave dell'account per consentire l'autenticazione senza password. Entrambe le opzioni sono illustrate nell'esempio seguente.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Modello a oggetti

Archiviazione code di Azure è un servizio per l'archiviazione di un numero elevato di messaggi. Un messaggio in coda avere dimensioni fino a 64 KB. Una coda può contenere milioni di messaggi, fino al limite di capacità totale dell'account di archiviazione. Le code vengono in genere usate per creare un backlog di lavoro da elaborare in modo asincrono. Archiviazione code offre tre tipi di risorse:

• Account di archiviazione:l'accesso ad Archiviazione di Azure viene eseguito esclusivamente tramite un account di archiviazione. Per altre informazioni sugli account di archiviazione, vedere panoramica dell'account di Archiviazione
• Coda: una coda contiene un set di messaggi. Tutti i messaggi devono essere in una coda. Si noti che il nome della coda deve essere tutto minuscolo. Per altre informazioni, vedere Denominazione di code e metadati.
• Messaggio: un messaggio, in qualsiasi formato, con dimensioni massime di 64 KB. Un messaggio può rimanere nella coda per un massimo di 7 giorni. Per la versione 2017-07-29 o successiva, la durata massima può essere qualsiasi numero positivo o -1 che indica che il messaggio non scade. Se questo parametro viene omesso, il valore TTL predefinito è sette giorni.

Il diagramma seguente mostra la relazione tra queste risorse.

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

• QueueServiceClientQueueServiceClient: consente di gestire tutte le code nell'account di archiviazione.
• QueueClient: la QueueClient classe consente di gestire e modificare una singola coda e i relativi messaggi.
• QueueMessage: la QueueMessage classe rappresenta i singoli oggetti restituiti durante la chiamata receive_messages a una coda.

Esempi di codice

Questi frammenti di codice di esempio illustrano come eseguire le azioni seguenti con la libreria client di Archiviazione code di Azure per Python:

• Autorizzare l'accesso e creare un oggetto client
• Creare una coda
• Aggiungere messaggi a una coda
• Visualizzare in anteprima i messaggi in una coda
• Aggiornare un messaggio in una coda
• Ottenere la lunghezza della coda
• Ricevere messaggi da una coda
• Eliminare messaggi da una coda
• Eliminare una coda

az login

az login

Connect-AzAccount

from azure.identity import DefaultAzureCredential

    print("Azure Queue storage - Python quickstart sample")

    # Create a unique name for the queue
    queue_name = "quickstartqueues-" + str(uuid.uuid4())

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

    # Create the QueueClient object
    # We'll use this object to create and interact with the queue
    queue_client = QueueClient(account_url, queue_name=queue_name ,credential=default_credential)

    print("Azure Queue storage - Python quickstart sample")

    # Retrieve the connection string for use with the application. The storage
    # connection string is stored in an environment variable on the machine
    # running the application called AZURE_STORAGE_CONNECTION_STRING. If the
    # environment variable is created after the application is launched in a
    # console or with Visual Studio, the shell or application needs to be
    # closed and reloaded to take the environment variable into account.
    connect_str = os.getenv('AZURE_STORAGE_CONNECTION_STRING')

    # Create a unique name for the queue
    queue_name = "quickstartqueues-" + str(uuid.uuid4())

    print("Creating queue: " + queue_name)

    # Instantiate a QueueClient which will be
    # used to create and manipulate the queue
    queue_client = QueueClient.from_connection_string(connect_str, queue_name)

I messaggi della coda vengono archiviati come testo. Per archiviare i dati binari, configurare le funzioni di codifica e decodifica Base64 prima di inserire un messaggio nella coda.

È possibile configurare funzioni di codifica e decodifica Base64 durante la creazione dell'oggetto client:

# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
                            conn_str=connect_str, queue_name=q_name,
                            message_encode_policy = BinaryBase64EncodePolicy(),
                            message_decode_policy = BinaryBase64DecodePolicy()
                        )

Crea una coda

Usando l'oggetto QueueClient , chiamare il create_queue metodo per creare la coda nell'account di archiviazione.

Aggiungere questo codice alla fine del blocco try:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Aggiungere messaggi a una coda

Il frammento di codice seguente aggiunge messaggi alla coda chiamando il metodo send_message. Salva anche il QueueMessage restituito dalla terza chiamata a send_message. Il saved_message viene usato per aggiornare il contenuto del messaggio in un secondo momento nel programma.

Aggiungere questo codice alla fine del blocco try:

    print("\nAdding messages to the queue...")

    # Send several messages to the queue
    queue_client.send_message(u"First message")
    queue_client.send_message(u"Second message")
    saved_message = queue_client.send_message(u"Third message")

Visualizzare in anteprima i messaggi in una coda

Per visualizzare in anteprima i messaggi nella coda, chiamare il metodo peek_messages. Questo metodo recupera uno o più messaggi dall'inizio della coda, senza modificare la visibilità del messaggio.

Aggiungere questo codice alla fine del blocco try:

    print("\nPeek at the messages in the queue...")

    # Peek at messages in the queue
    peeked_messages = queue_client.peek_messages(max_messages=5)

    for peeked_message in peeked_messages:
        # Display the message
        print("Message: " + peeked_message.content)

Aggiornare un messaggio in una coda

Per aggiornare il contenuto di un messaggio, chiamare il metodo update_message. Questo metodo può modificare il timeout di visibilità e il contenuto di un messaggio. Il contenuto del messaggio deve essere una stringa con codifica UTF-8 di dimensioni non superiori a 64 KB. Insieme al nuovo contenuto, passare i valori del messaggio salvati in precedenza nel codice. I valori del saved_message identificano il messaggio da aggiornare.

    print("\nUpdating the third message in the queue...")

    # Update a message using the message saved when calling send_message earlier
    queue_client.update_message(saved_message, pop_receipt=saved_message.pop_receipt, \
        content="Third message has been updated")

Recuperare la lunghezza della coda

È possibile ottenere una stima del numero di messaggi in una coda.

Il metodo get_queue_properties restituisce le proprietà della coda, tra cui .approximate_message_count

properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))

Il risultato è approssimativo perché i messaggi possono essere aggiunti o rimossi dopo che il servizio risponde alla richiesta.

Ricevere messaggi da una coda

È possibile scaricare i messaggi aggiunti in precedenza chiamando il receive_messages metodo .

Aggiungere questo codice alla fine del blocco try:

    print("\nReceiving messages from the queue...")

    # Get messages from the queue
    messages = queue_client.receive_messages(max_messages=5)

Quando si chiama il receive_messages metodo , è possibile specificare facoltativamente un valore per max_messages, ovvero il numero di messaggi da recuperare dalla coda. Il valore predefinito è 1 messaggio e il massimo è 32 messaggi. È anche possibile specificare un valore per visibility_timeout, che nasconde i messaggi da altre operazioni per il periodo di timeout. Il valore predefinito è 30 secondi.

Eliminare messaggi da una coda

Eliminare i messaggi dalla coda dopo che sono stati ricevuti ed elaborati. In questo caso, l'elaborazione consiste semplicemente nella visualizzazione del messaggio nella console.

L'app viene sospesa per l'input dell'utente chiamando input prima dell'elaborazione ed eliminazione dei messaggi. Verificare nel portale di Azure che le risorse siano state create correttamente, prima di eliminarle. Eventuali messaggi non eliminati in modo esplicito diventano nuovamente visibili nella coda per un'altra possibilità di elaborarli.

Aggiungere questo codice alla fine del blocco try:

    print("\nPress Enter key to 'process' messages and delete them from the queue...")
    input()

    for msg_batch in messages.by_page():
            for msg in msg_batch:
                # "Process" the message
                print(msg.content)
                # Let the service know we're finished with
                # the message and it can be safely deleted.
                queue_client.delete_message(msg)

Eliminare una coda

Il codice seguente pulisce le risorse create dall'app eliminando la coda tramite il metodo delete_queue.

Aggiungere questo codice alla fine del blocco try e salvare il file:

    print("\nPress Enter key to delete the queue...")
    input()

    # Clean up
    print("Deleting queue...")
    queue_client.delete_queue()

    print("Done")

Eseguire il codice

Questa app crea e aggiunge tre messaggi a una coda di Azure. Il codice elenca i messaggi nella coda, quindi li recupera e li elimina, prima di eliminare definitivamente la coda.

Nella finestra della console passare alla directory contenente il file queues-quickstart.py , quindi usare il comando seguente python per eseguire l'app.

python queues-quickstart.py

L'output dell'app è simile all'esempio seguente:

Azure Queue Storage client library - Python quickstart sample
Creating queue: quickstartqueues-<UUID>

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

First message
Second message
Third message has been updated

Press Enter key to delete the queue...

Deleting queue...
Done

Quando l'app viene sospesa prima della ricezione dei messaggi, controllare l'account di archiviazione nel portale di Azure. Verificare che i messaggi siano nella coda.

Premere il Enter tasto per ricevere ed eliminare i messaggi. Quando richiesto, premere di nuovo il Enter tasto per eliminare la coda e completare la demo.

Passaggi successivi

In questo argomento di avvio rapido si è appreso come creare una coda e aggiungervi messaggi usando codice Python. Si è quindi appreso come visualizzare in anteprima, recuperare ed eliminare i messaggi. Infine, si è appreso come eliminare una coda di messaggi.

Per esercitazioni, esempi, guide di avvio rapido e altra documentazione, vedere:

• Per esempi di codice correlati che usano SDK di Python versione 2 deprecati, vedere Esempi di codice con Python versione 2.
• Per altre informazioni, vedere le librerie di Archiviazione di Azure per Python.
• Per altre app di esempio di accodamento di Azure Archiviazione, vedere Azure Queue Archiviazione client library for Python - samples (Esempi di code di Azure per Python).