Enviar mensagens para um tópico do Barramento de Serviço do Azure e receber mensagens de assinaturas para o tópico (JavaScript)

• C#
• Java
• JavaScript
• Python

Neste tutorial, vai concluir os seguintes passos:

1. Criar um espaço de nomes do Service Bus com o Portal do Azure.
2. Criar um tópico do Service Bus com o portal do Azure.
3. Criar uma subscrição do Service Bus com o portal do Azure.
4. Escreva um aplicativo JavaScript para usar o pacote @azure/service-bus para:
   • Envie um conjunto de mensagens para o tópico.
   • Receba essas mensagens da assinatura.

Nota

Este 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 JavaScript e TypeScript pré-criados para o Barramento de Serviço do Azure no repositório do SDK do Azure para JavaScript no GitHub.

Pré-requisitos

• Uma subscrição do Azure. Para concluir este tutorial, precisa de uma conta do Azure. Pode ativar os benefícios de subscritor do MSDN ou inscrever-se numa conta gratuita.
• Node.js LTS
• Siga as etapas no Guia de início rápido: use o portal do Azure para criar um tópico do Service Bus e assinaturas para o tópico. Você usará apenas uma assinatura para este início rápido.

Sem senha (recomendado)

Para usar este guia de início rápido com sua própria conta do Azure, você precisa:

• Instale a CLI do Azure, que fornece a autenticação sem senha para sua máquina de desenvolvedor.
• Entre com sua conta do Azure no terminal ou prompt de comando com az login.
• Use a mesma conta ao adicionar a função apropriada ao seu recurso.
• Execute o código no mesmo terminal ou prompt de comando.
• Anote o nome do tópico e a assinatura do namespace do Service Bus. Você precisará disso no código.

Cadeia de Ligação

Anote o seguinte, que você usará no código abaixo:

• Cadeia de conexão de namespace do Service Bus
• Nome do tópico do namespace do Service Bus que você criou
• Assinatura de namespace do Service Bus

Nota

• Este tutorial funciona com exemplos que você pode copiar e executar usando o Nodejs. Para obter instruções sobre como criar um aplicativo Node.js, consulte Criar e implantar um aplicativo Node.js em um site do Azure ou Node.js Serviço de Nuvem usando o Windows PowerShell.

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:

1. Inicie sessão no portal do Azure.

2. Navegue até a página Todos os serviços.

3. 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.

   

4. Na marca Basics da página Criar namespace, siga estas etapas:

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

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

   3. 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.

   4. Em Local, escolha a região na qual seu namespace deve ser hospedado.

   5. 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.

   6. 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.

   7. Selecione Rever + criar na parte inferior da página.

      

   8. Na página Rever + criar, reveja as definições e selecione Criar.

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

   

6. Você vê a home page do namespace do barramento de serviço.

   

Criar um tópico com o portal do Azure

1. Na página Namespace do Service Bus, expanda Entidades no menu de navegação à esquerda e selecione Tópicos no menu à esquerda.

2. Selecione + Tópico na barra de ferramentas.

3. Insira um nome para o tópico. Deixe as outras opções com os valores predefinidos.

4. Selecione Criar.

   

Criar uma subscrição para o tópico

1. Selecione o tópico que você criou na seção anterior.

   

2. Na página Tópico do Service Bus, selecione + Assinatura na barra de ferramentas.

   

3. Na página Criar subscrição, siga estes passos:

   1. Digite S1 para o nome da assinatura.

   2. Digite 3 para Contagem máxima de entregas.

   3. 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.

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 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.

1. 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.

2. Na página de 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, Adicionar atribuição de função no menu suspenso resultante.

   

5. 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.

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

7. 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.

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

Cadeia de Ligação

Obter a cadeia de ligação

A criação de um novo namespace gera automaticamente uma política inicial de Assinatura de Acesso Compartilhado (SAS) com chaves primárias e secundárias e cadeias de conexão primárias e secundárias que concedem controle total sobre todos os aspetos do namespace. Consulte Autenticação e autorização do Service Bus para obter informações sobre como criar regras com direitos mais restritos para remetentes e destinatários regulares.

Um cliente pode usar a cadeia de conexão para se conectar ao namespace do Service Bus. Para copiar a cadeia de conexão primária para seu namespace, execute estas etapas:

