Freigeben über

Schnellstart: Azure Queue Storage-Clientbibliothek für Python

Erste Schritte mit der Azure Queue Storage-Clientbibliothek für Python. Azure Queue Storage ist ein Dienst zum Speichern großer Anzahl von Nachrichten zum späteren Abrufen und Verarbeiten. Führen Sie die folgenden Schritte aus, um das Paket zu installieren und Beispielcode für grundlegende Aufgaben auszuprobieren.

API-Referenzdokumentation | Quellcode | der BibliothekPaket (Python-Paketindex) | Proben

Verwenden Sie die Azure Queue Storage-Clientbibliothek für Python für:

  • Erstellen einer Warteschlange
  • Hinzufügen von Nachrichten zu einer Warteschlange
  • Nachrichten in einer Warteschlange einsehen
  • Aktualisieren einer Nachricht in einer Warteschlange
  • Die Warteschlangenlänge abrufen
  • Empfangen von Nachrichten aus einer Warteschlange
  • Löschen von Nachrichten aus einer Warteschlange
  • Löschen einer Warteschlange

Voraussetzungen

Einrichten

Dieser Abschnitt führt Sie durch die Vorbereitung eines Projekts für die Arbeit mit der Azure Queue Storage-Clientbibliothek für Python.

Erstelle das Projekt

Erstellen Sie eine Python-Anwendung namens "queues-quickstart".

  1. Erstellen Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) ein neues Verzeichnis für das Projekt.

    mkdir queues-quickstart

  2. Wechseln Sie zum neu erstellten queues-quickstart-Verzeichnis.

    cd queues-quickstart

Installieren der Pakete

Installieren Sie aus dem Projektverzeichnis die Azure Queue Storage-Clientbibliothek für python-Paket mithilfe des pip install Befehls. Das Azure-Identity-Paket ist für kennwortlose Verbindungen mit Azure-Diensten erforderlich.

pip install azure-storage-queue azure-identity

Einrichten des App-Frameworks

  1. Öffnen einer neuen Textdatei im Code-Editor

  2. Hinzufügen von import Anweisungen

  3. Erstellen der Struktur für das Programm, einschließlich einer einfachen Ausnahmebehandlung

    Der Code lautet wie folgt:

    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. Speichern Sie die neue Datei als queues-quickstart.py im queues-quickstart Verzeichnis.

Für Azure authentifizieren

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Die Verwendung der DefaultAzureCredential von der Azure Identity-Clientbibliothek bereitgestellten Klasse ist der empfohlene Ansatz für die Implementierung kennwortloser Verbindungen mit Azure-Diensten in Ihrem Code.

Sie können Auch Anforderungen an Azure-Dienste mithilfe von Kennwörtern, Verbindungszeichenfolgen oder anderen Anmeldeinformationen direkt autorisieren. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen fleißig sein, diese Geheimnisse niemals an einem unsicheren Ort verfügbar zu machen. Jeder, der Zugriff auf das Kennwort oder den geheimen Schlüssel erhält, kann sich authentifizieren. DefaultAzureCredential bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, um die kennwortlose Authentifizierung zu ermöglichen. Beide Optionen werden im folgenden Beispiel veranschaulicht.

DefaultAzureCredential ist eine Klasse, die von der Azure Identity-Clientbibliothek für Python bereitgestellt wird. Weitere DefaultAzureCredentialInformationen finden Sie in der Übersicht über DefaultAzureCredential. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll. Mit diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal im Vergleich zur Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren.

Ihre App kann sich beispielsweise bei der lokalen Entwicklung mithilfe Ihrer Anmeldeinformationen von Visual Studio Code authentifizieren und dann eine verwaltete Identität verwenden, nachdem sie in Azure bereitgestellt wurde. Für diesen Übergang sind keine Änderungen am Code erforderlich.

Stellen Sie beim lokalen Entwickeln sicher, dass das Benutzerkonto, das auf die Warteschlangendaten zugreift, über die richtigen Berechtigungen verfügt. Sie benötigen Storage Queue Data Contributor, um Warteschlangendaten zu lesen und zu schreiben. Um sich selbst diese Rolle zuweisen zu können, benötigen Sie die Rolle Benutzerzugriffsadministrator oder eine andere Rolle, die die Aktion Microsoft.Authorization/roleAssignments/Write enthält. Sie können einem Benutzer Azure RBAC-Rollen über das Azure-Portal, die Azure CLI oder mit Azure PowerShell zuweisen. Weitere Informationen zu den verfügbaren Bereichen für Rollenzuweisungen finden Sie auf der Seite Bereichsübersicht.

