Enviar mensagens para um tópico do Barramento de Serviço do Azure e receber mensagens de assinaturas para o tópico (Python)
Neste tutorial, vai concluir os seguintes passos:
- Criar um espaço de nomes do Service Bus com o Portal do Azure.
- Criar um tópico do Service Bus com o portal do Azure.
- Criar uma subscrição do Service Bus com o portal do Azure.
- Escreva um aplicativo Python para usar o pacote azure-servicebus para:
- Envie um conjunto de mensagens para o tópico.
- Receba essas mensagens da assinatura.
Nota
Este guia de início rápido fornece instruções passo a passo para um cenário simples de enviar um lote de mensagens para um tópico do Service Bus e receber essas mensagens de uma assinatura do tópico. Você pode encontrar exemplos de Python pré-criados para o Barramento de Serviço do Azure no repositório do SDK do Azure para Python no GitHub.
Pré-requisitos
- Uma subscrição do Azure.
- Python 3.8 ou superior
Nota
Este tutorial funciona com exemplos que você pode copiar e executar usando Python. Para obter instruções sobre como criar um aplicativo Python, consulte Criar e implantar um aplicativo Python em um site do Azure. Para obter mais informações sobre como instalar pacotes usados neste tutorial, consulte o Guia de Instalação do Python.
Criar um espaço de nomes no portal do Azure
Para começar a utilizar as entidades de mensagens do Service Bus no Azure, tem de, primeiro, criar um espaço de nomes que seja exclusivo em todo o Azure. Um namespace fornece um contêiner de escopo para recursos do Service Bus (filas, tópicos, etc.) em seu aplicativo.
Para criar um espaço de nomes:
Inicie sessão no portal do Azure.
Navegue até a página Todos os serviços.
Na barra de navegação esquerda, selecione Integração na lista de categorias, passe o mouse sobre o Service Bus e selecione + o botão no bloco do Service Bus.
Na marca Basics da página Criar namespace, siga estas etapas:
Em Assinatura, escolha uma assinatura do Azure na qual criar o namespace.
Para Grupo de recursos, escolha um grupo de recursos existente ou crie um novo.
Insira um nome para o namespace. O nome do namespace deve aderir às seguintes convenções de nomenclatura:
- O nome deve ser exclusivo no Azure. O sistema verifica imediatamente a disponibilidade do nome.
- O comprimento do nome é de pelo menos 6 e no máximo 50 caracteres.
- O nome pode conter apenas letras, números hífenes
-
. - O nome deve começar com uma letra e terminar com uma letra ou número.
- O nome não termina com
-sb
ou-mgmt
.
Em Local, escolha a região na qual seu namespace deve ser hospedado.
Em Nível de preço, selecione o nível de preço (Básico, Standard ou Premium) para o namespace. Para este início rápido, selecione Padrão.
Se você selecionar a camada Premium , selecione se é possível habilitar a replicação geográfica para o namespace. O recurso de replicação geográfica garante que os metadados e os dados de um namespace sejam replicados continuamente de uma região primária para uma ou mais regiões secundárias.
Importante
Se você quiser usar tópicos e assinaturas, escolha Standard ou Premium. Não há suporte para tópicos/assinaturas no nível de preço Básico.
Se você selecionou o nível de preço Premium, especifique o número de unidades de mensagens. A camada premium fornece isolamento de recursos no nível de CPU e memória para que cada carga de trabalho seja executada isoladamente. Este contentor de recursos é designado por unidade de mensagens. Um namespace premium tem pelo menos uma unidade de mensagens. Você pode selecionar 1, 2, 4, 8 ou 16 unidades de mensagens para cada namespace Premium do Service Bus. Para obter mais informações, consulte Mensagens Premium do Service Bus.
Selecione Rever + criar na parte inferior da página.
Na página Rever + criar, reveja as definições e selecione Criar.
Quando a implantação do recurso for bem-sucedida, selecione Ir para o recurso na página de implantação.
Você vê a home page do namespace do barramento de serviço.
Criar um tópico com o portal do Azure
Na página Namespace do Service Bus, expanda Entidades no menu de navegação à esquerda e selecione Tópicos no menu à esquerda.
Selecione + Tópico na barra de ferramentas.
Insira um nome para o tópico. Deixe as outras opções com os valores predefinidos.
Selecione Criar.
Criar uma subscrição para o tópico
Selecione o tópico que você criou na seção anterior.
Na página Tópico do Service Bus, selecione + Assinatura na barra de ferramentas.
Na página Criar subscrição, siga estes passos:
Digite S1 para o nome da assinatura.
Digite 3 para Contagem máxima de entregas.
Em seguida, selecione Criar para criar a assinatura.
Autenticar o aplicativo no Azure
Este início rápido mostra duas maneiras de se conectar ao Barramento de Serviço do Azure: sem senha e cadeia de conexão.
A primeira opção mostra como usar sua entidade de segurança no Microsoft Entra ID e RBAC (controle de acesso baseado em função) para se conectar a um namespace do Service Bus. Você não precisa se preocupar em ter uma cadeia de conexão codificada em seu código ou em um arquivo de configuração ou em um armazenamento seguro como o Azure Key Vault.
A segunda opção mostra como usar uma cadeia de conexão para se conectar a um namespace do Service Bus. Se você for novo no Azure, poderá achar a opção de cadeia de conexão mais fácil de seguir. Recomendamos o uso da opção sem senha em aplicativos e ambientes de produção do mundo real. Para obter mais informações, consulte Autenticação e autorização. Você também pode ler mais sobre autenticação sem senha na página de visão geral.
Atribuir funções ao usuário do Microsoft Entra
Ao desenvolver localmente, verifique se a conta de usuário que se conecta ao Barramento de Serviço do Azure tem as permissões corretas. Você precisará da função Proprietário de Dados do Barramento de Serviço do Azure para enviar e receber mensagens. Para atribuir essa função a si mesmo, você precisará da função de Administrador de Acesso de Usuário ou de outra função que inclua a Microsoft.Authorization/roleAssignments/write
ação. Você pode atribuir funções do RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Saiba mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.
O exemplo a seguir atribui a Azure Service Bus Data Owner
função à sua conta de usuário, que fornece acesso total aos recursos do Barramento de Serviço do Azure. Em um cenário real, siga o Princípio do Menor Privilégio para dar aos usuários apenas as permissões mínimas necessárias para um ambiente de produção mais seguro.
Funções internas do Azure para o Barramento de Serviço do Azure
Para o Barramento de Serviço do Azure, o gerenciamento de namespaces e todos os recursos relacionados por meio do portal do Azure e da API de gerenciamento de recursos do Azure já está protegido usando o modelo RBAC do Azure. O Azure fornece as seguintes funções internas do Azure para autorizar o acesso a um namespace do Service Bus:
- Proprietário de Dados do Barramento de Serviço do Azure: habilita o acesso a dados ao namespace do Barramento de Serviço e suas entidades (filas, tópicos, assinaturas e filtros). Um membro dessa função pode enviar e receber mensagens de filas ou tópicos/assinaturas.
- Remetente de Dados do Barramento de Serviço do Azure: use essa função para conceder acesso de envio ao namespace do Barramento de Serviço e suas entidades.
- Recetor de Dados do Barramento de Serviço do Azure: use essa função para conceder acesso de recebimento ao namespace do Barramento de Serviço e suas entidades.
Se você quiser criar uma função personalizada, consulte Direitos necessários para operações do Service Bus.
Adicionar usuário do Microsoft Entra à função de Proprietário do Barramento de Serviço do Azure
Adicione seu nome de usuário do Microsoft Entra à função Proprietário de Dados do Barramento de Serviço do Azure no nível do namespace do Barramento de Serviço. Ele permitirá que um aplicativo em execução no contexto da sua conta de usuário envie mensagens para uma fila ou um tópico e receba mensagens de uma fila ou da assinatura de um tópico.
Importante
Na maioria dos casos, levará um ou dois minutos para que a atribuição de função se propague no Azure. Em casos raros, pode demorar até oito minutos. Se você receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos e tente novamente.
Se você não tiver a página Namespace do Service Bus aberta no portal do Azure, localize seu namespace do Service Bus usando a barra de pesquisa principal ou a navegação à esquerda.
Na página de visão geral, selecione Controle de acesso (IAM) no menu à esquerda.
Na página Controle de acesso (IAM), selecione a guia Atribuições de função.
Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.
Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, procure
Azure Service Bus Data Owner
e selecione o resultado correspondente. Em seguida, escolha Avançar.Em Atribuir acesso a, selecione Utilizador, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.
Na caixa de diálogo, procure seu nome de usuário do Microsoft Entra (geralmente seu endereço de e-mail user@domain ) e escolha Selecionar na parte inferior da caixa de diálogo.
Selecione Rever + atribuir para ir para a página final e, em seguida , Rever + atribuir novamente para concluir o processo.
Configuração de código
Para seguir este guia de início rápido usando a autenticação sem senha e sua própria conta do Azure:
- Instale a CLI do Azure.
- Entre com sua conta do Azure no terminal ou prompt de comando com
az login
. - Use a mesma conta quando adicionar a função apropriada ao seu recurso mais adiante no tutorial.
- Execute o código do tutorial no mesmo terminal ou prompt de comando.
Importante
Certifique-se de que inicia sessão com az login
o . A DefaultAzureCredential
classe no código sem senha usa as credenciais da CLI do Azure para autenticar com a ID do Microsoft Entra.
Para usar o código sem senha, você precisará especificar um:
- namespace de barramento de serviço totalmente qualificado, por exemplo: <service-bus-namespace.servicebus.windows.net>
- Nome do tópico
- nome da subscrição
Use pip para instalar pacotes
Para instalar os pacotes Python necessários para este tutorial do Service Bus, abra um prompt de comando que tenha Python em seu caminho. Altere o diretório para a pasta onde você deseja ter suas amostras.
Instalar pacotes:
pip install azure-servicebus pip install azure-identity pip install aiohttp
Enviar mensagens para um tópico
O código de exemplo a seguir mostra como enviar um lote de mensagens para um tópico do Service Bus. Consulte os comentários de código para obter detalhes.
Abra seu editor favorito, como o Visual Studio Code, crie um send.py de arquivo e adicione o seguinte código a ele.
Adicione as seguintes instruções
import
.import asyncio from azure.servicebus.aio import ServiceBusClient from azure.servicebus import ServiceBusMessage from azure.identity.aio import DefaultAzureCredential
Adicione as constantes e defina uma credencial.
FULLY_QUALIFIED_NAMESPACE = "FULLY_QUALIFIED_NAMESPACE" TOPIC_NAME = "TOPIC_NAME" credential = DefaultAzureCredential()
Importante
- Substitua
FULLY_QUALIFIED_NAMESPACE
pelo namespace totalmente qualificado para seu namespace do Service Bus. - Substitua
TOPIC_NAME
pelo nome do tópico.
No código anterior, você usou a classe da biblioteca de
DefaultAzureCredential
cliente do Azure Identity. Quando o aplicativo é executado localmente durante o desenvolvimento,DefaultAzureCredential
ele descobre e autentica automaticamente no Azure usando a conta com a qual você fez login na CLI do Azure. Quando o aplicativo é implantado no Azure,DefaultAzureCredential
pode autenticar seu aplicativo no Microsoft Entra ID por meio de uma identidade gerenciada sem alterações de código.- Substitua
Adicione um método para enviar uma única mensagem.
async def send_single_message(sender): # Create a Service Bus message message = ServiceBusMessage("Single Message") # send the message to the topic await sender.send_messages(message) print("Sent a single message")
O remetente é um objeto que atua como um cliente para o tópico que você criou. Você irá criá-lo mais tarde e enviá-lo como um argumento para esta função.
Adicione um método para enviar uma lista de mensagens.
async def send_a_list_of_messages(sender): # Create a list of messages messages = [ServiceBusMessage("Message in list") for _ in range(5)] # send the list of messages to the topic await sender.send_messages(messages) print("Sent a list of 5 messages")
Adicione um método para enviar um lote de mensagens.
async def send_batch_message(sender): # Create a batch of messages async with sender: batch_message = await sender.create_message_batch() for _ in range(10): try: # Add a message to the batch batch_message.add_message(ServiceBusMessage("Message inside a ServiceBusMessageBatch")) except ValueError: # ServiceBusMessageBatch object reaches max_size. # New ServiceBusMessageBatch object can be created here to send more data. break # Send the batch of messages to the topic await sender.send_messages(batch_message) print("Sent a batch of 10 messages")
Crie um cliente do Service Bus e, em seguida, um objeto remetente de tópico para enviar mensagens.
async def run(): # create a Service Bus client using the credential. async with ServiceBusClient( fully_qualified_namespace=FULLY_QUALIFIED_NAMESPACE, credential=credential, logging_enable=True) as servicebus_client: # Get a Topic Sender object to send messages to the topic sender = servicebus_client.get_topic_sender(topic_name=TOPIC_NAME) async with sender: # Send one message await send_single_message(sender) # Send a list of messages await send_a_list_of_messages(sender) # Send a batch of messages await send_batch_message(sender) # Close credential when no longer needed. await credential.close() asyncio.run(run()) print("Done sending messages") print("-----------------------")
Receber mensagens de uma subscrição
O código de exemplo a seguir mostra como receber mensagens de uma assinatura. Este código recebe continuamente novas mensagens até não receber novas mensagens durante 5 (max_wait_time
) segundos.
Abra seu editor favorito, como o Visual Studio Code, crie um recv.py de arquivo e adicione o seguinte código a ele.
Semelhante ao exemplo de envio, adicione
import
instruções, defina constantes que você deve substituir por seus próprios valores e defina uma credencial.import asyncio from azure.servicebus.aio import ServiceBusClient from azure.identity.aio import DefaultAzureCredential FULLY_QUALIFIED_NAMESPACE = "FULLY_QUALIFIED_NAMESPACE" SUBSCRIPTION_NAME = "SUBSCRIPTION_NAME" TOPIC_NAME = "TOPIC_NAME" credential = DefaultAzureCredential()
Crie um cliente do Service Bus e, em seguida, um objeto de recetor de assinatura para receber mensagens.
async def run(): # create a Service Bus client using the credential async with ServiceBusClient( fully_qualified_namespace=FULLY_QUALIFIED_NAMESPACE, credential=credential, logging_enable=True) as servicebus_client: async with servicebus_client: # get the Subscription Receiver object for the subscription receiver = servicebus_client.get_subscription_receiver(topic_name=TOPIC_NAME, subscription_name=SUBSCRIPTION_NAME, max_wait_time=5) async with receiver: received_msgs = await receiver.receive_messages(max_wait_time=5, max_message_count=20) for msg in received_msgs: print("Received: " + str(msg)) # complete the message so that the message is removed from the subscription await receiver.complete_message(msg) # Close credential when no longer needed. await credential.close()
Chame o
run
método.asyncio.run(run())
Executar a aplicação
Abra um prompt de comando que tenha Python em seu caminho e, em seguida, execute o código para enviar e receber mensagens para uma assinatura em um tópico.
python send.py; python recv.py
Deverá ver o seguinte resultado:
Sent a single message
Sent a list of 5 messages
Sent a batch of 10 messages
Done sending messages
-----------------------
Received: Single Message
Received: Message in list
Received: Message in list
Received: Message in list
Received: Message in list
Received: Message in list
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
No portal do Azure, navegue até o namespace do Service Bus. Na página Visão geral, verifique se as contagens de mensagens de entrada e saída são 16. Se não vir as contagens, atualize a página depois de aguardar alguns minutos.
Selecione o tópico no painel inferior para ver a página Tópico do Service Bus para o seu tópico. Nesta página, você verá três mensagens de entrada e três de saída no gráfico Mensagens .
Nesta página, se selecionar uma subscrição, acede à página Subscrição do Service Bus. Você pode ver a contagem de mensagens ativas, a contagem de mensagens mortas e muito mais nesta página. Neste exemplo, todas as mensagens foram recebidas, portanto, a contagem de mensagens ativas é zero.
Se você comentar o código de recebimento, verá a mensagem ativa contar como 16.
Próximos passos
Consulte a seguinte documentação e exemplos:
- Biblioteca de cliente do Azure Service Bus para Python
- Exemplos.
- A pasta sync_samples tem exemplos que mostram como interagir com o Service Bus de maneira síncrona. Neste início rápido, você usou esse método.
- A pasta async_samples tem exemplos que mostram como interagir com o Service Bus de forma assíncrona.
- Documentação de referência do Azure-ServiceBus