Delen via

Azure Queue Storage gebruiken vanuit Python

  • Artikel

Overzicht

In dit artikel worden veelvoorkomende scenario's beschreven met behulp van de Azure Queue Storage-service. De scenario's die worden behandeld, zijn onder andere het invoegen, bekijken, ophalen en verwijderen van wachtrijberichten. Code voor het maken en verwijderen van wachtrijen wordt ook behandeld.

De voorbeelden in dit artikel zijn geschreven in Python en maken gebruik van de Azure Queue Storage-clientbibliotheek voor Python. Zie de sectie Volgende stappen voor meer informatie over wachtrijen.

Wat is Queue Storage?

Azure Queue Storage is een service voor de opslag van grote aantallen berichten die via HTTP of HTTPS overal vandaan kunnen worden opgevraagd met geverifieerde aanroepen. Een enkel wachtrijbericht mag maximaal 64 KB groot zijn en een wachtrij kan miljoenen berichten bevatten, tot de totale capaciteitslimiet van een opslagaccount. Queue Storage wordt vaak gebruikt om een achterstand van werk te maken om asynchroon te verwerken.

Concepten van Queue-service

De Azure Queue-service bevat de volgende onderdelen:

Onderdelen van de Azure Queue-service

  • Opslagaccount: Alle toegang tot Azure Storage wordt uitgevoerd via een opslagaccount. Zie Overzicht van opslagaccount voor meer informatie over opslagaccounts.

  • Wachtrij: Een wachtrij bevat een set berichten. Alle berichten moeten zich in een wachtrij bevinden. De naam van een wachtrij mag alleen kleine letters bevatten. Zie Naming Queues and Metadata (Wachtrijen en metagegevens een naam geven) voor informatie over de naamgeving van wachtrijen.

  • Bericht: Een bericht in een willekeurige indeling, van maximaal 64 KB. Een bericht kan maximaal 7 dagen in de wachtrij blijven staan. Voor versie 29-07-2017 of hoger mag de maximale time-to-live elk positief getal zijn. Of -1 om aan te geven dat het bericht niet verloopt. Als deze parameter wordt weggelaten, is de standaard time-to-live zeven dagen.

  • URL-indeling: Wachtrijen kunnen worden adresseerbaar met de volgende URL-indeling: http://<storage account>.queue.core.windows.net/<queue>

    Met de volgende URL wordt een wachtrij in het diagram opgevraagd:

    http://myaccount.queue.core.windows.net/incoming-orders

Een Azure-opslagaccount maken

De eenvoudigste manier om uw eerste Azure-opslagaccount te maken, is met behulp van de Azure Portal. Zie Een opslagaccount maken voor meer informatie.

U kunt ook een Azure-opslagaccount maken met behulp van Azure PowerShell, Azure CLI of de Azure Storage Resource Provider voor .NET.

Als u op dit moment liever geen opslagaccount in Azure maakt, kunt u de Azurite-opslagemulator ook gebruiken om uw code in een lokale omgeving uit te voeren en te testen. Zie Use the Azurite emulator for local Azure Storage development (De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling) voor meer informatie.

Azure Storage-SDK voor Python downloaden en installeren

Voor de Azure Storage SDK voor Python is Python v2.7, v3.3 of hoger vereist.

Installeren via PyPI

Als u wilt installeren via de Python Package Index (PyPI), typt u:

pip install azure-storage-queue

Notitie

Als u een upgrade uitvoert van de Azure Storage SDK voor Python v0.36 of eerder, verwijdert u de oudere SDK met voordat pip uninstall azure-storage u het nieuwste pakket installeert.

Zie Azure SDK voor Python voor alternatieve installatiemethoden.

Kopieer uw referenties van de Azure Portal

Wanneer met de voorbeeldtoepassing een aanvraag wordt ingediend bij Azure Storage, moet deze aanvraag worden geautoriseerd. Om een aanvraag te autoriseren voegt u de referenties van uw opslagaccount toe als een verbindingsreeks. Voer de volgende stappen uit om de referenties van uw opslagaccount weer te geven:

  1. Meld u aan bij Azure Portal.

  2. Zoek uw opslagaccount.

  3. Selecteer in het menuvenster opslagaccount onder Beveiliging en netwerken de optie Toegangssleutels. Hier kunt u de toegangssleutels voor het account en de volledige connection string voor elke sleutel bekijken.

    Schermopname die laat zien waar de instellingen voor de toegangssleutel zich bevinden in de Azure Portal

  4. Selecteer in het deelvenster Toegangssleutelsde optie Sleutels weergeven.

  5. Zoek in de sectie key1 de waarde van de verbindingsreeks . Selecteer het pictogram Kopiëren naar klembord om de connection string te kopiëren. In de volgende sectie voegt u de connection string-waarde toe aan een omgevingsvariabele.

    Schermopname waarin een verbindingsreeks vanuit de Azure-portal wordt gekopieerd

De opslagverbindingsreeks configureren

Nadat u de connection string hebt gekopieerd, schrijft u deze naar een nieuwe omgevingsvariabele op de lokale computer waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, opent u een consolevenster en volgt u de aanwijzingen voor uw besturingssysteem. Vervang <yourconnectionstring> door de feitelijke verbindingsreeks.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Nadat u de omgevingsvariabele in Windows hebt toegevoegd, moet u een nieuw exemplaar van het opdrachtvenster starten.

Programma's opnieuw opstarten

Nadat u de omgevingsvariabele hebt toegevoegd, start u actieve programma's die de omgevingsvariabele moeten lezen, opnieuw. Start bijvoorbeeld uw ontwikkelomgeving of editor opnieuw voordat u doorgaat.

