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, você completa as seguintes etapas:

1. Crie um namespace do Barramento de Serviço usando o portal do Azure.
2. Crie um tópico do Barramento de Serviço usando o portal do Azure.
3. Crie uma assinatura do Barramento de Serviço para esse tópico usando o portal do Azure.
4. Grave um aplicativo JavaScript para usar o pacote @azure/service-bus para:
   • Envie um conjunto de mensagens ao tópico.
   • Receba essas mensagens da assinatura.

Observação

Este guia de início rápido apresenta instruções passo a passo para um cenário simples de envio de um lote de mensagens para um tópico de Barramento de Serviço e recebimento dessas mensagens de uma assinatura do tópico. Você pode encontrar exemplos do JavaScript e TypeScript predefinidos para o Barramento de Serviço do Azure no SDK do Azure para repositório do JavaScript no GitHub.

Pré-requisitos

• Uma assinatura do Azure. Para concluir este tutorial, você precisa de uma conta do Azure. Ative seus benefícios de assinante do MSDN ou inscreva-se em uma conta gratuita.
• Node.js LTS
• Siga as etapas no Início Rápido: Usar o portal do Azure para criar um tópico do Barramento de Serviço e assinaturas para o tópico. Você usará apenas uma assinatura neste guia de início rápido.

Sem senha (recomendado)

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

• 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 apropriada ao recurso.
• Execute o código no mesmo terminal ou prompt de comando.
• Anote o nome do tópico e a assinatura do namespace do Barramento de Serviço. Você precisará disso no código.

Cadeia de Conexão

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

• Cadeia de conexão do namespace do Barramento de Serviço
• Nome do tópico do namespace do Barramento de Serviço que você criou
• Assinatura do namespace do Barramento de Serviço

Observação

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

Criar um namespace no Portal do Azure

Para começar a usar as entidades de mensagens do Barramento de Serviço no Azure, primeiro é necessário criar um namespace com um nome exclusivo no Azure. Um namespace fornece um contêiner de escopo para recursos do Barramento de Serviço (filas, tópicos, etc.) dentro de seu aplicativo.

Para criar um namespace:

1. Entre 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 Barramento de Serviço e selecione o botão + no bloco Barramento de Serviço.

   

4. Na marca Informaçõ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 no qual o namespace residirá ou então crie um novo.

   3. Insira um nome para o namespace. O nome do namespace deve estar de acordo com as convenções de nomenclatura abaixo:

      • 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 seis e no máximo 50 caracteres.
      • O campo 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“ nem “-mgmt“.

   4. Em Localização, escolha a região na qual o namespace deve ser hospedado.

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

      Importante

      Se você quiser usar tópicos e assinaturas, escolha Standard ou Premium. Não há suporte para os tópicos/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 recursos é 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 saber mais, confira Sistema 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.

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

   

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

   

Criar um tópico usando o portal do Azure

1. Na página Namespace de Barramento de Serviço, 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 padrão.

4. Selecione Criar.

   

Criar uma assinatura para o tópico

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

   

2. Na página Tópico de Barramento de Serviço, selecione + Assinatura na barra de ferramentas.

   

3. Na página Criar assinatura, siga estas etapas:

   1. Insira S1 em Nome da assinatura.

   2. Insira 3 em 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 o RBAC (controle de acesso baseado em função) para se conectar a um namespace do Barramento de Serviço. Você não precisa se preocupar em ter uma cadeia de conexão embutida no 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 novo no Azure, poderá achar a opção de cadeia de conexão mais fácil de ser seguida. É recomendável usar a opção sem senha em aplicativos do mundo real e ambientes de produção. Para obter mais informações, confira Autenticação e autorização. Você também pode ler mais sobre a 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, a conta de usuário que se conecta ao Barramento de Serviço do Azure deve ter 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 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. 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 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 do Privilégio Mínimo 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 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 RBAC do Azure. O Azure fornece as funções internas do Azure abaixo 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 (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 acesso de envio 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 conceder acesso de recebimento ao namespace do barramento de serviço e suas entidades.

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 de 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 de sua conta de usuário envie mensagens para uma fila ou um tópico e receba mensagens de uma fila ou assinatura de um tópico.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure. Em casos raros, poderá levar 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ê a página Namespace do Barramento de Serviço não estiver 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 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. 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 user@domain) 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

