Service Bus-Bibliotheken für PythonService Bus libraries for Python
Microsoft Azure Service Bus unterstützt einen Satz cloudbasierter, nachrichtenorientierter Middlewaretechnologien, darunter zuverlässiges Message Queuing und dauerhaftes Veröffentlichungs-/Abonnementmessaging.Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging.
Neuerungen in v0.50.0What's new in v0.50.0?
Ab Version 0.50.0 ist eine neue AMQP-basierte API zum Senden und Empfangen von Nachrichten verfügbar.As of version 0.50.0 a new AMQP-based API is available for sending and receiving messages. Dieses Update umfasst wichtige Änderungen.This update involves breaking changes.
Erfahren Sie im Abschnitt zur Migration von v0.21.1 zu v0.50.0, ob ein Upgrade für Sie zu diesem Zeitpunkt sinnvoll ist.Please read Migration from v0.21.1 to v0.50.0 to determine if upgrading is right for you at this time.
Mit der neuen AMQP-basierten API profitieren Sie von einer zuverlässigeren Nachrichtenübergabe sowie einer besseren Leistung und Unterstützung erweiterter Features.The new AMQP-based API offers improved message passing reliability, performance and expanded feature support going forward. Die neue API unterstützt zudem asynchrone Vorgänge (basierend auf Asyncio) für das Senden, Empfangen und Verarbeiten von Nachrichten.The new API also offers support for asynchronous operations (based on asyncio) for sending, receiving and handling messages.
Eine Dokumentation zu den älteren HTTP-basierten Vorgängen finden Sie im Abschnitt zur Verwendung HTTP-basierter Vorgänge der Legacy-API.For documentation on the legacy HTTP-based operations please see Using HTTP-based operations of the legacy API.
VoraussetzungenPrerequisites
- Azure-Abonnement (Erstellen Sie ein kostenloses Konto.)Azure subscription - Create a free account
- Azure Service Bus-Namespace und Anmeldeinformationen für die VerwaltungAzure Service Bus namespace and management credentials
- Python 2.7-3.7Python 2.7-3.7
InstallationInstallation
pip install azure-servicebus
Herstellen der Verbindung mit Azure Service BusConnect to Azure Service Bus
Abrufen von AnmeldeinformationenGet credentials
Verwenden Sie den folgenden Azure CLI-Codeausschnitt, um eine Umgebungsvariable mit der Service Bus-Verbindungszeichenfolge zu füllen (Sie finden diesen Wert auch im Azure-Portal).Use the Azure CLI snippet below to populate an environment variable with the Service Bus connection string (you can also find this value in the Azure portal). Der Ausschnitt ist für die Bash-Shell formatiert.The snippet is formatted for the Bash shell.
RES_GROUP=<resource-group-name>
NAMESPACE=<servicebus-namespace>
export SB_CONN_STR=$(az servicebus namespace authorization-rule keys list \
--resource-group $RES_GROUP \
--namespace-name $NAMESPACE \
--name RootManageSharedAccessKey \
--query primaryConnectionString \
--output tsv)
Erstellen des ClientsCreate client
Nach dem Auffüllen der SB_CONN_STR-Umgebungsvariablen können Sie das ServiceBusClient-Element erstellen.Once you've populated the SB_CONN_STR environment variable, you can create the ServiceBusClient.
import os
from azure.servicebus import ServiceBusClient
connection_str = os.environ['SB_CONN_STR']
sb_client = ServiceBusClient.from_connection_string(connection_str)
Verwenden Sie für asynchrone Vorgänge den azure.servicebus.aio-Namespace.If you wish to use asynchronous operations, please use the azure.servicebus.aio namespace.
import os
from azure.servicebus.aio import ServiceBusClient
connection_str = os.environ['SB_CONN_STR']
sb_client = ServiceBusClient.from_connection_string(connection_str)
Service Bus-WarteschlangenService Bus queues
Service Bus-Warteschlangen stellen eine Alternative zu Storage-Warteschlangen dar. Sie sind in Szenarien nützlich, in denen komplexere Messagingfeatures (größere Nachrichten, Nachrichtensortierung, einzelne schädliche Lesevorgänge, zeitgesteuerte Zustellung) mit pushbasierter Zustellung und langen Abrufvorgängen erforderlich sind.Service Bus queues are an alternative to Storage queues that might be useful in scenarios where more advanced messaging features are needed (larger message sizes, message ordering, single-operation destructive reads, scheduled delivery) using push-style delivery (using long polling).
Erstellen einer WarteschlangeCreate queue
Dadurch wird eine neue Warteschlange im Service Bus-Namespace erstellt.This creates a new queue within the Service Bus namespace. Wenn innerhalb des Namespace bereits eine Warteschlange vorhanden ist, wird ein Fehler ausgelöst.If a queue of the same name already exists within the namespace an error will be raised.
sb_client.create_queue("MyQueue")
Sie können auch optionale Parameter festlegen, um das Verhalten der Warteschlange zu konfigurieren.Optional parameters to configure the queue behavior can also be specified.
sb_client.create_queue(
"MySessionQueue",
requires_session=True # Create a sessionful queue
max_delivery_count=5 # Max delivery attempts per message
)
Abrufen eines WarteschlangenclientsGet a queue client
Ein QueueClient-Element kann zum Senden und Empfangen von Nachrichten über die Warteschlange sowie für weitere Vorgänge verwendet werden.A QueueClient can be used to send and receive messages from the queue, along with other operations.
queue_client = sb_client.get_queue("MyQueue")
Senden von NachrichtenSending messages
Der Warteschlangenclient kann mehrere Nachrichten gleichzeitig senden:The queue client can send one or more messages at a time:
from azure.servicebus import Message
message = Message("Hello World")
queue_client.send(message)
message_one = Message("First")
message_two = Message("Second")
queue_client.send([message_one, message_two])
Bei jedem Aufruf von „QueueClient.send“ wird eine neue Dienstverbindung erstellt.Each call to QueueClient.send will create a new service connection. Wenn Sie die gleiche Verbindung für mehrere Sendeaufrufe wiederverwenden möchten, können Sie einen Absender öffnen:To reuse the same connection for multiple send calls, you can open a sender:
message_one = Message("First")
message_two = Message("Second")
with queue_client.get_sender() as sender:
sender.send(message_one)
sender.send(message_two)
Wenn Sie einen asynchronen Client verwenden, nutzen die oben aufgeführten Vorgänge die Async-Syntax:If you are using an asynchronous client, the above operations will use async syntax:
from azure.servicebus.aio import Message
message = Message("Hello World")
await queue_client.send(message)
message_one = Message("First")
message_two = Message("Second")
async with queue_client.get_sender() as sender:
await sender.send(message_one)
await sender.send(message_two)
Empfangen von NachrichtenReceiving messages
Nachrichten können als fortlaufender Iterator von einer Warteschlange empfangen werden.Messages can be received from a queue as a continuous iterator. Der Standardmodus für den Empfang von Nachrichten ist PeekLock. Jede Nachricht muss explizit abgeschlossen werden, damit sie aus der Warteschlange entfernt wird.The default mode for message receiving is PeekLock, which requires each message to be explicitly completed in order that it be removed from the queue.
messages = queue_client.get_receiver()
for message in messages:
print(message)
message.complete()
Die Dienstverbindung bleibt während des gesamten Iterators geöffnet.The service connection will remain open for the entirety of the iterator. Wenn Sie den Nachrichtenstream nur teilweise durchlaufen, sollten Sie den Empfänger in einer with-Anweisung ausführen, um sicherzustellen, dass die Verbindung geschlossen wurde:If you find yourself only partially iterating the message stream, you should run the receiver in a with statement to ensure the connection is closed:
with queue_client.get_receiver() as messages:
for message in messages:
print(message)
message.complete()
break
Wenn Sie einen asynchronen Client verwenden, nutzen die oben aufgeführten Vorgänge die Async-Syntax:If you are using an asynchronous client, the above operations will use async syntax:
async with queue_client.get_receiver() as messages:
async for message in messages:
print(message)
await message.complete()
break
Service Bus-Themen und -AbonnementsService Bus topics and subscriptions
Service Bus-Themen und -Abonnements sind neben Service Bus-Warteschlangen eine weitere Abstraktion, die eine 1:n-Kommunikation mit dem Muster „Veröffentlichen/Abonnieren“ bereitstellt.Service Bus topics and subscriptions are an abstraction on top of Service Bus queues that provide a one-to-many form of communication, in a publish/subscribe pattern. Nachrichten werden an ein Thema gesendet und für mindestens ein zugeordnetes Abonnement bereitgestellt. Das ist für die Skalierung in Szenarien mit sehr vielen Benutzern hilfreich.Messages are sent to a topic and delivered to one or more associated subscriptions, which is useful for scaling to large numbers of recipients.
Thema erstellenCreate topic
Hiermit wird eine neues Thema im Service Bus-Namespace erstellt.This creates a new topic within the Service Bus namespace. Wenn bereits ein Thema mit dem gleichen Namen vorhanden ist, wird ein Fehler ausgelöst.If a topic of the same name already exists an error will be raised.
sb_client.create_topic("MyTopic")
Abrufen eines ThemenclientsGet a topic client
Ein TopicClient-Element kann zum Senden von Nachrichten an das Thema sowie für andere Vorgänge verwendet werden.A TopicClient can be used to send messages to the topic, along with other operations.
topic_client = sb_client.get_topic("MyTopic")
Erstellen des AbonnementsCreate subscription
Hiermit wird ein neues Abonnement für das angegebene Thema innerhalb des Service Bus-Namespace erstellt.This creates a new subscription for the specified topic within the Service Bus namespace.
sb_client.create_subscription("MyTopic", "MySubscription")
Abrufen eines AbonnementclientsGet a subscription client
Ein SubscriptionClient-Element kann zum Empfangen von Nachrichten aus der Warteschlange sowie für weitere Vorgänge verwendet werden.A SubscriptionClient can be used to receive messages from the topic, along with other operations.
topic_client = sb_client.get_subscription("MyTopic", "MySubscription")
Migration von v0.21.1 zu v0.50.0Migration from v0.21.1 to v0.50.0
In Version 0.50.0 wurden wichtige Änderungen eingeführt.Major breaking changes were introduced in version 0.50.0. Die ursprüngliche HTTP-basierte API ist auch in v0.50.0 weiterhin verfügbar. Jedoch ist sie jetzt unter einem neuen Namespace vorhanden: azure.servicebus.control_client.The original HTTP-based API is still available in v0.50.0 - however it now exists under a new namesapce: azure.servicebus.control_client.
Sollte ich ein Upgrade durchführen?Should I upgrade?
Das neue Paket (v0.50.0) bietet keine Verbesserungen in HTTP-basierten Vorgängen über v0.21.1.The new package (v0.50.0) offers no improvements in HTTP-based operations over v0.21.1. Die HTTP-basierte API ist bis auf die Verfügbarkeit unter einem neuen Namespace identisch.The HTTP-based API is identical except that it now exists under a new namespace. Wenn Sie nur HTTP-basierte Vorgänge verwenden möchten (create_queue, delete_queue usw.), bietet Ihnen ein Upgrade zu diesem Zeitpunkt keine weiteren Vorteile.For this reason if you only wish to use HTTP-based operations (create_queue, delete_queue etc) - there will be no additional benefit in upgrading at this time.
Wie migriere ich meinen Code zur neuen Version?How do I migrate my code to the new version?
Code, der für v0.21.0 geschrieben wird, kann durch einfaches Ändern des Import-Namespace zur Version 0.50.0 portiert werden:Code written against v0.21.0 can be ported to version 0.50.0 by simply changing the import namespace:
# from azure.servicebus import ServiceBusService <- This will now raise an ImportError
from azure.servicebus.control_client import ServiceBusService
key_name = 'RootManageSharedAccessKey' # SharedAccessKeyName from Azure portal
key_value = '' # SharedAccessKey from Azure portal
sbs = ServiceBusService(service_namespace,
shared_access_key_name=key_name,
shared_access_key_value=key_value)
Verwenden von HTTP-basierten Vorgängen der Legacy-APIUsing HTTP-based operations of the legacy API
Die folgende Dokumentation beschreibt die Legacy-API und sollte verwendet werden, wenn Sie vorhandenen Code zu v0.50.0 portieren möchten, ohne weitere Änderungen vorzunehmen.The following documentation describes the legacy API and should be used for those wishing to port existing code to v0.50.0 without making any additional changes. Diese Referenz kann auch als Leitfaden dienen, wenn Sie v0.21.1 verwenden.This reference can also be used as guidance by those using v0.21.1. Wenn Sie neuen Code schreiben, empfehlen wir Ihnen, die oben beschriebene neue API zu verwenden.For those writing new code, we recommend using the new API described above.
Service Bus-WarteschlangenService Bus queues
SAS-Authentifizierung (Shared Access Signature)Shared Access Signature (SAS) authentication
Wenn Sie SAS-Authentifizierung verwenden möchten, erstellen Sie den Service Bus-Dienst wie folgt:To use Shared Access Signature authentication, create the service bus service with:
from azure.servicebus.control_client import ServiceBusService
key_name = 'RootManageSharedAccessKey' # SharedAccessKeyName from Azure portal
key_value = '' # SharedAccessKey from Azure portal
sbs = ServiceBusService(service_namespace,
shared_access_key_name=key_name,
shared_access_key_value=key_value)
ACS-Authentifizierung (Access Control Service)Access Control Service (ACS) authentication
ACS wird für neue Service Bus-Namespaces nicht unterstützt.ACS is not supported on new Service Bus namespaces. Wir empfehlen das Migrieren von Anwendungen zur SAS-Authentifizierung.We recommend migrating applications to SAS authentication. Um die ACS-Authentifizierung in einem älteren Service Bus-Namespace zu verwenden, erstellen Sie ServiceBusService mit:To use ACS authentication within an older Service Bus namesapce, create the ServiceBusService with:
from azure.servicebus.control_client import ServiceBusService
account_key = '' # DEFAULT KEY from Azure portal
issuer = 'owner' # DEFAULT ISSUER from Azure portal
sbs = ServiceBusService(service_namespace,
account_key=account_key,
issuer=issuer)
Senden und Empfangen von NachrichtenSending and receiving messages
Mit der create_queue-Methode können Sie sicherstellen, dass eine Warteschlange vorhanden ist:The create_queue method can be used to ensure a queue exists:
sbs.create_queue('taskqueue')
Anschließend kann die send_queue_message-Methode aufgerufen werden, um die Nachricht in die Warteschlange einzufügen:The send_queue_message method can then be called to insert the message into the queue:
from azure.servicebus.control_client import Message
msg = Message('Hello World!')
sbs.send_queue_message('taskqueue', msg)
Dann können Sie die send_queue_message_batch-Methode aufrufen, um mehrere Nachrichten auf einmal zu senden:The send_queue_message_batch method can then be called to send several messages at once:
from azure.servicebus.control_client import Message
msg1 = Message('Hello World!')
msg2 = Message('Hello World again!')
sbs.send_queue_message_batch('taskqueue', [msg1, msg2])
Anschließend kann die receive_queue_message-Methode aufgerufen werden, um die Nachricht aus der Warteschlange zu entfernen.It is then possible to call the receive_queue_message method to dequeue the message.
msg = sbs.receive_queue_message('taskqueue')
Service Bus-ThemenService Bus topics
Mit der create_topic-Methode können Sie ein Thema auf Serverseite erstellen:The create_topic method can be used to create a server-side topic:
sbs.create_topic('taskdiscussion')
Mit der send_topic_message-Methode kann eine Nachricht an ein Thema gesendet werden:The send_topic_message method can be used to send a message to a topic:
from azure.servicebus.control_client import Message
msg = Message(b'Hello World!')
sbs.send_topic_message('taskdiscussion', msg)
Mit der send_topic_message_batch-Methode können mehrere Nachrichten auf einmal gesendet werden:The send_topic_message_batch method can be used to send several messages at once:
from azure.servicebus.control_client import Message
msg1 = Message(b'Hello World!')
msg2 = Message(b'Hello World again!')
sbs.send_topic_message_batch('taskdiscussion', [msg1, msg2])
Beachten Sie, dass in Python 3 eine str-Nachricht UFT-8-codiert ist and Sie die Codierung in Python 2 selbst verwalten müssen.Please consider that in Python 3 a str message will be utf-8 encoded and you should have to manage your encoding yourself in Python 2.
Ein Client kann dann ein Abonnement erstellen und mit der Verarbeitung von Nachrichten beginnen, indem er die create_subscription-Methode gefolgt von der receive_subscription_message-Methode aufruft.A client can then create a subscription and start consuming messages by calling the create_subscription method followed by the receive_subscription_message method. Beachten Sie, dass vor dem Erstellen des Abonnements gesendete Nachrichten nicht empfangen werden.Please note that any messages sent before the subscription is created will not be received.
from azure.servicebus.control_client import Message
sbs.create_subscription('taskdiscussion', 'client1')
msg = Message('Hello World!')
sbs.send_topic_message('taskdiscussion', msg)
msg = sbs.receive_subscription_message('taskdiscussion', 'client1')
Event HubEvent Hub
Event Hubs ermöglichen die Erfassung von Ereignisströmen bei hohem Durchsatz von unterschiedlichen Geräten und Diensten.Event Hubs enable the collection of event streams at high throughput, from a diverse set of devices and services.
Mit der create_event_hub-Methode können Sie einen Event Hub erstellen:The create_event_hub method can be used to create an event hub:
sbs.create_event_hub('myhub')
So senden Sie ein Ereignis:To send an event:
sbs.send_event('myhub', '{ "DeviceId":"dev-01", "Temperature":"37.0" }')
Der Ereignisinhalt ist die Ereignisnachricht oder eine JSON-codierte Zeichenfolge mit mehreren Nachrichten.The event content is the event message or JSON-encoded string that contains multiple messages.
Erweiterte FunktionenAdvanced features
Brokereigenschaften und BenutzereigenschaftenBroker properties and user properties
In diesem Abschnitt wird die Verwendung der hier beschriebenen Broker- und Benutzereigenschaften erläutert:This section describes how to use Broker and User properties defined here:
sent_msg = Message(b'This is the third message',
broker_properties={'Label': 'M3'},
custom_properties={'Priority': 'Medium',
'Customer': 'ABC'}
)
Sie können „datetime“, „int“, „float“ oder „boolean“ verwenden.You can use datetime, int, float or boolean
props = {'hello': 'world',
'number': 42,
'active': True,
'deceased': False,
'large': 8555111000,
'floating': 3.14,
'dob': datetime(2011, 12, 14),
'double_quote_message': 'This "should" work fine',
'quote_message': "This 'should' work fine"}
sent_msg = Message(b'message with properties', custom_properties=props)
Aus Gründen der Kompatibilität mit einer älteren Version dieser Bibliothek kann broker_properties auch als JSON-Zeichenfolge definiert werden.For compatibility reason with old version of this library, broker_properties could also be defined as a JSON string.
In diesem Fall müssen Sie eine gültige JSON-Zeichenfolge schreiben. Von Python wird vor der Übermittlung an die Rest-API keine Überprüfung ausgeführt.If this situation, you're responsible to write a valid JSON string, no check will be made by Python before sending to the RestAPI.
broker_properties = '{"ForcePersistence": false, "Label": "My label"}'
sent_msg = Message(b'receive message',
broker_properties = broker_properties
)