Bibliotecas de Service Bus para PythonService Bus libraries for Python
Microsoft Azure Service Bus admite un conjunto de tecnologías de middleware basadas en la nube y orientadas a mensajes, incluidas una cola de mensajes de confianza y una mensajería de publicación/suscripción duradera.Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging.
Novedades de la versión 0.50.0What's new in v0.50.0?
A partir de la versión 0.50.0, hay una nueva API basada en AMQP disponible para enviar y recibir mensajes.As of version 0.50.0 a new AMQP-based API is available for sending and receiving messages. Esta actualización implica cambios importantes.This update involves breaking changes.
Lea el documento de migración de v0.21.1 a v0.50.0 para determinar si debe actualizar en este momento.Please read Migration from v0.21.1 to v0.50.0 to determine if upgrading is right for you at this time.
La nueva API basada en AMQP ofrece confiabilidad, rendimiento, compatibilidad y más características para el envío de mensajes.The new AMQP-based API offers improved message passing reliability, performance and expanded feature support going forward. También ofrece compatibilidad para las operaciones asincrónicas (basadas en asyncio) para enviar, recibir y controlar los mensajes.The new API also offers support for asynchronous operations (based on asyncio) for sending, receiving and handling messages.
Para ver la documentación sobre las operaciones basadas en HTTP heredadas, consulte Uso de las operaciones basadas en HTTP de la API heredada.For documentation on the legacy HTTP-based operations please see Using HTTP-based operations of the legacy API.
Requisitos previosPrerequisites
- Una suscripción de Azure (cree una cuenta gratuita).Azure subscription - Create a free account
- Un espacio de nombres de Service Bus y credenciales de administración de Azure.Azure Service Bus namespace and management credentials
- Python 2.7-3.7Python 2.7-3.7
InstalaciónInstallation
pip install azure-servicebus
Conexión a Azure Service BusConnect to Azure Service Bus
Obtener credencialesGet credentials
Use el siguiente fragmento de la CLI de Azure para rellenar una variable de entorno con la cadena de conexión de Service Bus (también puede encontrar este valor en 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). El fragmento de código tiene el formato para el shell de 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)
Crear el clienteCreate client
Una vez que ha rellenado la variable de entorno SB_CONN_STR, puede crear el cliente de Service Bus.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 desea usar operaciones asincrónicas, use el espacio de nombres 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)
Colas de Service BusService Bus queues
Las colas de Service Bus son una alternativa a las colas de Storage que podrían ser útiles en escenarios en los que se necesitan características de mensajería más avanzadas (tamaños de mensaje más grandes, orden de los mensajes, lecturas destructivas de una sola operación o entrega programada) con entrega de inserción (mediante sondeo largo).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).
Crear colaCreate queue
Se crea una nueva cola en el espacio de nombres de Service Bus.This creates a new queue within the Service Bus namespace. Si ya existe una cola con el mismo nombre en el espacio de nombres, se producirá un error.If a queue of the same name already exists within the namespace an error will be raised.
sb_client.create_queue("MyQueue")
También se pueden especificar parámetros opcionales para configurar el comportamiento de la cola.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
)
Obtener un cliente de colaGet a queue client
Se puede usar QueueClient para enviar y recibir mensajes de la cola, además de otras operaciones.A QueueClient can be used to send and receive messages from the queue, along with other operations.
queue_client = sb_client.get_queue("MyQueue")
Envío de mensajesSending messages
El cliente de cola puede enviar uno o varios mensajes a la vez: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])
Cada llamada a QueueClient.send creará una nueva conexión de servicio.Each call to QueueClient.send will create a new service connection. Para reutilizar la misma conexión para varias llamadas de envío, puede abrir un remitente: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 usa a un cliente asincrónico, las operaciones anteriores usará la sintaxis de 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)
Recepción de mensajesReceiving messages
Los mensajes se pueden recibir de una cola como un iterador continuo.Messages can be received from a queue as a continuous iterator. El modo predeterminado para la recepción del mensaje es PeekLock, que requiere que cada mensaje se complete explícitamente para poder quitarlo de la cola.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 conexión de servicio permanecerá abierta durante todo el iterador.The service connection will remain open for the entirety of the iterator. Si detecta que la iteración por la secuencia de mensajes se realiza solo parcialmente, debe ejecutar el receptor una instrucción with para asegurarse de que la conexión se cierra: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 usa a un cliente asincrónico, las operaciones anteriores usará la sintaxis de 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
Temas y suscripciones de Service BusService Bus topics and subscriptions
Los temas y las suscripciones de Service Bus son una abstracción que se sitúan encima de las colas de Service Bus y que proporcionan una o varias formas de comunicación según un modelo publicación/suscripción.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. Los mensajes se envían a un tema y entregan a una o varias suscripciones asociadas, lo que resulta útil para escalar a un gran número de destinatarios.Messages are sent to a topic and delivered to one or more associated subscriptions, which is useful for scaling to large numbers of recipients.
Crear temaCreate topic
Se crea un nuevo tema en el espacio de nombres de Service Bus.This creates a new topic within the Service Bus namespace. Si ya existe un tema con el mismo nombre, se producirá un error.If a topic of the same name already exists an error will be raised.
sb_client.create_topic("MyTopic")
Obtener un cliente de temaGet a topic client
Se puede usar TopicClient para enviar mensajes al tema, además de otras operaciones.A TopicClient can be used to send messages to the topic, along with other operations.
topic_client = sb_client.get_topic("MyTopic")
Creación de una suscripciónCreate subscription
Se crea una nueva suscripción para el tema especificado dentro del espacio de nombres de Service Bus.This creates a new subscription for the specified topic within the Service Bus namespace.
sb_client.create_subscription("MyTopic", "MySubscription")
Obtener un cliente de suscripciónGet a subscription client
Se puede usar SubscriptionClient para recibir mensajes del tema, además de otras operaciones.A SubscriptionClient can be used to receive messages from the topic, along with other operations.
topic_client = sb_client.get_subscription("MyTopic", "MySubscription")
Migración de v0.21.1 a v0.50.0Migration from v0.21.1 to v0.50.0
Se introdujeron cambios importantes en la versión 0.50.0.Major breaking changes were introduced in version 0.50.0. La API basada en HTTP original sigue estando disponible en la versión 0.50.0; sin embargo, ahora existe en un espacio de nombres nuevo: 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.
¿Debería actualizar?Should I upgrade?
El nuevo paquete (v0.50.0) no ofrece mejoras en las operaciones basadas en HTTP respecto a v0.21.1.The new package (v0.50.0) offers no improvements in HTTP-based operations over v0.21.1. La API basada en HTTP es idéntica, salvo que ahora existe en un nuevo espacio de nombres.The HTTP-based API is identical except that it now exists under a new namespace. Por este motivo, si solo desea usar operaciones basadas en HTTP (create_queue, delete_queue etc), actualizar en este momento no aportará ninguna ventaja adicional.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.
¿Cómo migro mi código a la nueva versión?How do I migrate my code to the new version?
El código escrito en la versión 0.21.0 se puede portar a la versión 0.50.0 simplemente cambiando el espacio de nombres de importación: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)
Uso de las operaciones basadas en HTTP de la API heredadaUsing HTTP-based operations of the legacy API
En la documentación siguiente se describe la API heredada, que deberán usarla aquellos que quieran portal el código existente desde la versión 0.50.0 sin realizar ningún cambio adicional.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. Esta referencia también sirve como guía para los usuarios de la versión 0.21.1.This reference can also be used as guidance by those using v0.21.1. Para los que están escribiendo código nuevo, se recomienda usar la nueva API descrita anteriormente.For those writing new code, we recommend using the new API described above.
Colas de Service BusService Bus queues
Autenticación de Firma de acceso compartido (SAS)Shared Access Signature (SAS) authentication
Para usar la autenticación con firma de acceso compartido, cree el servicio de Service Bus con: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)
Autenticación de Access Control Service (ACS)Access Control Service (ACS) authentication
ACS no se admite en los nuevos espacios de nombres de Service Bus.ACS is not supported on new Service Bus namespaces. Se recomienda migrar las aplicaciones a la autenticación de SAS.We recommend migrating applications to SAS authentication. Para usar la autenticación de ACS dentro de un espacio de nombres de Service Bus anterior, cree ServiceBusService con: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)
Envío y recepción de mensajesSending and receiving messages
El método create_queue se puede utilizar para asegurarse de existe que una cola:The create_queue method can be used to ensure a queue exists:
sbs.create_queue('taskqueue')
A continuación, se puede llamar al método send_queue_message para insertar el mensaje en la cola: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)
Se puede llamar al método send_queue_message_batch para enviar varios mensajes a la vez: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])
A continuación, es posible llamar al método receive_queue_message para eliminar el mensaje de la cola.It is then possible to call the receive_queue_message method to dequeue the message.
msg = sbs.receive_queue_message('taskqueue')
Temas de Service BusService Bus topics
El método create_topic se puede utilizar para crear un tema de servidor:The create_topic method can be used to create a server-side topic:
sbs.create_topic('taskdiscussion')
El método send_topic_message se puede utilizar para enviar un mensaje a un tema: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)
El método send_topic_message_batch se puede utilizar para enviar varios mensajes a la vez: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])
Tenga en cuenta que, en Python 3, un mensaje de tipo cadena se codificará en utf-8 y debe administrar la codificación por sí mismo en 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.
Después, un cliente puede crear una suscripción y empezar a consumir mensajes mediante una llamada al método create_subscription seguida de otra al método 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. Tenga en cuenta que no se recibirán los mensajes enviados antes de crear la suscripción.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')
Centro de eventosEvent Hub
Event Hubs permite recopilar secuencias de eventos con un alto rendimiento desde una amplia variedad de dispositivos y servicios.Event Hubs enable the collection of event streams at high throughput, from a diverse set of devices and services.
El método create_event_hub se puede utilizar para crear un centro de eventos:The create_event_hub method can be used to create an event hub:
sbs.create_event_hub('myhub')
Para enviar un evento:To send an event:
sbs.send_event('myhub', '{ "DeviceId":"dev-01", "Temperature":"37.0" }')
El contenido del evento es el mensaje del evento o una cadena codificada en JSON que contiene varios mensajes.The event content is the event message or JSON-encoded string that contains multiple messages.
Características avanzadasAdvanced features
Propiedades de agente y de usuarioBroker properties and user properties
En esta sección se describe cómo utilizar las propiedades de agente y de usuario definidas aquí: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'}
)
Puede usar datetime, int, float o booleanYou 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)
Por motivos de compatibilidad con la versión anterior de esta biblioteca, broker_properties también se puede definir como una cadena JSON.For compatibility reason with old version of this library, broker_properties could also be defined as a JSON string.
Si esta es la situación, es responsable de escribir una cadena JSON válida, ya que Python no realizará ninguna comprobación antes del envío a la API de REST.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
)