1. Na página Namespace do Service Bus, selecione Políticas de acesso compartilhado no menu à esquerda.

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

3. Na janela Policy: RootManageSharedAccessKey, selecione o botão de cópia ao lado de Cadeia de conexão primária, para copiar a cadeia de conexão para a área de transferência para uso posterior. Cole este valor no Bloco de Notas ou noutra localização temporária.

   

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

Utilize o NPM (Node Package Manager, Gestor de Pacotes do Nó) para instalar o pacote

Sem senha

1. Para instalar o(s) pacote(s) npm necessários(s) para o Service Bus, abra um prompt de comando que tenha npm em seu caminho, altere o diretório para a pasta onde você deseja ter seus exemplos e, em seguida, execute este comando.

2. Instale os seguintes pacotes:

   npm install @azure/service-bus @azure/identity
   

Cadeia de ligação

1. Para instalar o(s) pacote(s) npm necessários(s) para o Service Bus, abra um prompt de comando que tenha npm em seu caminho, altere o diretório para a pasta onde você deseja ter seus exemplos e, em seguida, execute este comando.

2. Instale o seguinte pacote:

   npm install @azure/service-bus
   

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.

Sem senha

Você deve ter entrado com as CLI do az login Azure para que sua máquina local forneça a autenticação sem senha exigida neste código.

1. Abra seu editor favorito, como o Visual Studio Code

2. Crie um arquivo chamado sendtotopic.js e cole o código abaixo nele. Este código enviará uma mensagem para o seu tópico.

   Importante

   A credencial sem senha é fornecida com o DefaultAzureCredential.

   const { ServiceBusClient } = require("@azure/service-bus");
   const { DefaultAzureCredential } = require("@azure/identity");
   
   // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
   const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
   
   // Passwordless credential
   const credential = new DefaultAzureCredential();
   
   const topicName = "<TOPIC NAME>";
   
   const messages = [
       { body: "Albert Einstein" },
       { body: "Werner Heisenberg" },
       { body: "Marie Curie" },
       { body: "Steven Hawking" },
       { body: "Isaac Newton" },
       { body: "Niels Bohr" },
       { body: "Michael Faraday" },
       { body: "Galileo Galilei" },
       { body: "Johannes Kepler" },
       { body: "Nikolaus Kopernikus" }
    ];
   
    async function main() {
       // create a Service Bus client using the passwordless authentication to the Service Bus namespace
       const sbClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
   
       // createSender() can also be used to create a sender for a queue.
       const sender = sbClient.createSender(topicName);
   
       try {
           // Tries to send all messages in a single batch.
           // Will fail if the messages cannot fit in a batch.
           // await sender.sendMessages(messages);
   
           // create a batch object
           let batch = await sender.createMessageBatch();
           for (let i = 0; i < messages.length; i++) {
               // for each message in the array
   
               // try to add the message to the batch
               if (!batch.tryAddMessage(messages[i])) {
                   // if it fails to add the message to the current batch
                   // send the current batch as it is full
                   await sender.sendMessages(batch);
   
                   // then, create a new batch
                   batch = await sender.createMessageBatch();
   
                   // now, add the message failed to be added to the previous batch to this batch
                   if (!batch.tryAddMessage(messages[i])) {
                       // if it still can't be added to the batch, the message is probably too big to fit in a batch
                       throw new Error("Message too big to fit in a batch");
                   }
               }
           }
   
           // Send the last created batch of messages to the topic
           await sender.sendMessages(batch);
   
           console.log(`Sent a batch of messages to the topic: ${topicName}`);
   
           // Close the sender
           await sender.close();
       } finally {
           await sbClient.close();
       }
   }
   
   // call the main function
   main().catch((err) => {
       console.log("Error occurred: ", err);
       process.exit(1);
    });
   

3. Substitua <SERVICE BUS NAMESPACE CONNECTION STRING> pela cadeia de conexão ao namespace do Service Bus.

4. Substitua <TOPIC NAME> pelo nome do tópico.

5. Em seguida, execute o comando em um prompt de comando para executar esse arquivo.

   node sendtotopic.js
   

6. Deverá ver o seguinte resultado.

   Sent a batch of messages to the topic: mytopic
   

