Quickstart: Azure Queue Storage-clientbibliotheek voor Python

  • Artikel

Ga aan de slag met de Azure Queue Storage-clientbibliotheek 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.

API-referentiedocumentatie | Broncode van de bibliotheek | Pakket (Python Package Index) | Voorbeelden

Gebruik de Azure Queue Storage-clientbibliotheek voor Python om het volgende te doen:

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

Vereisten

Instellen

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

Het project maken

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

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

    mkdir queues-quickstart

  2. Schakel over naar de zojuist gemaakte wachtrijen-quickstart-map .

    cd queues-quickstart

De pakketten installeren

Installeer vanuit de projectmap de Azure Queue Storage-clientbibliotheek voor het Python-pakket met behulp van de pip install opdracht. Het azure-identity-pakket is nodig voor verbindingen zonder wachtwoord met Azure-services.

pip install azure-storage-queue azure-identity

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 eenvoudige afhandeling van uitzonderingen

    Hier volgt de code:

    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. Sla het nieuwe bestand op als queues-quickstart.py in de map wachtrijen-quickstart.

Verifiëren bij Azure

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential klasse die wordt geleverd door de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van wachtwoordloze verbindingen met Azure-services in uw code.

U kunt aanvragen voor Azure-services ook rechtstreeks autoriseren met behulp van wachtwoorden, verbindingsreeks s of andere referenties. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om deze geheimen nooit zichtbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot het wachtwoord of de geheime sleutel, kan worden geverifieerd. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord mogelijk te maken. Beide opties worden in het volgende voorbeeld gedemonstreerd.

DefaultAzureCredential is een klasse die wordt geleverd door de Azure Identity-clientbibliotheek voor Python. Zie het overzicht DefaultAzureCredential voor meer DefaultAzureCredentialinformatie. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

Uw app kan bijvoorbeeld verifiëren met behulp van uw aanmeldingsreferenties voor Visual Studio Code bij het lokaal ontwikkelen en vervolgens een beheerde identiteit gebruiken zodra deze is geïmplementeerd in Azure. Er zijn geen codewijzigingen vereist voor deze overgang.

Wanneer u lokaal ontwikkelt, moet u ervoor zorgen dat het gebruikersaccount dat toegang heeft tot de wachtrijgegevens over de juiste machtigingen beschikt. U hebt Inzender voor opslagwachtrijgegevens nodig om wachtrijgegevens te lezen en te schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Gebruikerstoegang Beheer istrator of een andere rol met de actie Microsoft.Authorization/roleAssignments/write toegewezen krijgen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van Azure Portal, Azure CLI of Azure PowerShell. Meer informatie over de beschikbare bereiken voor roltoewijzingen vindt u op de overzichtspagina van het bereik.

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, dat is afgestemd op het opslagaccount, om het principe van minimale bevoegdheden te volgen. Deze procedure biedt gebruikers alleen de minimale machtigingen die nodig zijn en maakt veiligere productieomgevingen.

In het volgende voorbeeld wordt de rol Inzender voor opslagwachtrijgegevens toegewezen aan uw gebruikersaccount, dat zowel lees- als schrijftoegang biedt tot wachtrijgegevens in uw opslagaccount.

Belangrijk

In de meeste gevallen duurt het een of twee minuten voordat de roltoewijzing is doorgegeven in Azure, maar in zeldzame gevallen kan het maximaal acht minuten duren. Als u verificatiefouten ontvangt wanneer u de code voor het eerst uitvoert, wacht u even en probeert u het opnieuw.

  1. Zoek uw opslagaccount in Azure Portal met behulp van de hoofdzoekbalk of linkernavigatiebalk.

  2. Selecteer op de overzichtspagina van het opslagaccount toegangsbeheer (IAM) in het menu aan de linkerkant.

  3. Selecteer op de pagina Toegangsbeheer (IAM) het tabblad Roltoewijzingen .

  4. Selecteer + Toevoegen in het bovenste menu en voeg vervolgens roltoewijzing toe in de resulterende vervolgkeuzelijst.