In diesem Szenario weisen Sie Ihrem Benutzerkonto Berechtigungen zu, die auf das Speicherkonto festgelegt sind, um dem Prinzip der geringsten Rechte zu folgen. Auf diese Weise erhalten Benutzer nur die erforderlichen Mindestberechtigungen, und es entstehen sicherere Produktionsumgebungen.

Im folgenden Beispiel wird Ihrem Benutzerkonto die Rolle "Beitragsberechtigter für Speicherwarteschlangendaten" zugewiesen, die sowohl Lese- als auch Schreibzugriff auf Warteschlangendaten in Ihrem Storage-Konto gewährt.

Von Bedeutung

In den meisten Fällen dauert es eine oder zwei Minute(n), bis die Rollenzuweisung in Azure weitergegeben wird. In seltenen Fällen kann es aber bis zu acht Minuten dauern. Wenn bei der ersten Ausführung Ihres Codes Authentifizierungsfehler auftreten, warten Sie einige Momente, und versuchen Sie es dann erneut.

  1. Suchen Sie im Azure-Portal Ihr Speicherkonto mithilfe der Hauptsuchleiste oder der linken Navigationsleiste.

  2. Wählen Sie auf der Übersichtsseite des Speicherkontos im linken Menü die Zugriffssteuerung (IAM) aus.

  3. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Registerkarte Rollenzuweisungen aus.

  4. Wählen Sie im oberen Menü +Hinzufügen aus, und fügen Sie dann die Rollenzuweisung aus dem resultierenden Dropdownmenü hinzu.

Ein Screenshot zeigt, wie eine Rolle zugewiesen wird.

  1. Über das Suchfeld können Sie die Ergebnisse für die gewünschte Rolle filtern. Suchen Sie in diesem Beispiel nach Mitwirkender an Speicherwarteschlangendaten, und wählen Sie das übereinstimmende Ergebnis und dann Weiter aus.

  2. Wählen Sie unter Zugriff zuweisen zu die Option Benutzer, Gruppe oder Dienstprinzipal und dann die Option + Mitglieder auswählen aus.

  3. Suchen Sie im Dialogfeld nach Ihrem Microsoft Entra-Benutzernamen (in der Regel Ihre user@domain-E-Mail-Adresse), und wählen Sie dann unten im Dialogfeld Auswählen aus.

  4. Wählen Sie Überprüfen und zuweisen aus, um zur letzten Seite zu gelangen, und wählen Sie erneut Überprüfen und zuweisen aus, um den Vorgang abzuschließen.

Objektmodell

Azure Queue Storage ist ein Dienst zum Speichern großer Anzahl von Nachrichten. Eine Warteschlangennachricht kann bis zu 64 KB groß sein. Eine Warteschlange kann Millionen von Nachrichten bis zum Gesamtkapazitätslimit eines Speicherkontos enthalten. Warteschlangen werden häufig verwendet, um einen Arbeitsbestand zu erstellen, der asynchron verarbeitet werden kann. Queue Storage bietet drei Arten von Ressourcen:

  • Speicherkonto: Der gesamte Zugriff auf Azure Storage erfolgt über ein Speicherkonto. Weitere Informationen zu Speicherkonten finden Sie unter Übersicht über das Speicherkonto
  • Warteschlange: Eine Warteschlange enthält eine Reihe von Nachrichten. Alle Nachrichten müssen sich in einer Warteschlange befinden. Beachten Sie, dass der Warteschlangenname in Kleinbuchstaben geschrieben sein muss. Informationen zu Benennungswarteschlangen finden Sie unter Benennen von Warteschlangen und Metadaten.
  • Nachricht: Eine Nachricht in einem beliebigen Format von bis zu 64 KB. Eine Nachricht kann maximal 7 Tage lang in der Warteschlange verbleiben. Für Version 2017-07-29 oder höher kann die maximale Zeit bis zum Live eine beliebige positive Zahl sein, oder -1 angibt, dass die Nachricht nicht abläuft. Wenn dieser Parameter nicht angegeben wird, beträgt die Standardzeit für die Lebensdauer sieben Tage.

Das folgende Diagramm zeigt die Beziehung zwischen diesen Ressourcen.

Diagramm der Architektur des Warteschlangenspeichers

