Freigeben über

Azure Storage Queues-Clientbibliothek für Python– Version 12.9.0

  • Artikel

Die Warteschlangenspeicherung in Azure ist ein Dienst zur Speicherung großer Anzahlen von Nachrichten, auf die von überall auf der Welt mit authentifizierten Anrufen über HTTP oder HTTPS zugegriffen werden kann. Eine einzelne Warteschlangennachricht kann bis zu 64 KiB groß sein, und eine Warteschlange kann Millionen von Nachrichten enthalten, bis zur Gesamtkapazitätsgrenze eines Speicherkontos.

Warteschlangenspeicherungen werden hauptsächlich für folgende Zwecke verwendet:

  • Erstellung eines Arbeits-Backlogs zur asynchronen Verarbeitung
  • Übergeben von Nachrichten zwischen verschiedenen Teilen einer verteilten Anwendung

Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Storage Queues-Clientbibliothek für Python mit pip:

pip install azure-storage-queue

Speicherkonto erstellen

Wenn Sie ein neues Speicherkonto erstellen möchten, können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Erstellen des Clients

Mit der Azure Storage Queues-Clientbibliothek für Python können Sie mit drei Arten von Ressourcen interagieren: dem Speicherkonto selbst, Warteschlangen und Nachrichten. Die Interaktion mit diesen Ressourcen beginnt mit einer instance eines Clients. Um ein Clientobjekt zu erstellen, benötigen Sie die Endpunkt-URL des Speicherkontos für den Warteschlangendienst und eine Anmeldeinformation, die Ihnen den Zugriff auf das Speicherkonto ermöglicht:

from azure.storage.queue import QueueServiceClient

service = QueueServiceClient(account_url="https://<my-storage-account-name>.queue.core.windows.net/", credential=credential)

Nachschlagen der Konto-URL

Sie finden die Warteschlangendienst-URL des Speicherkontos über das Azure-Portal, Azure PowerShell oder die Azure CLI:

# Get the queue service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.queue"

Typen von Anmeldeinformationen

Der credential Parameter kann in verschiedenen Formen bereitgestellt werden, je nachdem, welche Autorisierung Sie verwenden möchten:

  1. Um ein SAS-Token (Shared Access Signature) zu verwenden, geben Sie das Token als Zeichenfolge an. Wenn Ihre Konto-URL das SAS-Token enthält, lassen Sie den Parameter mit Anmeldeinformationen aus. Sie können ein SAS-Token im Azure-Portal unter "Shared Access Signature" generieren oder eine der generate_sas() Funktionen verwenden, um ein SAS-Token für das Speicherkonto oder die Warteschlange zu erstellen:

    from datetime import datetime, timedelta
from azure.storage.queue import QueueServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    start=datetime.utcnow(),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

queue_service_client = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential=sas_token)

  2. Um einen freigegebenen Speicherkontoschlüssel (auch als Kontoschlüssel oder Zugriffsschlüssel bezeichnet) zu verwenden, geben Sie den Schlüssel als Zeichenfolge an. Dies finden Sie im Azure-Portal im Abschnitt "Zugriffsschlüssel" oder indem Sie den folgenden Azure CLI-Befehl ausführen:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Verwenden Sie den Schlüssel als Anmeldeinformationsparameter, um den Client zu authentifizieren:

    from azure.storage.queue import QueueServiceClient
service = QueueServiceClient(account_url="https://<my_account_name>.queue.core.windows.net", credential="<account_access_key>")

  3. Um Azure Active Directory-Tokenanmeldeinformationen (AAD) zu verwenden, geben Sie eine instance des gewünschten Anmeldeinformationstyps an, der aus der azure-identity-Bibliothek abgerufen wird. Beispielsweise kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren.

    Dies erfordert eine anfängliche Einrichtung:

    Verwenden Sie die zurückgegebenen Tokenanmeldeinformationen, um den Client zu authentifizieren:

        from azure.identity import DefaultAzureCredential
    from azure.storage.queue import QueueServiceClient
    token_credential = DefaultAzureCredential()

    queue_service_client = QueueServiceClient(
        account_url="https://<my_account_name>.queue.core.windows.net",
        credential=token_credential
    )

Erstellen des Clients aus einer Verbindungszeichenfolge

Abhängig von Ihrem Anwendungsfall und Ihrer Autorisierungsmethode können Sie es vorziehen, einen Client instance mit einer Speicher-Verbindungszeichenfolge zu initialisieren, anstatt die Konto-URL und die Anmeldeinformationen separat bereitzustellen. Übergeben Sie dazu den Speicher Verbindungszeichenfolge an die Klassenmethode des from_connection_string Clients:

from azure.storage.queue import QueueServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = QueueServiceClient.from_connection_string(conn_str=connection_string)

Die Verbindungszeichenfolge zu Ihrem Speicherkonto finden Sie im Azure-Portal unter dem Abschnitt „Zugriffsschlüssel“ oder indem Sie den folgenden CLI-Befehl ausführen:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Wichtige Begriffe