A screenshot showing how to assign a role.

  1. Gebruik het zoekvak om de resultaten te filteren op de gewenste rol. In dit voorbeeld zoekt u inzender voor opslagwachtrijgegevens en selecteert u het overeenkomende resultaat en kiest u vervolgens Volgende.

  2. Selecteer onder Toegang toewijzen de optie Gebruiker, groep of service-principal en kies vervolgens + Leden selecteren.

  3. Zoek in het dialoogvenster naar uw Microsoft Entra-gebruikersnaam (meestal uw user@domain e-mailadres) en kies Vervolgens onderaan het dialoogvenster Selecteren .

  4. Selecteer Beoordelen + toewijzen om naar de laatste pagina te gaan en vervolgens opnieuw beoordelen en toewijzen om het proces te voltooien.

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:

  • Opslagaccount: Alle toegang tot Azure Storage wordt uitgevoerd via een opslagaccount. Zie overzicht van opslagaccounts 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. 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.

Het volgende diagram geeft de relatie tussen deze resources weer.

Diagram of Queue storage architecture

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

  • QueueServiceClient: Hiermee 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 bij het aanroepen receive_messages van een wachtrij.

Codevoorbeelden

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

Toegang autoriseren en een clientobject maken

Zorg ervoor dat u bent geverifieerd met hetzelfde Microsoft Entra-account waaraan u de rol hebt toegewezen. U kunt zich verifiëren via Azure CLI, Visual Studio Code of Azure PowerShell.

Meld u aan bij Azure via de Azure CLI met behulp van de volgende opdracht:

az login

Nadat u bent geverifieerd, kunt u een QueueClient object maken en autoriseren met behulp van DefaultAzureCredential toegang tot wachtrijgegevens in het opslagaccount. DefaultAzureCredential detecteert en gebruikt automatisch het account waarmee u zich in de vorige stap hebt aangemeld.

Als u het gebruik DefaultAzureCredentialwilt autoriseren, moet u ervoor zorgen dat u het azure-identity-pakket hebt toegevoegd, zoals beschreven in De pakketten installeren. Zorg er ook voor dat u de volgende importinstructie toevoegt in het queues-quickstart.py-bestand :

from azure.identity import DefaultAzureCredential

Bepaal een naam voor de wachtrij en maak een exemplaar van de QueueClient klasse met behulp van DefaultAzureCredential autorisatie. We gebruiken dit clientobject om de wachtrijresource in het opslagaccount te maken en ermee te communiceren.

Belangrijk

Wachtrijnamen mogen alleen kleine letters, cijfers en afbreekstreepjes bevatten en moeten beginnen met een letter of cijfer. Elk afbreekstreepje moet worden voorafgegaan en gevolgd door een cijfer of letter. De naam moet bovendien tussen 3 en 63 tekens lang zijn. Zie Naamgeving van wachtrijen en metagegevens voor meer informatie over de naamgeving van wachtrijen.

Voeg de volgende code toe in het try blok en zorg ervoor dat u de waarde van de <storage-account-name> tijdelijke aanduiding vervangt:

    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)

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.

U kunt Base64-coderings- en decoderingsfuncties configureren 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 wachtrij maken

Roep met behulp van het QueueClient object de create_queue methode aan om de wachtrij in uw opslagaccount te maken.

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

    print("Creating queue: " + 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")

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 bij benadering omdat berichten kunnen worden toegevoegd of verwijderd nadat de service op uw aanvraag heeft gereageerd.

Berichten van een wachtrij ontvangen

U kunt eerder toegevoegde berichten downloaden door de methode aan te receive_messages 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(max_messages=5)

Wanneer u de receive_messages methode aanroept, kunt u desgewenst een waarde opgeven voor max_messages, wat het aantal berichten is dat uit de wachtrij moet worden opgehaald. De standaardwaarde is 1 bericht en het maximum is 32 berichten. U kunt ook een waarde opgeven waarvoor visibility_timeoutde berichten voor de time-outperiode worden verborgen voor andere bewerkingen. De standaardwaarde is 30 seconden.

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 voor een andere kans 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 met het bestand queues-quickstart.py en gebruik vervolgens de volgende python opdracht om de app uit te voeren.

python queues-quickstart.py

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

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

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 te verwijderen. Wanneer u hierom wordt gevraagd, drukt u nogmaals op de Enter toets 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:

Azure voor Python-ontwikkelaars