Bibliotecas de Barramento de Serviço para PythonService Bus libraries for Python

  • Artigo

O Barramento de Serviço do Microsoft Azure oferece suporte a um conjunto de tecnologias middleware orientado a mensagens, baseado em nuvem, incluindo o serviço de enfileiramento de mensagens confiável e o sistema de mensagens de publicação/assinatura durável.Microsoft Azure Service Bus supports a set of cloud-based, message-oriented middleware technologies including reliable message queuing and durable publish/subscribe messaging.

Quais as novidades na v0.50.0?What's new in v0.50.0?

A partir da versão 0.50.0, uma nova API baseada em AMQP está disponível para enviar e receber mensagens.As of version 0.50.0 a new AMQP-based API is available for sending and receiving messages. Essa atualização envolve alterações de falhas.This update involves breaking changes.

Leia a Migração da v0.21.1 para v0.50.0 para determinar se a atualização é ideal para você no momento.Please read Migration from v0.21.1 to v0.50.0 to determine if upgrading is right for you at this time.

A nova API baseada em AMQP oferece desempenho e confiabilidade de transmissão de mensagens e suporte expandido a recursos daqui em diante.The new AMQP-based API offers improved message passing reliability, performance and expanded feature support going forward. A nova API também oferece suporte para operações assíncronas (com base em asyncio) para enviar, receber e manusear com mensagens.The new API also offers support for asynchronous operations (based on asyncio) for sending, receiving and handling messages.

Para obter a documentação sobre as operações baseadas em HTTP herdadas, consulte Usar operações baseadas em HTTP da API herdada.For documentation on the legacy HTTP-based operations please see Using HTTP-based operations of the legacy API.

Pré-requisitosPrerequisites

InstalaçãoInstallation

pip install azure-servicebus

Conectar-se ao Barramento de Serviço do AzureConnect to Azure Service Bus

Obter credenciaisGet credentials

Use o trecho da CLI do Azure a seguir para preencher uma variável de ambiente com a cadeia de conexão do Barramento de Serviço (você também encontra esse valor no portal do 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). O trecho é formatado para o shell do 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)

Criar clienteCreate client

Depois de ter preenchido a variável de ambiente SB_CONN_STR, você pode criar o 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)

Caso queira usar as operações assíncronas, use o namespace 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)

Filas do Barramento de ServiçoService Bus queues

As Filas do Barramento de Serviço são uma alternativa às Filas de armazenamento que podem ser úteis em cenários em que são necessários recursos de mensagens mais avançados (tamanhos maiores de mensagem, classificação das mensagens, leituras destrutivas de única operação, entrega agendada) usando a entrega de estilo push (usando sondagem longa).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).

Criar filaCreate queue

Isso cria uma nova fila no namespace do Barramento de Serviço.This creates a new queue within the Service Bus namespace. Se uma fila com o mesmo nome já existir dentro do namespace, um erro será gerado.If a queue of the same name already exists within the namespace an error will be raised.

sb_client.create_queue("MyQueue")

Também podem ser especificados parâmetros opcionais para configurar o comportamento de fila.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
)

Obter um cliente de filaGet a queue client

Um QueueClient pode ser usado para enviar e receber mensagens da fila, juntamente com outras operações.A QueueClient can be used to send and receive messages from the queue, along with other operations.

queue_client = sb_client.get_queue("MyQueue")

Enviar mensagensSending messages

O cliente de fila pode enviar uma ou mais mensagens por 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 chamada para QueueClient.send criará uma nova conexão de serviço.Each call to QueueClient.send will create a new service connection. Para reutilizar a mesma conexão para várias chamadas de envio, você pode abrir um remetente: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)

Se você estiver usando um cliente assíncrono, as operações acima usarão a sintaxe assíncrona: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)

Recebendo mensagensReceiving messages

As mensagens podem ser recebidas de uma fila como um iterador contínuo.Messages can be received from a queue as a continuous iterator. O modo padrão para o recebimento de mensagem é PeekLock, que requer que cada mensagem seja explicitamente concluída para que ela seja removida da fila.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()

A conexão de serviço permanecerá aberta para a totalidade do iterador.The service connection will remain open for the entirety of the iterator. Caso você veja que está iterando o fluxo de mensagens apenas parcialmente, o receptor deve ser executado em uma instrução with para garantir que a conexão esteja fechada: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

Se você estiver usando um cliente assíncrono, as operações acima usarão a sintaxe assíncrona: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

Tópicos e assinaturas do Barramento de ServiçoService Bus topics and subscriptions

Os tópicos e as assinaturas do Barramento de Serviço são uma abstração sobre suas filas e fornecem uma forma de comunicação de um para muitos, em um padrão de publicação/assinatura.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. As mensagens são enviadas a um tópico e entregues a uma ou mais assinaturas associadas, o que é útil para o dimensionamento de uma grande quantidade de destinatários.Messages are sent to a topic and delivered to one or more associated subscriptions, which is useful for scaling to large numbers of recipients.

Criar tópicoCreate topic

Isso cria um novo tópico no namespace do Barramento de Serviço.This creates a new topic within the Service Bus namespace. Se já houver um tópico de mesmo nome, um erro será gerado.If a topic of the same name already exists an error will be raised.

sb_client.create_topic("MyTopic")

Obter um cliente de tópicoGet a topic client

Um TopicClient pode ser usado para enviar mensagens ao tópico, juntamente com outras operações.A TopicClient can be used to send messages to the topic, along with other operations.

topic_client = sb_client.get_topic("MyTopic")

Criar assinaturaCreate subscription

