Azure Queue Storage gebruiken vanuit Python

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 gebruiken de Azure Queue Storage-clientbibliotheek voor Python. Zie de sectie Volgende stappen voor meer informatie over wachtrijen.

Wat is wachtrijopslag?

Azure Queue Storage is een service voor het opslaan van grote aantallen berichten die overal ter wereld toegankelijk zijn via geverifieerde aanroepen via HTTP of HTTPS. Eén wachtrijbericht kan maximaal 64 kB groot zijn en een wachtrij kan miljoenen berichten bevatten, tot aan de totale capaciteitslimiet van een opslagaccount. Queue Storage wordt vaak gebruikt om een wachtrij van taken te maken voor asynchrone verwerking.

Concepten van wachtrijservice

De Azure Queue-service bevat de volgende onderdelen:

• 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. De maximale tijd dat een bericht in de wachtrij kan blijven, is 7 dagen. 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 aangesproken met behulp van de volgende URL-indeling: http://<storage account>.queue.core.windows.net/<queue>

  De volgende URL verwijst naar een wachtrij in het diagram.

  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-resourceprovider voor .NET.

Als u op dit moment liever geen opslagaccount in Azure wilt maken, kunt u ook de Emulator van de Azurite-opslag gebruiken om uw code in een lokale omgeving uit te voeren en te testen. Zie De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkelingvoor 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.

Install via PyPI

Om via de Python Package Index (PyPI) te installeren, typ:

pip install azure-storage-queue

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 verzoek te autoriseren, voegt u de referenties van uw opslagaccount toe aan de applicatie als een verbindingsreeks. Voer de volgende stappen uit om uw opslagaccountreferenties weer te geven:

1. Meld u aan bij het Azure-portaal.

2. Zoek uw opslagaccount.

3. Selecteer toegangssleutels in het menuvenster van het opslagaccount onder Beveiliging en netwerken. Hier kunt u de toegangssleutels van het account en de volledige verbindingsreeks voor elke sleutel bekijken.

   

4. Selecteer Sleutels weergeven in het deelvenster Toegangssleutels.

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

   

De opslagverbindingsreeks configureren

Nadat u de verbindingsreeks 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> met uw daadwerkelijke connectiestring.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export 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 op voordat u doorgaat.

Uw toepassing configureren voor toegang tot Queue Storage

Met QueueClient het object kunt u met een wachtrij werken. 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 verbindingsreeks wordt opgehaald uit de AZURE_STORAGE_CONNECTION_STRING omgevingsvariabele die u eerder hebt ingesteld.

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

# 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, stelt u Base64-coderings- en decoderingsfuncties in 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

Als u een bericht in een wachtrij wilt invoegen, gebruikt u de send_message methode.

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 methode aan te peek_messages roepen. Deze methode bekijkt standaard één bericht.

# 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 ter plaatse 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)

De lengte van de wachtrij ophalen

U kunt een schatting krijgen van het aantal berichten in een 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 alleen bij benadering omdat berichten kunnen worden toegevoegd of verwijderd nadat de service op uw aanvraag heeft gereageerd.

Berichten uit de wachtrij halen

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

Wanneer u receive_messages belt, krijgt u standaard het volgende bericht in de wachtrij. Een bericht dat wordt geretourneerd van receive_messages wordt onzichtbaar voor alle andere code die berichten uit deze wachtrij leest. Dit bericht blijft standaard 30 seconden onzichtbaar. 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 vanuit 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 heeft om elk bericht volledig te verwerken.

In het volgende codevoorbeeld wordt de receive_messages methode gebruikt om berichten in batches op te halen. Vervolgens verwerkt het elk bericht in elke batch door gebruik te maken van een geneste lus for. Ook wordt de time-out voor onzichtbaarheid 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()

Volgende stappen

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

• Naslaginformatie over De Python-API voor Azure Queue Storage
• Python-ontwikkelaarscentrum
• Azure Storage REST API-naslagreferentie

Zie Codevoorbeelden met Python versie 2 voor voorbeelden van code die gebruikmaakt van afgeschreven Python versie 2 SDK's.