Início rápido: Enviar e receber mensagens em filas do Barramento de Serviço do Azure (Python)

• C#
• Java
• JavaScript
• Python

Este artigo apresenta instruções passo a passo para um cenário simples de enviar mensagens para uma fila Barramento de Serviço e recebê-las. Você pode encontrar exemplos predefinidos de JavaScript e TypeScript para o Barramento de Serviço do Azure no repositório do SDK do Azure para Python no GitHub.

Neste início rápido, você:

• Crie um namespace do Barramento de Serviço usando o portal do Azure.

• Crie uma fila do Barramento de Serviço usando o portal do Azure.

• Escreva código Python para usar o pacote azure-servicebus para:

  • Envie um conjunto de mensagens à fila.
  • Receber essas mensagens da fila.

Se não conhecer muito bem o serviço, confira a Visão geral do Barramento de Serviço antes de começar.

Pré-requisitos

• Uma assinatura do Azure. Para concluir este início rápido, você precisa de uma conta do Azure. Você pode ativar seus créditos mensais do Azure para assinantes do Visual Studio ou inscrever-se para uma conta gratuita.

• Python 3.8 ou posterior.

Sem senha (recomendado)

Para usar este guia de início rápido com sua conta do Azure:

• Instalar a CLI do Azure, que fornece a autenticação sem senha para o computador desenvolvedor.
• Entrar com sua conta do Azure no terminal ou no prompt de comando com az login.
• Usar a mesma conta ao adicionar a função de dados apropriada ao recurso.
• Execute o código no mesmo terminal ou prompt de comando.
• Anote o nome da fila do namespace do Barramento de Serviço. Você precisa disso no código.

Cadeia de Conexão

Observe os seguintes valores, que você usa no código:

• Cadeia de conexão do namespace do Barramento de Serviço
• Fila do namespace do Barramento de Serviço que você criou

Este início rápido funciona com exemplos que você pode copiar e executar usando o Python. Para obter instruções sobre como criar um aplicativo Python, consulte Início Rápido: Implantar um aplicativo Web Python no Serviço de Aplicativo do Azure. Para obter mais informações sobre como instalar pacotes usados neste início rápido, consulte Como instalar pacotes de biblioteca do Azure para Python.

Criar um namespace no Portal do Azure

Para começar a usar as entidades de mensagens do Barramento de Serviço no Azure, crie um namespace com um nome exclusivo no Azure. Um namespace fornece um contêiner de escopo para recursos do Barramento de Serviço, como filas e tópicos, no seu aplicativo.

Para criar um namespace:

1. Entre no portal do Azure.

2. Selecione o menu de submenu no canto superior esquerdo e navegue até a página Todos os serviços.

3. Na barra de navegação à esquerda, selecione Integração.

4. Role para baixo até oBarramento de > e selecione Criar.

   

5. Na guia Noções básicas da página Criar namespace , siga estas etapas:

   1. Em Assinatura, escolha uma assinatura do Azure na qual criar o namespace.

   2. Em Grupo de recursos, escolha um grupo de recursos existente ou crie um.

   3. Insira um nome de namespace que atenda às seguintes convenções de nomenclatura:

      • O nome deve ser exclusivo em todo o Azure. O sistema imediatamente verifica para ver se o nome está disponível.
      • O nome deve ter no mínimo 6 e no máximo 50 caracteres.
      • O nome pode conter apenas letras, números e hifens -.
      • O nome precisa começar com uma letra e terminar com uma letra ou um número.
      • O nome não termina com -sb ou -mgmt.

   4. Para Localização, escolha a região para hospedar seu namespace.

   5. Selecione o Tipo de preço (Básico, Standard ou Premium) do namespace. Para esse início rápido, selecione Padrão.

      Se você selecionar a camada Premium , poderá 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 e assinaturas no tipo de preço Básico.

      Se você selecionou o tipo de preço Premium, especifique o número de unidades do sistema de mensagens. A camada Premium fornece isolamento de recursos no nível de CPU e memória, de modo que cada carga de trabalho seja executada isoladamente. Esse contêiner de recurso é chamado de unidade do sistema de mensagens. Um namespace premium tem pelo menos uma unidade do sistema de mensagens. Você pode selecionar 1, 2, 4, 8 ou 16 unidades do sistema de mensagens para cada namespace Premium do Barramento de Serviço. Para obter mais informações, veja Camada de mensagens premium do Barramento de Serviço.

   6. Selecione Revisar + criar na parte inferior da página.

      

   7. Na páginaRevisar + criar,revise as configurações e selecioneCriar.