Uw toepassing configureren voor toegang tot Queue Storage

Met QueueClient het object kunt u werken met een wachtrij. Voeg de volgende code toe boven aan een Python-bestand waarin u programmatisch toegang wilt krijgen tot een Azure-wachtrij:

from azure.storage.queue import (
        QueueClient,
        BinaryBase64EncodePolicy,
        BinaryBase64DecodePolicy
)

import os, uuid

Het os pakket biedt ondersteuning voor het ophalen van een omgevingsvariabele. Het uuid pakket biedt ondersteuning voor het genereren van een unieke id voor een wachtrijnaam.

Een wachtrij maken

De connection string wordt opgehaald uit de AZURE_STORAGE_CONNECTION_STRING omgevingsvariabele die eerder is ingesteld.

Met de volgende code wordt een QueueClient -object gemaakt met behulp van de opslag connection string.

# Retrieve the connection string from an environment
# variable named AZURE_STORAGE_CONNECTION_STRING
connect_str = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

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

# Instantiate a QueueClient object which will
# be used to create and manipulate the queue
print("Creating queue: " + q_name)
queue_client = QueueClient.from_connection_string(connect_str, q_name)

# Create the queue
queue_client.create_queue()

Azure-wachtrijberichten worden opgeslagen als tekst. Als u binaire gegevens wilt opslaan, moet u base64-coderings- en decoderingsfuncties instellen voordat u een bericht in de wachtrij plaatst.

Configureer base64-coderings- en decoderingsfuncties bij het maken van het clientobject.

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

Een bericht in een wachtrij invoegen

Gebruik de send_message methode om een bericht in een wachtrij in te voegen.

message = u"Hello World"
print("Adding message: " + message)
queue_client.send_message(message)

Berichten bekijken

U kunt berichten bekijken zonder ze uit de wachtrij te verwijderen door de peek_messages methode aan te roepen. Met deze methode wordt standaard één bericht bekeken.

# Peek at the first message
messages = queue_client.peek_messages()

for peeked_message in messages:
    print("Peeked message: " + peeked_message.content)

De inhoud van een bericht in de wachtrij wijzigen

U kunt de inhoud van een bericht in de wachtrij wijzigen. Als het bericht een taak vertegenwoordigt, kunt u deze functie gebruiken om de status van de taak bij te werken.

De volgende code gebruikt de update_message methode om een bericht bij te werken. De time-out voor zichtbaarheid is ingesteld op 0, wat betekent dat het bericht onmiddellijk wordt weergegeven en de inhoud wordt bijgewerkt.

messages = queue_client.receive_messages()
list_result = next(messages)

message = queue_client.update_message(
        list_result.id, list_result.pop_receipt,
        visibility_timeout=0, content=u'Hello World Again')

print("Updated message to: " + message.content)

Lengte van de wachtrij ophalen

U kunt een schatting ophalen van het aantal berichten in de wachtrij.

De methode get_queue_properties retourneert wachtrijeigenschappen, waaronder de approximate_message_count.

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

Het resultaat is slechts bij benadering omdat berichten kunnen worden toegevoegd of verwijderd nadat de service op uw aanvraag heeft gereageerd.

Bericht uit een wachtrij verwijderen

Verwijder een bericht in twee stappen uit een wachtrij. Als uw code een bericht niet kan verwerken, zorgt dit proces in twee stappen ervoor dat u hetzelfde bericht kunt ontvangen en het opnieuw kunt proberen. Roep delete_message aan nadat het bericht is verwerkt.

Wanneer u receive_messages aanroept, krijgt u standaard het volgende bericht in de wachtrij. Een bericht dat wordt geretourneerd van receive_messages wordt onzichtbaar voor andere code die berichten uit deze wachtrij leest. Standaard blijft het bericht onzichtbaar gedurende 30 seconden. Als u het bericht uit de wachtrij wilt verwijderen, moet u ook delete_message aanroepen.

messages = queue_client.receive_messages()

for message in messages:
    print("Dequeueing message: " + message.content)
    queue_client.delete_message(message.id, message.pop_receipt)

Er zijn twee manieren waarop u het ophalen van berichten uit een wachtrij kunt aanpassen. Ten eerste kunt u berichten batchgewijs (maximaal 32) ophalen. Ten tweede kunt u een langere of kortere time-out voor onzichtbaarheid instellen, zodat uw code meer of minder tijd krijgt voor het volledig verwerken van elk bericht.

In het volgende codevoorbeeld wordt de receive_messages methode gebruikt om berichten in batches op te halen. Vervolgens worden elk bericht in elke batch verwerkt met behulp van een geneste for lus. De time-out voor onzichtbaarheid wordt ingesteld op vijf minuten voor elk bericht.

messages = queue_client.receive_messages(messages_per_page=5, visibility_timeout=5*60)

for msg_batch in messages.by_page():
   for msg in msg_batch:
      print("Batch dequeue message: " + msg.content)
      queue_client.delete_message(msg)

Een wachtrij verwijderen

Als u een wachtrij en alle berichten in de wachtrij wilt verwijderen, roept u de delete_queue methode aan.

print("Deleting queue: " + queue_client.queue_name)
queue_client.delete_queue()

Tip

Microsoft Azure Storage Explorer proberen

Microsoft Azure Storage Explorer is een gratis, zelfstandige app van Microsoft waarmee u visueel met Azure Storage-gegevens kunt werken in Windows, macOS en Linux.

Volgende stappen

Nu u de basisbeginselen van Queue Storage hebt geleerd, volgt u deze koppelingen voor meer informatie.

Zie Codevoorbeelden met Python versie 2 voor gerelateerde codevoorbeelden met behulp van afgeschafte Python versie 2 SDK's.