Quickstart: Azure Queue Storage-clientbibliotheek v12 voor Python

Ga aan de slag met de Azure Queue Storage-clientbibliotheek v12 voor Python. Azure Queue Storage is een service waarmee u grote aantallen berichten kunt opslaan om later op te halen en te verwerken. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

Gebruik de Azure Queue Storage-clientbibliotheek v12 voor Python voor het volgende:

• Een wachtrij maken
• Berichten aan een wachtrij toevoegen
• Berichten in een wachtrij bekijken
• Een bericht in een wachtrij bijwerken
• Berichten van een wachtrij ontvangen
• Berichten uit een wachtrij verwijderen
• Een wachtrij verwijderen

Aanvullende bronnen:

• API-referentiedocumentatie
• Broncode van bibliotheek
• Pakket (Python-pakketindex)
• Voorbeelden

Vereisten

• Azure-abonnement: u kunt een gratis abonnement nemen
• Azure Storage-account: maak een opslagaccount
• Python voor uw besturingssysteem - 2.7 of 3.6+

Instellen

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Azure Queue Storage-clientbibliotheek v12 voor Python.

Het project maken

Maak een Python-toepassing met de naam queues-quickstart-v12.

1. Maak in een consolevenster (zoals cmd, PowerShell of Bash) een nieuwe map voor het project.

   mkdir queues-quickstart-v12
   

2. Schakel over naar de zojuist gemaakte map queues-quickstart-v12.

   cd queues-quickstart-v12
   

Het pakket installeren

Installeer het pakket Azure Blob Storage-clientbibliotheek voor Python met behulp van de opdracht pip install.

pip install azure-storage-queue

Met deze opdracht wordt het pakket Azure Queue Storage-clientbibliotheek voor Python geïnstalleerd, evenals alle bibliotheken waarvan het afhankelijk is. In dit geval is dat alleen de Azure-kernbibliotheek voor Python.

Stel het app-framework in

1. Open een nieuw tekstbestand in uw code-editor

2. Voeg import-instructies toe

3. Maak de structuur voor het programma, waaronder zeer eenvoudige afhandeling van uitzonderingen

   Hier volgt de code:

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

4. Sla het nieuwe bestand op als queues-quickstart-v12.py in de map queues-quickstart-v12.

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. Volg deze stappen om uw opslagaccountreferenties te bekijken:

1. Meld u aan bij Azure Portal.

2. Zoek uw opslagaccount.

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

   

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 connection string. In de volgende sectie voegt connection string waarde toe aan een omgevingsvariabele.

   

De opslagverbindingsreeks configureren

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

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

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

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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.

Objectmodel

Azure Queue Storage is een service om grote aantallen berichten op te slaan. Een wachtrijbericht kan maximaal 64 KB groot zijn. Een wachtrij kan miljoenen berichten bevatten, tot aan de totale capaciteitslimiet van een opslagaccount. Wachtrijen worden vaak gebruikt om een voorraad werk te maken dat asynchroon moet worden verwerkt. Queue Storage biedt drie typen resources:

• Het opslagaccount
• Een wachtrij in het opslagaccount
• Berichten in de wachtrij

Het volgende diagram geeft de relatie tussen deze resources weer.

Gebruik de volgende Python-klassen om te communiceren met deze resources:

• QueueServiceClient: Met de QueueServiceClient kunt u alle wachtrijen in uw opslagaccount beheren.
• QueueClient: Met de QueueClient-klasse kunt u een afzonderlijke wachtrij en de bijbehorende berichten beheren en bewerken.
• QueueMessage: De QueueMessage-klasse vertegenwoordigt de afzonderlijke objecten die worden geretourneerd wanneer receive_messages wordt aangeroepen voor een wachtrij.

Codevoorbeelden

Deze voorbeeldcodefragmenten laten zien hoe u de volgende acties kunt uitvoeren met de Azure Queue Storage-clientbibliotheek voor Python:

• De verbindingsreeks ophalen
• Een wachtrij maken
• Berichten aan een wachtrij toevoegen
• Berichten in een wachtrij bekijken
• Een bericht in een wachtrij bijwerken
• Berichten van een wachtrij ontvangen
• Berichten uit een wachtrij verwijderen
• Een wachtrij verwijderen

De verbindingsreeks ophalen

Met de volgende code wordt de verbindingsreeks voor het opslagaccount opgehaald. De verbindingsreeks is opgeslagen in de omgevingsvariabele die is gemaakt in de sectie De opslagverbindingsreeks configureren.

Voeg deze code toe in het try-blok:

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