6. Depois que a implantação do recurso for bem-sucedida, selecione Ir para o recurso na página de implantação.

   

7. Você verá a home page do namespace do barramento de serviço.

   

Criar uma fila no portal do Azure

1. Na página Namespace do Barramento de Serviço, expanda Entidades no menu de navegação à esquerda e selecione Filas.

2. Na página Filas, na barra de ferramentas, selecione + Fila.

3. Insira um nome para a fila. Deixe os outros valores com seus valores padrões.

4. Selecione Criar.

   

Autenticar o aplicativo no Azure

Este artigo 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 o controle de acesso baseado em função (RBAC) para se conectar a um namespace do Barramento de Serviço. Você não precisa se preocupar em ter uma cadeia de conexão codificada em código em seu código, 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 Barramento de Serviço. Se você for iniciante no Azure, poderá achar a opção de cadeia de conexão mais fácil de seguir. É recomendável usar a opção sem senha em aplicativos do mundo real e ambientes de produção. Para saber mais, veja Autenticação e autorização do Barramento de Serviço. Para ler mais sobre autenticação sem senha, consulte Autenticar aplicativos .NET.

Sem senha (recomendado)

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, você precisa da função Administrador de Acesso do Usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write .

É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Para saber mais sobre os escopos disponíveis para atribuições de função, consulte Noções básicas sobre o escopo do RBAC do Azure.

O exemplo a seguir atribui a função Azure Service Bus Data Owner à sua conta de usuário, que fornece acesso completo aos recursos do Barramento de Serviço do Azure. Em um cenário real, siga o princípio de privilégio mínimo para conceder 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 de todos os recursos relacionados por meio do portal do Azure e da API de gerenciamento de recursos do Azure já está protegido pelo modelo Azure RBAC. O Azure fornece as funções internas do Azure a seguir para autorizar o acesso a um namespace do Barramento de Serviço:

• Proprietário de dados do Barramento de Serviço do Azure: habilita o acesso a dados ao namespace do Barramento de Serviço e as entidades dele, incluindo 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 fornecer o acesso send ao namespace do Barramento de Serviço e às entidades dele.
• Receptor de dados do Barramento de Serviço do Azure: use essa função para fornecer o acesso receive ao namespace do Barramento de Serviço e às entidades dele.

Se você quiser criar uma função personalizada, consulte Direitos exigidos para operações do Barramento de Serviço.

Adicionar usuário do Microsoft Entra à função 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. Essa configuração permite que um aplicativo executado no contexto da sua conta de usuário envie mensagens para uma fila ou um tópico. Ele pode receber mensagens de uma fila ou de uma assinatura de um tópico.

Importante

Na maioria dos casos, leva um ou dois minutos para que a atribuição de função seja propagada no Azure. Em casos raros, pode demorar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

1. Se você não tiver a página namespace do Barramento de Serviço aberta no portal do Azure, localize o namespace do Barramento de Serviço usando a barra de pesquisa principal ou a navegação à esquerda.

2. Na página Visão geral , selecione Controle de acesso (IAM) no menu à esquerda.

3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

4. Selecione + Adicionar no menu superior e, em seguida, Adicione a atribuição de função.

   

5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Neste exemplo, pesquise Azure Service Bus Data Owner e selecione o resultado correspondente. Em seguida, escolha Avançar.

6. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

7. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente, seu endereço de email usuário@domínio) e escolha Selecionar na parte inferior do diálogo.

8. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

Cadeia de Conexão

Obtenha a cadeia de conexão

A criação de um novo namespace gera automaticamente uma política de SAS (Assinatura de Acesso Compartilhado) inicial com chaves primárias e secundárias. Ele cria cadeias de conexão primárias e secundárias que concedem controle total sobre todos os aspectos do namespace. Para obter mais informações sobre como criar regras com direitos mais restritos para usuários frequentes, consulte Autenticação e Autorização do Service Bus.

Um cliente pode usar a cadeia de conexão para se conectar ao namespace do Barramento de Serviço. Para copiar a cadeia de conexão primária para seu namespace, siga estas etapas:

1. Na página Namespace do Barramento de Serviço , no menu à esquerda, expanda Configurações e selecione Políticas de acesso compartilhado.

2. Na página Políticas de acesso compartilhado, selecione RootManageSharedAccessKey.

3. Na janela Política: RootManageSharedAccessKey, selecione o botão Copiar próximo à Cadeia de Conexão Primária para copiar a cadeia de conexão na área de transferência para uso posterior. Cole esse valor no Bloco de notas ou em outro local temporário.

   

   Você pode usar essa página para copiar a chave primária, a chave secundária, a cadeia de conexão primária e a cadeia de conexão secundária.

Usar o pip para instalar pacotes

Sem senha (recomendado)

1. Para instalar os pacotes do Python necessários para este início rápido do Barramento de Serviço, abra uma janela do Prompt de Comando que tem o Python em seu caminho.

2. Altere o diretório para a pasta em que deseja ter os exemplos.

3. Instale os seguintes pacotes:

   pip install azure-servicebus
   pip install azure-identity
   pip install aiohttp
   

Cadeia de conexão

1. Para instalar os pacotes do Python necessários para este início rápido do Barramento de Serviço, abra uma janela do Prompt de Comando que tem o Python em seu caminho.

2. Altere o diretório para a pasta em que deseja ter os exemplos.

3. Instale o seguinte pacote:

   pip install azure-servicebus
   

Enviar mensagens a uma fila

O código de exemplo a seguir mostra como enviar uma mensagem para uma fila. Abra um editor de texto, como o Visual Studio Code, crie um arquivo send.py e adicione o código a seguir a ele.

Sem senha (recomendado)

1. Adicione instruções de importação.

   import asyncio
   from azure.servicebus.aio import ServiceBusClient
   from azure.servicebus import ServiceBusMessage
   from azure.identity.aio import DefaultAzureCredential
   

2. Adicione constantes e defina uma credencial.

   FULLY_QUALIFIED_NAMESPACE = "FULLY_QUALIFIED_NAMESPACE"
   QUEUE_NAME = "QUEUE_NAME"
   
   credential = DefaultAzureCredential()
   

   Importante

   • Substitua FULLY_QUALIFIED_NAMESPACE pelo namespace totalmente qualificado do Barramento de Serviço.
   • Substitua QUEUE_NAME pelo nome da fila.

3. Adicione um método para enviar uma mensagem individual.

   async def send_single_message(sender):
       # Create a Service Bus message and send it to the queue
       message = ServiceBusMessage("Single Message")
       await sender.send_messages(message)
       print("Sent a single message")
   

   O remetente é um objeto que funciona como um cliente para a fila criada. Você o criará mais tarde e enviará como um argumento para essa função.

4. Adicione um método para enviar uma lista de mensagens.

   async def send_a_list_of_messages(sender):
       # Create a list of messages and send it to the queue
       messages = [ServiceBusMessage("Message in list") for _ in range(5)]
       await sender.send_messages(messages)
       print("Sent a list of 5 messages")
   

5. 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 queue
           await sender.send_messages(batch_message)
       print("Sent a batch of 10 messages")
   