Der Azure-Warteschlangendienst besteht aus den folgenden Komponenten:

  • Das Speicherkonto selbst
  • Eine Warteschlange innerhalb des Speicherkontos, die einen Satz von Nachrichten enthält
  • Eine Nachricht in einer Warteschlange in einem beliebigen Format von bis zu 64 KiB

Mit der Azure Storage Queues-Clientbibliothek für Python können Sie mit jeder dieser Komponenten über ein dediziertes Clientobjekt interagieren.

Asynchrone Clients

Diese Bibliothek enthält eine vollständige asynchrone API, die unter Python 3.5 und höher unterstützt wird. Um es verwenden zu können, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Weitere Informationen finden Sie in der Dokumentation zu azure-core .

Asynchrone Clients und Anmeldeinformationen sollten geschlossen werden, wenn sie nicht mehr benötigt werden. Diese Objekte sind asynchrone Kontext-Manager und definieren asynchrone close Methoden.

Clients

Für die Interaktion mit den verschiedenen Komponenten des Warteschlangendiensts werden zwei verschiedene Clients bereitgestellt:

  1. QueueServiceClient : Dieser Client stellt die Interaktion mit dem Azure-Speicherkonto selbst dar und ermöglicht es Ihnen, vorkonfigurierte Clientinstanzen abzurufen, um auf die Darin enthaltenen Warteschlangen zuzugreifen. Es bietet Vorgänge zum Abrufen und Konfigurieren der Kontoeigenschaften sowie zum Auflisten, Erstellen und Löschen von Warteschlangen innerhalb des Kontos. Um Vorgänge für eine bestimmte Warteschlange auszuführen, rufen Sie einen Client mithilfe der get_queue_client -Methode ab.
  2. QueueClient : Dieser Client stellt die Interaktion mit einer bestimmten Warteschlange dar (die noch nicht vorhanden sein muss). Es stellt Vorgänge zum Erstellen, Löschen oder Konfigurieren einer Warteschlange bereit und umfasst Vorgänge zum Senden, Empfangen, Einsehen, Löschen und Aktualisieren von Nachrichten darin.

Nachrichten

  • Senden : Fügt der Warteschlange eine Nachricht hinzu und legt optional ein Sichtbarkeitstimeout für die Nachricht fest.
  • Receive : Ruft eine Nachricht aus der Warteschlange ab und macht sie für andere Consumer unsichtbar.
  • Peek: Ruft eine Nachricht vom Anfang der Warteschlange ab, ohne die Sichtbarkeit der Nachricht zu ändern.
  • Aktualisieren: Updates das Sichtbarkeitstimeout einer Nachricht und/oder des Nachrichteninhalts.
  • Löschen : Löscht eine angegebene Nachricht aus der Warteschlange.
  • Löschen : Löscht alle Nachrichten aus der Warteschlange.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Aufgaben der Speicherwarteschlange abdecken, einschließlich:

Erstellen einer Warteschlange

Erstellen einer Warteschlange in Ihrem Speicherkonto

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.create_queue()

Verwenden des asynchronen Clients zum Erstellen einer Warteschlange

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await queue.create_queue()

Senden von Nachrichten

Senden von Nachrichten an Ihre Warteschlange

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
queue.send_message("I'm using queues!")
queue.send_message("This is my second message")

Nachrichten asynchron senden

import asyncio
from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
await asyncio.gather(
    queue.send_message("I'm using queues!"),
    queue.send_message("This is my second message")
)

Empfangen von Nachrichten

Empfangen und Verarbeiten von Nachrichten aus Ihrer Warteschlange

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

for message in response:
    print(message.content)
    queue.delete_message(message)

# Printed messages from the front of the queue:
# >> I'm using queues!
# >> This is my second message

Empfangen und Verarbeiten von Nachrichten in Batches

from azure.storage.queue import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages(messages_per_page=10)

for message_batch in response.by_page():
    for message in message_batch:
        print(message.content)
        queue.delete_message(message)

Asynchrones Empfangen und Verarbeiten von Nachrichten

from azure.storage.queue.aio import QueueClient

queue = QueueClient.from_connection_string(conn_str="<connection_string>", queue_name="myqueue")
response = queue.receive_messages()

async for message in response:
    print(message.content)
    await queue.delete_message(message)

Optionale Konfiguration

Optionale Schlüsselwort (keyword) Argumente, die auf Client- und Vorgangsebene übergeben werden können.

Konfiguration der Wiederholungsrichtlinie

Verwenden Sie die folgenden Schlüsselwort (keyword) Argumente, wenn Sie einen Client instanziieren, um die Wiederholungsrichtlinie zu konfigurieren:

  • retry_total (int): Gesamtzahl der zuzulassenden Wiederholungen. Hat Vorrang vor anderen Zählungen. retry_total=0 Übergeben Sie, wenn Sie bei Anforderungen keinen Wiederholungsversuch durchführen möchten. Der Standardwert ist 10.
  • retry_connect (int): Gibt an, wie viele Verbindungsfehler wiederholt werden sollen. Der Standardwert ist 3.
  • retry_read (int): Gibt an, wie oft bei Lesefehlern wiederholt werden soll. Der Standardwert ist 3.
  • retry_status (int): Gibt an, wie oft bei fehlerhaften status Codes wiederholt werden soll. Der Standardwert ist 3.
  • retry_to_secondary (bool): Gibt an, ob die Anforderung ggf. an die sekundäre Anforderung wiederholt werden soll. Dies sollte nur aktiviert werden, wenn RA-GRS-Konten verwendet werden, und möglicherweise veraltete Daten können verarbeitet werden. Der Standardwert lautet False.