Verwenden Sie die folgenden Python-Klassen, um mit diesen Ressourcen zu interagieren:

  • QueueServiceClient: Mit QueueServiceClient dieser Option können Sie alle Warteschlangen in Ihrem Speicherkonto verwalten.
  • QueueClient: Mit der QueueClient Klasse können Sie eine einzelne Warteschlange und deren Nachrichten verwalten und bearbeiten.
  • QueueMessage: Die QueueMessage-Klasse repräsentiert die individuellen Objekte, die bei einem Aufruf von receive_messages auf einer Warteschlange zurückgegeben werden.

Code-Beispiele

Diese Beispielcodeausschnitte zeigen Ihnen, wie Sie die folgenden Aktionen mit der Azure Queue Storage-Clientbibliothek für Python ausführen:

Autorisieren des Zugriffs und Erstellen eines Clientobjekts

Stellen Sie sicher, dass Sie mit demselben Microsoft Entra-Konto authentifiziert sind, dem Sie die Rolle zugewiesen haben. Sie können sich über Azure CLI, Visual Studio Code oder Azure PowerShell authentifizieren.

Melden Sie sich mit dem folgenden Befehl über die Azure-Befehlszeilenschnittstelle bei Azure an:

az login

Nach der Authentifizierung können Sie ein QueueClient Objekt erstellen und autorisieren, um auf Warteschlangendaten im Speicherkonto zuzugreifen, indem Sie DefaultAzureCredential verwenden. DefaultAzureCredential ermittelt und verwendet automatisch das Konto, mit dem Sie sich im vorherigen Schritt angemeldet haben.

Um die Verwendung DefaultAzureCredentialzu autorisieren, stellen Sie sicher, dass Sie das Azure-Identity-Paket hinzugefügt haben, wie in "Installieren der Pakete" beschrieben. Achten Sie außerdem darauf, die folgende Import-Anweisung in der datei queues-quickstart.py hinzuzufügen:

from azure.identity import DefaultAzureCredential

Entscheiden Sie sich für einen Namen für die Warteschlange und erstellen Sie eine Instanz der QueueClient Klasse unter Verwendung von DefaultAzureCredential zur Autorisierung. Sie verwenden dieses Clientobjekt, um die Warteschlangenressource im Speicherkonto zu erstellen und mit ihr zu interagieren.

Von Bedeutung

Warteschlangennamen dürfen nur Kleinbuchstaben, Zahlen und Bindestriche enthalten und müssen mit einem Buchstaben oder einer Zahl beginnen. Vor und nach jedem Bindestrich muss ein Zeichen stehen, das kein Bindestrich ist. Der Name muss auch zwischen 3 und 63 Zeichen lang sein. Weitere Informationen zu Benennungswarteschlangen finden Sie unter Benennungswarteschlangen und Metadaten.

Fügen Sie den folgenden Code innerhalb des try Blocks hinzu, und stellen Sie sicher, dass Sie den <storage-account-name> Platzhalterwert ersetzen:

    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)

Warteschlangennachrichten werden als Text gespeichert. Wenn Sie binärdaten speichern möchten, richten Sie Base64-Codierungs- und Decodierungsfunktionen ein, bevor Sie eine Nachricht in die Warteschlange einfügen.

Sie können base64-Codierungs- und Decodierungsfunktionen beim Erstellen des Clientobjekts konfigurieren:

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

Erstellen einer Warteschlange

Rufen Sie mithilfe des QueueClient Objekts die create_queue Methode auf, um die Warteschlange in Ihrem Speicherkonto zu erstellen.

Fügen Sie diesen Code am Ende des try Blocks hinzu:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

Hinzufügen von Nachrichten zu einer Warteschlange

Der folgende Codeausschnitt fügt nachrichten zur Warteschlange hinzu, indem die send_message Methode aufgerufen wird. Außerdem speichert er die QueueMessage, die vom dritten send_message-Aufruf zurückgegeben wird. Dies saved_message wird verwendet, um den Nachrichteninhalt später im Programm zu aktualisieren.

Fügen Sie diesen Code am Ende des try Blocks hinzu:

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

Nachrichten in einer Warteschlange einsehen

Werfen Sie einen Blick auf die Nachrichten in der Warteschlange, indem Sie die peek_messages Methode aufrufen. Diese Methode ruft eine oder mehrere Nachrichten von der Vorderseite der Warteschlange ab, ändert jedoch nicht die Sichtbarkeit der Nachricht.

Fügen Sie diesen Code am Ende des try Blocks hinzu:

    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)