Een wachtrij maken

Verzin een naam voor de nieuwe wachtrij. Met de volgende code wordt een UUID-waarde aan de wachtrijnaam toegevoegd om te verzekeren dat deze uniek is.

Maak een exemplaar van de QueueClient-klasse. Roep vervolgens de methode create_queue aan om de wachtrij in uw opslagaccount te maken.

Voeg deze code toe aan het einde van het try-blok:

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

    # Create the queue
    queue_client.create_queue()

Berichten aan een wachtrij toevoegen

Met het volgende codefragment worden berichten aan de wachtrij toegevoegd door de methode send_message aan te roepen. Ook wordt de QueueMessage opgeslagen die met de derde send_message-aanroep wordt geretourneerd. De saved_message wordt gebruikt om de inhoud van een bericht later in het programma bij te werken.

Voeg deze code toe aan het einde van het try-blok:

    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")

Berichten in een wachtrij bekijken

Bekijk de berichten in de wachtrij door de methode peek_messages aan te roepen. Met deze methode worden één of meer berichten vooraan in de wachtrij opgehaald, maar wordt de zichtbaarheid van het bericht niet gewijzigd.

Voeg deze code toe aan het einde van het try-blok:

    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)

Een bericht in een wachtrij bijwerken

Werk de inhoud van een bericht bij door de methode update_message aan te roepen. Deze methode kan de time-out voor zichtbaarheid en de inhoud van een bericht wijzigen. De inhoud van het bericht moet een UTF-8-gecodeerde tekenreeks zijn die maximaal 64 KB groot is. Geef behalve de nieuwe inhoud ook waarden uit het bericht door die eerder in de code waren opgeslagen. De saved_message-waarden identificeren welk bericht moet worden bijgewerkt.

    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")

Berichten van een wachtrij ontvangen

Download eerder toegevoegde berichten door de methode receive_messages aan te roepen.

Voeg deze code toe aan het einde van het try-blok:

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

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

Berichten uit een wachtrij verwijderen

Verwijder berichten uit de wachtrij nadat ze zijn ontvangen en verwerkt. In dit geval betekent ‘verwerken’ gewoon dat het bericht wordt weergegeven in de console.

De app pauzeert voor gebruikersinvoer door input aan te roepen voordat deze de berichten verwerkt en verwijdert. Verifieer in uw Azure-portal dat de resources correct zijn gemaakt, voordat ze worden verwijderd. Berichten die niet expliciet worden verwijderd, worden uiteindelijk weer zichtbaar in de wachtrij, zodat u nog een kans hebt om ze te verwerken.

Voeg deze code toe aan het einde van het try-blok:

    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)

Een wachtrij verwijderen

Met de volgende code worden de resources opgeschoond die met de app zijn gemaakt, door de wachtrij te verwijderen met de methode delete_queue.

Voeg deze code toe aan het einde van het try-blok en sla het bestand op:

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

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

    print("Done")

De code uitvoeren

Met deze app worden drie berichten gemaakt en aan een Azure-wachtrij toegevoegd. De code toont de berichten in de wachtrij, haalt ze op en verwijdert ze, en verwijdert uiteindelijk de wachtrij.

Navigeer in het consolevenster naar de map die het bestand queues-quickstart-v12.py bevat, en voer de volgende opdracht python uit om de app uit te voeren.

python queues-quickstart-v12.py

De uitvoer van de app lijkt op die in het volgende voorbeeld:

Azure Queue Storage client library v12 - Python quickstart sample
Creating queue: quickstartqueues-cac365be-7ce6-4065-bd65-3756ea052cb8

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

Wanneer de app pauzeert voordat deze berichten ontvangt, controleert u uw opslagaccount in de Azure-portal. Verifieer dat de berichten in de wachtrij staan.

Druk op de Enter-toets om de berichten te ontvangen en verwijderen. Druk nogmaals op de Enter-toets wanneer u daarom wordt gevraagd, om de wachtrij te verwijderen en de demo te voltooien.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een wachtrij maakt en berichten eraan toevoegt met behulp van Python-code. Vervolgens leerde u hoe u berichten kunt bekijken, ophalen en verwijderen. Tot slot leerde u hoe u een berichtenwachtrij verwijdert.

Voor zelfstudies, voorbeelden, quickstarts en andere documentatie gaat u naar:

• Zie de Azure Storage-bibliotheken voor Python voor meer informatie.
• Raadpleeg Azure Queue Storage-clientbibliotheek v12 voor Python - voorbeelden voor meer Azure Queue Storage-voorbeeld-apps.