Andere Client-/Pro-Operation-Konfiguration

Andere optionale Konfiguration Schlüsselwort (keyword) Argumente, die auf dem Client oder pro Vorgang angegeben werden können.

Client Schlüsselwort (keyword) Argumente:

  • connection_timeout (int): Die Anzahl der Sekunden, die der Client wartet, um eine Verbindung mit dem Server herzustellen. Der Standardwert ist 20 Sekunden.
  • read_timeout (int): Die Anzahl der Sekunden, die der Client zwischen aufeinanderfolgenden Lesevorgängen auf eine Antwort vom Server wartet. Dies ist ein Timeout auf Socketebene, das sich nicht auf die Gesamtdatengröße auswirkt. Clientseitige Lesetimeouts werden automatisch wiederholt. Der Standardwert ist 60 Sekunden.
  • transport (Any): Vom Benutzer bereitgestellter Transport zum Senden der HTTP-Anforderung.

Pro Vorgang Schlüsselwort (keyword) Argumente:

  • raw_response_hook (aufrufbar): Der angegebene Rückruf verwendet die vom Dienst zurückgegebene Antwort.
  • raw_request_hook (aufrufbar): Der angegebene Rückruf verwendet die Anforderung, bevor er an den Dienst gesendet wird.
  • client_request_id (str): Optionale vom Benutzer angegebene Identifizierung der Anforderung.
  • user_agent (str): Fügt den benutzerdefinierten Wert an den User-Agent-Header an, der mit der Anforderung gesendet werden soll.
  • logging_enable (bool): Aktiviert die Protokollierung auf DEBUG-Ebene. Der Standardwert lautet „False“. Kann auch auf Clientebene übergeben werden, um es für alle Anforderungen zu aktivieren.
  • logging_body (bool): Ermöglicht die Protokollierung des Anforderungs- und Antworttexts. Der Standardwert lautet „False“. Kann auch auf Clientebene übergeben werden, um es für alle Anforderungen zu aktivieren.
  • headers (dict): Übergeben Sie benutzerdefinierte Header als Schlüssel- und Wertpaare. Beispiel: headers={'CustomValue': value}

Problembehandlung

Allgemein

Speicherwarteschlangenclients lösen in Azure Core definierte Ausnahmen aus.

Diese Liste kann als Verweis verwendet werden, um ausgelöste Ausnahmen abzufangen. Um den spezifischen Fehlercode der Ausnahme abzurufen, verwenden Sie das error_code -Attribut, d. h exception.error_code. .

Protokollierung

Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable -Argument aktiviert werden:

import sys
import logging
from azure.storage.queue import QueueServiceClient

# Create a logger for the 'azure.storage.queue' SDK
logger = logging.getLogger('azure.storage.queue')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = QueueServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

service_client.get_service_stats(logging_enable=True)

Nächste Schritte

Weiterer Beispielcode

Erste Schritte mit unseren Warteschlangenbeispielen.

Mehrere Python SDK-Beispiele für Speicherwarteschlangen stehen Ihnen im GitHub-Repository des SDK zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Speicherwarteschlangen auftreten:

  • queue_samples_hello_world.py (asynchrone Version): Beispiele in diesem Artikel:

    • Clienterstellung
    • Erstellen einer Warteschlange
    • Senden von Nachrichten
    • Empfangen von Nachrichten

  • queue_samples_authentication.py (asynchrone Version): Beispiele für die Authentifizierung und Erstellung des Clients:

    • Aus einem Verbindungszeichenfolge
    • Von einem gemeinsam genutzten Zugriffsschlüssel
    • Von einem Shared Access Signature-Token
    • Aus Azure Active Directory

  • queue_samples_service.py (asynchrone Version): Beispiele für die Interaktion mit dem Warteschlangendienst:

    • Abrufen und Festlegen von Diensteigenschaften
    • Auflisten von Warteschlangen in einem Speicherkonto
    • Erstellen und Löschen einer Warteschlange aus dem Dienst
    • Abrufen des QueueClient

  • queue_samples_message.py (asynchrone Version): Beispiele für das Arbeiten mit Warteschlangen und Nachrichten:

    • Festlegen einer Zugriffsrichtlinie
    • Abrufen und Festlegen von Warteschlangenmetadaten
    • Senden und Empfangen von Nachrichten
    • Löschen von angegebenen Nachrichten und Löschen aller Nachrichten
    • Peek und Aktualisieren von Nachrichten

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Queue Storage finden Sie in der Dokumentation zu Azure Queue Storage auf docs.microsoft.com.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.