Aktualisieren einer Nachricht in einer Warteschlange

Aktualisieren Sie den Inhalt einer Nachricht, indem Sie die update_message Methode aufrufen. Diese Methode kann das Sichtbarkeits-Timeout und den Inhalt einer Nachricht ändern. Der Nachrichteninhalt muss eine UTF-8-codierte Zeichenfolge sein, die bis zu 64 KB groß ist. Übergeben Sie zusammen mit dem neuen Inhalt Werte aus der Nachricht, die weiter oben im Code gespeichert wurde. Die saved_message Werte identifizieren, welche Nachricht aktualisiert werden soll.

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

Die Warteschlangenlänge abrufen

Sie können eine Schätzung der Anzahl der Nachrichten in einer Warteschlange erhalten.

Die get_queue_properties-Methode gibt die Eigenschaften der Warteschlange einschließlich der approximate_message_count zurück.

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

Das Ergebnis ist ungefähr, da Nachrichten hinzugefügt oder entfernt werden können, nachdem der Dienst auf Ihre Anfrage geantwortet hat.

Empfangen von Nachrichten aus einer Warteschlange

Sie können zuvor hinzugefügte Nachrichten herunterladen, indem Sie die receive_messages Methode aufrufen.

Fügen Sie diesen Code am Ende des try Blocks hinzu:

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

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

Beim Aufrufen der receive_messages Methode können Sie optional einen Wert angeben, für max_messagesden es sich um die Anzahl der Nachrichten handelt, die aus der Warteschlange abgerufen werden sollen. Der Standardwert ist 1 Nachricht und maximal 32 Nachrichten. Sie können auch einen Wert für visibility_timeout angeben, bei dem Nachrichten von anderen Vorgängen für den Timeoutzeitraum ausgeblendet werden. Der Standardwert ist 30 Sekunden.

Löschen von Nachrichten aus einer Warteschlange

Löschen Sie Nachrichten aus der Warteschlange, nachdem sie empfangen und verarbeitet wurden. In diesem Fall zeigt die Verarbeitung nur die Meldung auf der Konsole an.

Die App wartet auf Benutzereingaben, indem sie input aufruft, bevor sie die Nachrichten verarbeitet und löscht. Überprüfen Sie in Ihrem Azure-Portal , ob die Ressourcen ordnungsgemäß erstellt wurden, bevor sie gelöscht werden. Alle Nachrichten, die nicht explizit gelöscht wurden, werden schließlich wieder in der Warteschlange sichtbar, um eine weitere Möglichkeit zur Bearbeitung zu erhalten.

Fügen Sie diesen Code am Ende des try Blocks hinzu:

    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)

Löschen einer Warteschlange

Der folgende Code bereinigt die Ressourcen, die die App durch Löschen der Warteschlange mithilfe der delete_queue Methode erstellt hat.

Fügen Sie diesen Code am Ende des try Blocks hinzu, und speichern Sie die Datei:

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

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

    print("Done")

Ausführen des Codes

Diese App erstellt und fügt einer Azure-Warteschlange drei Nachrichten hinzu. Der Code listet die Nachrichten in der Warteschlange auf, ruft sie dann ab und löscht sie, bevor die Warteschlange endgültig gelöscht wird.

Navigieren Sie im Konsolenfenster zu dem Verzeichnis, das die queues-quickstart.py Datei enthält, und verwenden Sie dann den folgenden python Befehl, um die App auszuführen.

python queues-quickstart.py

Die Ausgabe der App ähnelt dem folgenden Beispiel:

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

Wenn die App vor dem Empfangen von Nachrichten angehalten wird, überprüfen Sie Ihr Speicherkonto im Azure-Portal. Überprüfen Sie, ob sich die Nachrichten in der Warteschlange befinden.

Drücken Sie die Enter TASTE, um die Nachrichten zu empfangen und zu löschen. Wenn Sie dazu aufgefordert werden, drücken Sie erneut die Enter TASTE, um die Warteschlange zu löschen und die Demo abzuschließen.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie erfahren, wie Sie eine Warteschlange erstellen und ihr Mithilfe von Python-Code Nachrichten hinzufügen. Dann haben Sie gelernt, Nachrichten anzuzeigen, abzurufen und zu löschen. Schließlich haben Sie erfahren, wie Sie eine Nachrichtenwarteschlange löschen.

Für Lernprogramme, Beispiele, Schnellstarts und andere Dokumentationen besuchen Sie:

Azure für Python-Entwickler

  • Last updated on