Criar um namespace gera automaticamente uma política inicial de SAS (Assinatura de Acesso Compartilhado) com chaves primárias e secundárias e cadeias de conexão primárias e secundárias que concedem controle total sobre todos os aspectos do namespace. Consulte Autenticação e autorização do Barramento de Serviço 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 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, selecione Políticas de acesso compartilhado no menu à esquerda.

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 NPM (Gerenciador de Pacotes de Nós) para obter o pacote

Sem senha

1. Para instalar o pacote npm obrigatório para o Barramento de Serviço, abra um prompt de comando que tenha npm em seu caminho, altere o diretório para a pasta em que 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 conexão

1. Para instalar o pacote npm obrigatório para o Barramento de Serviço, abra um prompt de comando que tenha npm em seu caminho, altere o diretório para a pasta em que 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 Barramento de Serviço. Confira os comentários sobre código para obter detalhes.

Sem senha

Você deve ter se conectado com a CLI do Azure az login para que seu computador local forneça a autenticação sem senha necessária neste código.

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

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

   Importante

   A credencial sem senha é fornecida com 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 para o namespace do Barramento de Serviço.

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. A saída a seguir será exibida.

   Sent a batch of messages to the topic: mytopic
   

Cadeia de conexão

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

2. Crie um arquivo chamado sendtotopic.js e cole nele o código abaixo. Esse código enviará uma mensagem ao 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 para o namespace do Barramento de Serviço.

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. A saída a seguir será exibida.

   Sent a batch of messages to the topic: mytopic
   

Receber mensagens de uma assinatura

Sem senha

Você deve ter se conectado com a CLI do Azure az login para que seu computador local forneça a autenticação sem senha necessária neste código.

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

2. Crie um arquivo chamado receivefromsubscription.js e cole o código a seguir nele. Confira os comentários sobre 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 para o tópico.

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

   node receivefromsubscription.js
   

Cadeia de conexão

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

2. Crie um arquivo chamado receivefromsubscription.js e cole o código a seguir nele. Confira os comentários sobre 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 para o tópico.

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

   node receivefromsubscription.js
   

A saída a seguir será exibida.

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, acesse o namespace do Barramento de Serviço, alterne para Tópicos na parte inferior e selecione o tópico para ver a página Tópico do Barramento de Serviço do tópico. Nessa página, você verá dez mensagens de entrada e dez mensagens de saída no gráfico Mensagens.

Se você só executar o aplicativo de envio na próxima vez, na página Tópico do Barramento de Serviço, verá 20 mensagens de entrada (dez novas), mas dez mensagens de saída.

Nessa página, se você selecionar uma assinatura no painel inferior, chegará à página Assinatura do Barramento de Serviço. Você poderá ver a contagem de mensagens ativas, a contagem de mensagens mortas, entre outros nessa página. Neste exemplo, há dez mensagens ativas que ainda não foram recebidas por um destinatário.

Soluçã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 pelo comando az login da CLI do Azure e se a função apropriada é aplicada à conta de usuário do Azure.

Limpar os recursos

Navegue até o namespace do Barramento de Serviço no portal do Azure e selecione Excluir no portal do Azure para excluir o namespace e a fila.

Próximas etapas

Confira os seguintes exemplos e a documentação:

• Biblioteca de clientes do Barramento de Serviço do Azure para JavaScript
• Exemplos de JavaScript
• Exemplos de TypeScript
• Documentação de referência da API