Bibliothèques Service Bus pour PythonService Bus libraries for Python
Microsoft Azure Service Bus prend en charge un ensemble de technologies middleware Cloud orientées messages, notamment la mise en file d’attente de messages fiable et la messagerie de publication/abonnement durable.Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging.
Nouveautés de la version 0.50.0What's new in v0.50.0?
La version 0.50.0 fournit une nouvelle API basée sur AMQP pour l’envoi et la réception des messages.As of version 0.50.0 a new AMQP-based API is available for sending and receiving messages. Cette mise à jour introduit des changements cassants.This update involves breaking changes.
Lisez la section Migration de la version 0.21.1 vers la version 0.50.0 pour déterminer si vous avez ou non intérêt à faire la mise à niveau maintenant.Please read Migration from v0.21.1 to v0.50.0 to determine if upgrading is right for you at this time.
La nouvelle API basée sur AMQP améliore la fiabilité, les performances et la prise en charge des fonctionnalités de la transmission des messages.The new AMQP-based API offers improved message passing reliability, performance and expanded feature support going forward. Cette API permet également d’utiliser des opérations asynchrones (basées sur asyncio) pour l’envoi, la réception et le traitement des messages.The new API also offers support for asynchronous operations (based on asyncio) for sending, receiving and handling messages.
Pour plus d’informations sur les opérations HTTP héritées, consultez Utilisation d’opérations HTTP de l’API héritée.For documentation on the legacy HTTP-based operations please see Using HTTP-based operations of the legacy API.
PrérequisPrerequisites
- Abonnement Azure - Créer un compte gratuitAzure subscription - Create a free account
- Informations d’identification de gestion et d’espace de noms Azure Service BusAzure Service Bus namespace and management credentials
- Python 2.7-3.7Python 2.7-3.7
InstallationInstallation
pip install azure-servicebus
Se connecter à Azure Service BusConnect to Azure Service Bus
Récupérer les informations d’identificationGet credentials
Utilisez l’extrait de code Azure CLI ci-dessous pour remplir une variable d’environnement avec la chaîne de connexion Service Bus (vous pouvez également trouver cette valeur dans le portail Azure).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). L’extrait de code est mis en forme pour l’interpréteur de commandes Bash.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)
Créer un clientCreate client
Une fois que vous avez rempli la variable d’environnement SB_CONN_STR, vous pouvez créer le ServiceBusClient.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)
Si vous souhaitez utiliser des opérations asynchrones, utilisez l’espace de noms azure.servicebus.aio.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)
Files d’attente Service BusService Bus queues
Les files d’attente Service Bus sont une alternative aux files d’attente de stockage qui peuvent être utiles dans les scénarios requérant des fonctionnalités de messagerie plus avancées (messages plus volumineux, classement des messages, lectures destructives à opération unique, remise planifiée) via une remise de type push (interrogation sur le long terme).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).
Créer la file d’attenteCreate queue
Cette opération crée une file d’attente dans l’espace de noms Service Bus.This creates a new queue within the Service Bus namespace. Une erreur se produit si une file d’attente du même nom existe déjà dans l’espace de noms.If a queue of the same name already exists within the namespace an error will be raised.
sb_client.create_queue("MyQueue")
Vous pouvez également définir des paramètres facultatifs pour configurer le comportement de la file d’attente.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
)
Obtenir un client de file d'attenteGet a queue client
Un QueueClient peut être utilisé pour la transmission des messages avec la file d’attente, ainsi que d’autres opérations.A QueueClient can be used to send and receive messages from the queue, along with other operations.
queue_client = sb_client.get_queue("MyQueue")
Envoi de messagesSending messages
Le client de file d’attente peut envoyer un ou plusieurs messages à la fois :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])
Chaque appel à QueueClient.send crée une connexion au service.Each call to QueueClient.send will create a new service connection. Si vous souhaitez réutiliser la même connexion pour plusieurs appels d’envoi, vous pouvez ouvrir un expéditeur (sender) :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)
Si vous utilisez un client asynchrone, les opérations ci-dessus doivent respecter la syntaxe async :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)
Réception de messagesReceiving messages
Les messages peuvent être reçus d’une file d’attente en tant qu’itérateur continu.Messages can be received from a queue as a continuous iterator. Le mode par défaut pour la réception des messages est PeekLock, qui nécessite que chaque message ait été traité explicitement avant d’être supprimé de la file d’attente.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()
La connexion au service reste ouverte durant l’intégralité de l’itérateur.The service connection will remain open for the entirety of the iterator. Si vous voyez que le flux des messages est seulement itéré partiellement, vous devez exécuter le récepteur (receiver) dans une instruction with pour vous assurer que la connexion est fermée :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
Si vous utilisez un client asynchrone, les opérations ci-dessus doivent respecter la syntaxe async :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
Rubriques et abonnements Service BusService Bus topics and subscriptions
Les rubriques et abonnements Service Bus constituent une couche d’abstraction au-dessus des files d’attente Service Bus afin de fournir une forme de communication un-à-plusieurs dans un modèle de publication/abonnement.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. Les messages sont envoyés à une rubrique et sont remis à un ou plusieurs abonnements associés, ce qui facilite l’envoi à un grand nombre de destinataires.Messages are sent to a topic and delivered to one or more associated subscriptions, which is useful for scaling to large numbers of recipients.
Créer une rubriqueCreate topic
Cette opération crée une rubrique dans l’espace de noms Service Bus.This creates a new topic within the Service Bus namespace. Une erreur se produit si une rubrique du même nom existe déjà dans l’espace de noms.If a topic of the same name already exists an error will be raised.
sb_client.create_topic("MyTopic")
Obtenir un client de rubriqueGet a topic client
Un TopicClient peut être utilisé pour l’envoi de messages à la rubrique, ainsi que d’autres opérations.A TopicClient can be used to send messages to the topic, along with other operations.
topic_client = sb_client.get_topic("MyTopic")
Créer un abonnementCreate subscription
Cette opération crée un abonnement pour la rubrique spécifiée dans l’espace de noms Service Bus.This creates a new subscription for the specified topic within the Service Bus namespace.
sb_client.create_subscription("MyTopic", "MySubscription")
Obtenir un client d’abonnementGet a subscription client
Un SubscriptionClient peut être utilisé pour la réception de messages de la rubrique, ainsi que d’autres opérations.A SubscriptionClient can be used to receive messages from the topic, along with other operations.
topic_client = sb_client.get_subscription("MyTopic", "MySubscription")
Migration de la version 0.21.1 vers la version 0.50.0Migration from v0.21.1 to v0.50.0
Des changements cassants ont été introduits dans la version 0.50.0.Major breaking changes were introduced in version 0.50.0. L’API HTTP initiale est toujours disponible dans la version 0.50.0, mais elle est maintenant implémentée dans le nouvel espace de noms 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.
Dois-je effectuer la mise à niveau ?Should I upgrade?
Le nouveau package (version 0.50.0) n’apporte pas d’améliorations pour les opérations HTTP par rapport à la version 0.21.1.The new package (v0.50.0) offers no improvements in HTTP-based operations over v0.21.1. L’API HTTP est identique, à ceci près qu’elle est maintenant implémentée dans un nouvel espace de noms.The HTTP-based API is identical except that it now exists under a new namespace. Pour cette raison, si vous souhaitez uniquement utiliser des opérations HTTP (create_queue, delete_queue, etc.), il n’y a pas d’intérêt particulier à faire cette mise à niveau.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.
Comment migrer mon code vers la nouvelle version ?How do I migrate my code to the new version?
Le code écrit pour la version 0.21.0 peut être migré vers la version 0.50.0 simplement en changeant l’espace de noms import :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)
Utilisation d’opérations HTTP de l’API héritéeUsing HTTP-based operations of the legacy API
Les sections suivantes décrivent l’API héritée et sont destinées à ceux qui souhaitent migrer du code existant vers la version 0.50.0 sans apporter d’autres changements.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. Ces informations de référence peuvent également apporter des conseils utiles aux utilisateurs de la version 0.21.1.This reference can also be used as guidance by those using v0.21.1. Nous recommandons à ceux qui écrivent du code nouveau d’utiliser la nouvelle API décrite ci-dessus.For those writing new code, we recommend using the new API described above.
Files d’attente Service BusService Bus queues
Authentification SAS (par signature d’accès partagé)Shared Access Signature (SAS) authentication
Pour utiliser l’authentification par signature d’accès partagé, créez le service Service Bus avec les éléments suivants :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)
Authentification ACS (Access Control Service)Access Control Service (ACS) authentication
ACS n’est pas pris en charge dans les nouveaux espaces de noms Service Bus.ACS is not supported on new Service Bus namespaces. Nous vous recommandons de migrer vos applications vers l’authentification SAS.We recommend migrating applications to SAS authentication. Pour utiliser l’authentification ACS dans un espace de noms Service Bus d’une version antérieure, créez ServiceBusService comme ci-dessous :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)
Envoi et réception des messagesSending and receiving messages
La méthode create_queue peut être utilisée pour garantir l’existence d’une file d’attente :The create_queue method can be used to ensure a queue exists:
sbs.create_queue('taskqueue')
Vous pouvez ensuite appeler la méthode send_queue_message pour insérer le message dans la file d’attente :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)
La méthode send_queue_message_batch peut ensuite être appelée pour envoyer plusieurs messages en même temps :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])
Il est ensuite possible d’appeler la méthode receive_queue_message pour retirer le message de la file d’attente.It is then possible to call the receive_queue_message method to dequeue the message.
msg = sbs.receive_queue_message('taskqueue')
Rubriques Service BusService Bus topics
La méthode create_topic peut ensuite servir à créer une rubrique côté serveur :The create_topic method can be used to create a server-side topic:
sbs.create_topic('taskdiscussion')
Vous pouvez utiliser la méthode send_topic_message pour envoyer un message à une rubrique :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)
Vous pouvez utiliser la méthode send_topic_message_batch pour envoyer plusieurs messages en même temps :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])
N’oubliez pas que, dans Python 3, un message str présente le codage utf-8. Vous devez gérer votre codage vous-même, dans Python 2.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.
Un client peut ensuite créer un abonnement et commencer à consommer des messages en appelant la méthode create_subscription, puis la méthode receive_subscription_message.A client can then create a subscription and start consuming messages by calling the create_subscription method followed by the receive_subscription_message method. N’oubliez pas que les messages envoyés avant la création de l’abonnement n’arriveront pas à destination.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
Les hubs Event Hubs permettent la collecte de flux d’événements à débit élevé, depuis un ensemble varié d’appareils et de services.Event Hubs enable the collection of event streams at high throughput, from a diverse set of devices and services.
La méthode create_event_hub peut permettre de créer un hub Event Hub :The create_event_hub method can be used to create an event hub:
sbs.create_event_hub('myhub')
Pour envoyer un événement, procédez comme suit :To send an event:
sbs.send_event('myhub', '{ "DeviceId":"dev-01", "Temperature":"37.0" }')
Le contenu de l’événement correspond au message d’événement ou à une chaîne codée au format JSON qui contient plusieurs messages.The event content is the event message or JSON-encoded string that contains multiple messages.
Fonctionnalités avancéesAdvanced features
Propriétés du répartiteur et de l’utilisateurBroker properties and user properties
Cette section explique comment utiliser les propriétés du répartiteur et de l’utilisateur définies ici :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'}
)
Vous pouvez utiliser les valeurs datetime, int, float ou boolean.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)
Pour des raisons de compatibilité avec l’ancienne version de cette bibliothèque, l’élément broker_properties peut également être défini comme une chaîne JSON.For compatibility reason with old version of this library, broker_properties could also be defined as a JSON string.
Si tel est le cas, vous devez écrire une chaîne JSON valide. Python n’effectuera aucune vérification avant l’envoi à l’API RestAPI.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
)