6. Crie um cliente do Barramento de Serviço e, depois, um objeto de remetente da fila 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 Queue Sender object to send messages to the queue
           sender = servicebus_client.get_queue_sender(queue_name=QUEUE_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()
   

7. Chame o método run e imprima uma mensagem.

   asyncio.run(run())
   print("Done sending messages")
   print("-----------------------")
   

Cadeia de conexão

1. Adicione instruções de importação.

   import asyncio
   from azure.servicebus.aio import ServiceBusClient
   from azure.servicebus import ServiceBusMessage
   

2. Adicione constantes.

   NAMESPACE_CONNECTION_STR = "NAMESPACE_CONNECTION_STR"
   QUEUE_NAME = "QUEUE_NAME"
   

   Importante

   • Substitua NAMESPACE_CONNECTION_STR pela cadeia de conexão para o namespace do Barramento de Serviço.
   • Substitua QUEUE_NAME pelo nome da fila.

3. Adicione um método para enviar uma mensagem individual.

   async def send_single_message(sender):
       # Create a Service Bus message and send it to the queue
       message = ServiceBusMessage("Single Message")
       await sender.send_messages(message)
       print("Sent a single message")
   

   O remetente é um objeto que funciona como um cliente para a fila criada. Você o criará mais tarde e enviará como um argumento para essa função.

4. Adicione um método para enviar uma lista de mensagens.

   async def send_a_list_of_messages(sender):
       # Create a list of messages and send it to the queue
       messages = [ServiceBusMessage("Message in list") for _ in range(5)]
       await sender.send_messages(messages)
       print("Sent a list of 5 messages")
   

5. 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 queue
           await sender.send_messages(batch_message)
       print("Sent a batch of 10 messages")
   

6. Crie um cliente do Barramento de Serviço e, depois, um objeto de remetente da fila para enviar mensagens.

   async def run():
       # create a Service Bus client using the connection string
       async with ServiceBusClient.from_connection_string(
           conn_str=NAMESPACE_CONNECTION_STR,
           logging_enable=True) as servicebus_client:
           # Get a Queue Sender object to send messages to the queue
           sender = servicebus_client.get_queue_sender(queue_name=QUEUE_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)
   

7. Chame o método run e imprima uma mensagem.

   asyncio.run(run())
   print("Done sending messages")
   print("-----------------------")
   

Receber mensagens de uma fila

O código de exemplo a seguir mostra como receber uma mensagem de uma fila. O código mostrado recebe novas mensagens até que ele não receba nenhuma mensagem nova por cinco (max_wait_time) segundos.

Abra um editor de texto, como o Visual Studio Code, crie um arquivo recv.py e adicione o código a seguir a ele.

Sem senha (recomendado)

1. Semelhante ao exemplo de send.py, adicione instruções em import. Substitua as constantes 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"
   QUEUE_NAME = "QUEUE_NAME"
   
   credential = DefaultAzureCredential()
   

2. Crie um cliente do Barramento de Serviço e, depois, um objeto de remetente da fila para receber mensagens.

   async def run():
       # create a Service Bus client using the connection string
       async with ServiceBusClient(
           fully_qualified_namespace=FULLY_QUALIFIED_NAMESPACE,
           credential=credential,
           logging_enable=True) as servicebus_client:
   
           async with servicebus_client:
               # get the Queue Receiver object for the queue
               receiver = servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME)
               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 queue
                       await receiver.complete_message(msg)
   
           # Close credential when no longer needed.
           await credential.close()
   

3. Chame o método run .

   asyncio.run(run())
   

Cadeia de conexão

1. Semelhante ao exemplo de send.py , adicione import instruções e defina constantes que usam seus próprios valores.

   import asyncio
   from azure.servicebus.aio import ServiceBusClient
   
   NAMESPACE_CONNECTION_STR = "NAMESPACE_CONNECTION_STR"
   QUEUE_NAME = "QUEUE_NAME"
   

2. Crie um cliente do Barramento de Serviço e, depois, um objeto de remetente da fila para receber mensagens.

   async def run():
       # create a Service Bus client using the connection string
       async with ServiceBusClient.from_connection_string(
           conn_str=NAMESPACE_CONNECTION_STR,
           logging_enable=True) as servicebus_client:
   
           async with servicebus_client:
               # get the Queue Receiver object for the queue
               receiver = servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME)
               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 queue
                       await receiver.complete_message(msg)
   

3. Chame o método run .

   asyncio.run(run())
   

Executar o aplicativo

Abra um prompt de comando que tenha o Python no caminho e execute o código para enviar e receber mensagens da fila.

python send.py; python recv.py

Você deve 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, acesse o namespace do Barramento de Serviço. Na página Visão geral, confirme se as contagens de mensagens de entrada e saída são 16. Se você não vir as contagens, aguarde alguns minutos e atualize a página.

Selecione a fila nesta página Visão geral para acessar a página Fila do Barramento de Serviço. Você também poderá ver a contagem de mensagens de entrada e saída nessa página. Você também verá outras informações, como o tamanho atual da fila e a contagem de mensagens ativas.

Conteúdo relacionado

Confira os seguintes exemplos e a documentação:

• Biblioteca de clientes do Barramento de Serviço do Azure para Python

• Amostras

  • A pasta sync_samples traz exemplos que mostram como interagir com o Barramento de Serviço de maneira síncrona.
  • A pasta async_samples traz exemplos que mostram como interagir com o Barramento de Serviço de maneira assíncrona. Neste guia de início rápido, você usou esse método.

• Documentação de referência de azure-servicebus