Cadeia de ligação

1. Abra seu editor favorito, como o Visual Studio Code

2. Crie um arquivo chamado sendtotopic.js e cole o código abaixo nele. Este código enviará uma mensagem para o seu tópico.

   const { ServiceBusClient } = require("@azure/service-bus");
   
   const connectionString = "<SERVICE BUS NAMESPACE CONNECTION STRING>"
   const topicName = "<TOPIC NAME>";
   
   const messages = [
       { body: "Albert Einstein" },
       { body: "Werner Heisenberg" },
       { body: "Marie Curie" },
       { body: "Steven Hawking" },
       { body: "Isaac Newton" },
       { body: "Niels Bohr" },
       { body: "Michael Faraday" },
       { body: "Galileo Galilei" },
       { body: "Johannes Kepler" },
       { body: "Nikolaus Kopernikus" }
    ];
   
    async function main() {
       // create a Service Bus client using the connection string to the Service Bus namespace
       const sbClient = new ServiceBusClient(connectionString);
   
       // createSender() can also be used to create a sender for a queue.
       const sender = sbClient.createSender(topicName);
   
       try {
           // Tries to send all messages in a single batch.
           // Will fail if the messages cannot fit in a batch.
           // await sender.sendMessages(messages);
   
           // create a batch object
           let batch = await sender.createMessageBatch();
           for (let i = 0; i < messages.length; i++) {
               // for each message in the array
   
               // try to add the message to the batch
               if (!batch.tryAddMessage(messages[i])) {
                   // if it fails to add the message to the current batch
                   // send the current batch as it is full
                   await sender.sendMessages(batch);
   
                   // then, create a new batch
                   batch = await sender.createMessageBatch();
   
                   // now, add the message failed to be added to the previous batch to this batch
                   if (!batch.tryAddMessage(messages[i])) {
                       // if it still can't be added to the batch, the message is probably too big to fit in a batch
                       throw new Error("Message too big to fit in a batch");
                   }
               }
           }
   
           // Send the last created batch of messages to the topic
           await sender.sendMessages(batch);
   
           console.log(`Sent a batch of messages to the topic: ${topicName}`);
   
           // Close the sender
           await sender.close();
       } finally {
           await sbClient.close();
       }
   }
   
   // call the main function
   main().catch((err) => {
       console.log("Error occurred: ", err);
       process.exit(1);
    });
   

3. Substitua <SERVICE BUS NAMESPACE CONNECTION STRING> pela cadeia de conexão ao namespace do Service Bus.

4. Substitua <TOPIC NAME> pelo nome do tópico.

5. Em seguida, execute o comando em um prompt de comando para executar esse arquivo.

   node sendtotopic.js
   

6. Deverá ver o seguinte resultado.

   Sent a batch of messages to the topic: mytopic
   

Receber mensagens de uma subscrição

Sem senha

Você deve ter entrado com as CLI do az login Azure para que sua máquina local forneça a autenticação sem senha exigida neste código.

1. Abra seu editor favorito, como o Visual Studio Code

2. Crie um arquivo chamado receivefromsubscription.js e cole o seguinte código nele. Consulte os comentários de código para obter detalhes.

   const { delay, ServiceBusClient, ServiceBusMessage } = require("@azure/service-bus");
   const { DefaultAzureCredential } = require("@azure/identity");
   
   // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
   const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
   
   // Passwordless credential
   const credential = new DefaultAzureCredential();
   
   const topicName = "<TOPIC NAME>";
   const subscriptionName = "<SUBSCRIPTION NAME>";
   
    async function main() {
       // create a Service Bus client using the passwordless authentication to the Service Bus namespace
       const sbClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
   
       // createReceiver() can also be used to create a receiver for a queue.
       const receiver = sbClient.createReceiver(topicName, subscriptionName);
   
       // function to handle messages
       const myMessageHandler = async (messageReceived) => {
           console.log(`Received message: ${messageReceived.body}`);
       };
   
       // function to handle any errors
       const myErrorHandler = async (error) => {
           console.log(error);
       };
   
       // subscribe and specify the message and error handlers
       receiver.subscribe({
           processMessage: myMessageHandler,
           processError: myErrorHandler
       });
   
       // Waiting long enough before closing the sender to send messages
       await delay(5000);
   
       await receiver.close();
       await sbClient.close();
   }
   
   // call the main function
   main().catch((err) => {
       console.log("Error occurred: ", err);
       process.exit(1);
    });
   

