Azure Storage Queues-Clientbibliothek für Python– Version 12.9.0
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
- Für die Verwendung dieses Pakets ist Python 3.7 oder höher erforderlich. Weitere Informationen finden Sie auf unserer Seite zur Supportrichtlinie für Azure SDK für Python-Versionen.
- Sie benötigen ein Azure-Abonnement und ein Azure-Speicherkonto , um dieses Paket verwenden zu können.
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:
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)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 MyStorageAccountVerwenden 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>")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:
- Installieren von azure-identity
- Registrieren einer neuen AAD-Anwendung und Erteilen von Berechtigungen für den Zugriff auf Azure Storage
- Gewähren des Zugriffs auf Azure Queue-Daten mit RBAC im Azure-Portal
- Legen Sie die Werte der Client-ID, mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
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:
- 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. - 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.
Azure SDK for Python
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für