Isso cria uma nova assinatura para o tópico especificado dentro do namespace do Barramento de Serviço.This creates a new subscription for the specified topic within the Service Bus namespace.

sb_client.create_subscription("MyTopic", "MySubscription")

Obter um cliente de assinaturaGet a subscription client

Um SubscriptionClient pode ser usado para receber mensagens do tópico, juntamente com outras operações.A SubscriptionClient can be used to receive messages from the topic, along with other operations.

topic_client = sb_client.get_subscription("MyTopic", "MySubscription")

Migração da v0.21.1 para v0.50.0Migration from v0.21.1 to v0.50.0

As principais alterações de falhas foram introduzidas na versão 0.50.0.Major breaking changes were introduced in version 0.50.0. A API baseada em HTTP original ainda está disponível na v0.50.0, porém, agora ela existe em um novo namespace: 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.

Devo atualizar?Should I upgrade?

O novo pacote (v0.50.0) não oferece nenhuma melhoria em operações baseadas em HTTP em relação à v0.21.1.The new package (v0.50.0) offers no improvements in HTTP-based operations over v0.21.1. A API baseada em HTTP é idêntica, com a diferença de que agora ela existe sob um novo namespace.The HTTP-based API is identical except that it now exists under a new namespace. Por esse motivo, se você quiser usar apenas operações baseadas em HTTP (create_queue, delete_queue, etc.), não há nenhum benefício adicional na atualização nesse momento.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.

Como fazer para migrar meu código para a nova versão?How do I migrate my code to the new version?

O código escrito com base na v0.21.0 pode ser portado para a versão 0.50.0 simplesmente alterando o namespace de importação: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)

Usando operações baseadas em HTTP da API herdadaUsing HTTP-based operations of the legacy API

A documentação a seguir descreve a API herdada e deve ser usada por aqueles que quiserem transferir o código existente para a v0.50.0 sem fazer nenhuma alteração 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. Essa referência também pode ser usada como uma orientação por aqueles que usam a v0.21.1.This reference can also be used as guidance by those using v0.21.1. Para aqueles escrevendo um novo código, é recomendável usar a nova API descrita acima.For those writing new code, we recommend using the new API described above.

Filas do Barramento de ServiçoService Bus queues

Autenticação da SAS (Assinatura de Acesso Compartilhado)Shared Access Signature (SAS) authentication

Para usar a autenticação de Assinatura de Acesso Compartilhado, crie o barramento de serviço com: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)

Autenticação do ACS (Serviço de Controle de Acesso)Access Control Service (ACS) authentication

Os novos namespaces do Barramento de Serviço não são mais compatíveis com o ACS.ACS is not supported on new Service Bus namespaces. É recomendável migrar aplicativos para a autenticação SAS.We recommend migrating applications to SAS authentication. Para usar a autenticação ACS dentro de um namespace do Barramento de Serviço mais antigo, crie o ServiceBusService com: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)

Enviar e receber mensagensSending and receiving messages

O método create_queue pode ser usado para garantir que exista uma fila:The create_queue method can be used to ensure a queue exists:

sbs.create_queue('taskqueue')

O método send_queue_message pode, então, ser chamado para inserir a mensagem na fila: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)

O método send_queue_message_batch pode, então, ser chamado para enviar várias mensagens de uma 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])

Assim, é possível chamar o método receive_queue_message para remover a mensagem da fila.It is then possible to call the receive_queue_message method to dequeue the message.

msg = sbs.receive_queue_message('taskqueue')

Tópicos do Barramento de ServiçoService Bus topics

O método create_topic pode ser usado para criar um tópico no servidor:The create_topic method can be used to create a server-side topic:

sbs.create_topic('taskdiscussion')

O método send_topic_message pode ser usado para enviar uma mensagem para um tópico: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)

O método send_topic_message_batch pode ser usado para enviar várias mensagens de uma 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])

Leve em consideração que, no Python 3, uma mensagem str será codificada em utf-8 e você deve ter de gerenciar sua codificação por conta própria no 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.

Um cliente pode criar uma assinatura e começar a consumir mensagens chamando o método create_subscription seguido do 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. Observe que todas as mensagens enviadas antes da assinatura ser criada não serão recebidas.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')

Hub de eventoEvent Hub

Os Hubs de Eventos habilitam a coleção de fluxos de eventos com alta taxa de transferência em um conjunto diversificado de dispositivos e serviços.Event Hubs enable the collection of event streams at high throughput, from a diverse set of devices and services.

O método create_event_hub pode ser usado para criar um hub de eventos:The create_event_hub method can be used to create an event hub:

sbs.create_event_hub('myhub')

Para enviar um evento:To send an event:

sbs.send_event('myhub', '{ "DeviceId":"dev-01", "Temperature":"37.0" }')

O conteúdo do evento é a mensagem de evento ou uma cadeia de caracteres codificada em JSON que contém várias mensagens.The event content is the event message or JSON-encoded string that contains multiple messages.

Recursos avançadosAdvanced features

Propriedades de agente e propriedades de usuárioBroker properties and user properties

Esta seção descreve como usar as propriedades do Agente e do Usuário definidas aqui: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'}
            )

É possível usar datetime, int, float ou booleanoYou 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 questões de compatibilidade com a versão antiga dessa biblioteca, broker_properties também pode ser definido como uma cadeia de caracteres JSON.For compatibility reason with old version of this library, broker_properties could also be defined as a JSON string. Se essa for a situação, você é o responsável por gravar uma cadeia de caracteres JSON válida, e nenhuma verificação será feita pelo Python antes do envio à API 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
)

Próximas etapasNext Steps