3. Substitua <SERVICE BUS NAMESPACE CONNECTION STRING> pela cadeia de conexão para o namespace.

4. Substitua <TOPIC NAME> pelo nome do tópico.

5. Substitua <SUBSCRIPTION NAME> pelo nome da assinatura do tópico.

6. Em seguida, execute o comando em um prompt de comando para executar esse arquivo.

   node receivefromsubscription.js
   

Cadeia de ligação

1. Abra seu editor favorito, como o Visual Studio Code

2. Crie um arquivo chamado receivefromsubscription.js e cole o seguinte código nele. Consulte os comentários de código para obter detalhes.

   const { delay, ServiceBusClient, ServiceBusMessage } = require("@azure/service-bus");
   
   const connectionString = "<SERVICE BUS NAMESPACE CONNECTION STRING>"
   const topicName = "<TOPIC NAME>";
   const subscriptionName = "<SUBSCRIPTION NAME>";
   
    async function main() {
       // create a Service Bus client using the connection string to the Service Bus namespace
       const sbClient = new ServiceBusClient(connectionString);
   
       // createReceiver() can also be used to create a receiver for a queue.
       const receiver = sbClient.createReceiver(topicName, subscriptionName);
   
       // function to handle messages
       const myMessageHandler = async (messageReceived) => {
           console.log(`Received message: ${messageReceived.body}`);
       };
   
       // function to handle any errors
       const myErrorHandler = async (error) => {
           console.log(error);
       };
   
       // subscribe and specify the message and error handlers
       receiver.subscribe({
           processMessage: myMessageHandler,
           processError: myErrorHandler
       });
   
       // Waiting long enough before closing the sender to send messages
       await delay(5000);
   
       await receiver.close();
       await sbClient.close();
   }
   
   // call the main function
   main().catch((err) => {
       console.log("Error occurred: ", err);
       process.exit(1);
    });
   

3. Substitua <SERVICE BUS NAMESPACE CONNECTION STRING> pela cadeia de conexão para o namespace.

4. Substitua <TOPIC NAME> pelo nome do tópico.

5. Substitua <SUBSCRIPTION NAME> pelo nome da assinatura do tópico.

6. Em seguida, execute o comando em um prompt de comando para executar esse arquivo.

   node receivefromsubscription.js
   

Deverá ver o seguinte resultado.

Received message: Albert Einstein
Received message: Werner Heisenberg
Received message: Marie Curie
Received message: Steven Hawking
Received message: Isaac Newton
Received message: Niels Bohr
Received message: Michael Faraday
Received message: Galileo Galilei
Received message: Johannes Kepler
Received message: Nikolaus Kopernikus

No portal do Azure, navegue até o namespace do Service Bus, alterne para Tópicos no painel inferior e selecione seu tópico para ver a página Tópico do Service Bus para seu tópico. Nesta página, você verá 10 mensagens de entrada e 10 de saída no gráfico Mensagens .

Se você executar apenas o aplicativo de envio na próxima vez, na página Tópico do Service Bus, verá 20 mensagens de entrada (10 novas), mas 10 mensagens de saída.

Nesta página, se você selecionar uma assinatura no painel inferior, chegará à página Assinatura do Service Bus. Você pode ver a contagem de mensagens ativas, a contagem de mensagens mortas e muito mais nesta página. Neste exemplo, há 10 mensagens ativas que ainda não foram recebidas por um destinatário.

Resolução de Problemas

Se você receber um erro ao executar a versão sem senha do código JavaScript sobre as declarações necessárias, verifique se você está conectado por meio do comando az login CLI do Azure e se a função apropriada é aplicada à sua conta de usuário do Azure.

Clean up resources (Limpar recursos)

Navegue até o namespace do Service Bus no portal do Azure e selecione Excluir no portal do Azure para excluir o namespace e a fila nele.

Próximos passos

Consulte a seguinte documentação e exemplos:

• Biblioteca de cliente do Azure Service Bus para JavaScript
• Exemplos de JavaScript
• Exemplos de TypeScript
• Documentação de referência da API