Guia de início rápido: enviar ou receber eventos de hubs de eventos usando JavaScript

Neste Guia de início rápido, você aprenderá como enviar e receber eventos de um hub de eventos usando o pacote npm @azure/event-hubs .

Se você é novo nos Hubs de Eventos do Azure, consulte Visão geral dos Hubs de Eventos antes de começar.

Pré-requisitos

• Subscrição do Microsoft Azure. Para usar os serviços do Azure, incluindo os Hubs de Eventos do Azure, você precisa de uma assinatura. Se você não tiver uma conta do Azure, inscreva-se para uma avaliação gratuita.
• Node.js LTS. Faça o download da versão mais recente de suporte de longo prazo (LTS).
• Visual Studio Code (recomendado) ou qualquer outro ambiente de desenvolvimento integrado (IDE).
• Crie um namespace de Hubs de Eventos e um hub de eventos. Usar o portal do Azure para criar um namespace do tipo Hubs de Eventos Obtenha as credenciais de gerenciamento de que seu aplicativo precisa para se comunicar com o hub de eventos. Para obter mais informações, consulte Criar um hub de eventos usando o portal do Azure.

Instalar pacotes npm para enviar eventos

Para instalar o pacote npm (Node Package Manager) para Hubs de Eventos, abra uma janela do Prompt de Comando que tenha npm em seu caminho. Altere o diretório para a pasta onde você deseja manter suas amostras.

Sem Palavra-passe (Recomendado)

Execute estes comandos:

npm install @azure/event-hubs
npm install @azure/identity

Cadeia de conexão

Execute este comando:

npm install @azure/event-hubs

Autenticar o aplicativo no Azure

Este guia de início rápido mostra duas maneiras de se conectar aos Hubs de Eventos do Azure:

• Autenticação sem senha. Use sua entidade de segurança no Microsoft Entra ID e no RBAC (controle de acesso baseado em função) para se conectar a um namespace de Hubs de Eventos. Você não precisa se preocupar em ter cadeias de conexão codificadas em seu código, em um arquivo de configuração ou em armazenamento seguro, como o Azure Key Vault.
• Cadeia de conexão. Use uma cadeia de conexão para se conectar a um namespace de Hubs de Eventos. Se você for novo no Azure, talvez ache 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 do Service Bus e Conexões sem senha para serviços do Azure.

Sem Palavra-passe (Recomendado)

Atribuir funções ao usuário do Microsoft Entra

Ao desenvolver localmente, verifique se a conta de usuário que se conecta aos Hubs de Eventos do Azure tem as permissões corretas. Você precisa da função Proprietário de Dados dos Hubs de Eventos do Azure para enviar e receber mensagens. Para atribuir essa função a si mesmo, você precisa da função de Administrador de Acesso de Usuário ou 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. Para obter mais informações, consulte Entender o escopo da página RBAC do Azure .

O exemplo a seguir atribui a Azure Event Hubs Data Owner função à sua conta de usuário, que fornece acesso total aos recursos dos Hubs de Eventos 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 incorporadas do Azure para Hubs de Eventos do Azure

Para Hubs de Eventos 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 para autorizar o acesso a um namespace de Hubs de Eventos:

• Proprietário de Dados dos Hubs de Eventos do Azure: habilita o acesso aos dados ao namespace dos Hubs de Eventos e suas entidades (filas, tópicos, assinaturas e filtros).
• Remetente de Dados dos Hubs de Eventos do Azure: use essa função para dar ao remetente acesso ao namespace dos Hubs de Eventos e suas entidades.
• Recetor de Dados dos Hubs de Eventos do Azure: use essa função para dar ao recetor acesso ao namespace dos Hubs de Eventos e suas entidades.

Se quiser criar uma função personalizada, consulte Direitos necessários para operações de Hubs de Eventos.

Importante

Na maioria dos casos, leva 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.

portal do Azure

1. No portal do Azure, localize seu namespace de Hubs de Eventos 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 Controlo de acesso (IAM), selecione o separador Atribuição de funções.

4. Selecione + Adicionar no menu superior. Em seguida, selecione Adicionar atribuição de função.

   

5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, procure Azure Event Hubs 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. Em seguida, escolha + Selecionar membros.

7. Na caixa de diálogo, procure o seu nome de utilizador do Microsoft Entra (normalmente o seu endereço de e-mail user@domain ). Escolha Selecionar na parte inferior da caixa de diálogo.

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

Azure CLI

Para atribuir uma função no nível de recurso usando a CLI do Azure, primeiro obtenha a ID do recurso usando o az eventhubs namespace show comando. Você pode filtrar as propriedades de saída usando o --query parâmetro.

az eventhubs namespace show -g '<your-event-hub-resource-group>' -n '<your-event-hub-name>' --query id

Copie a saída Id do comando anterior. Em seguida, você pode atribuir funções usando o comando az role .

az role assignment create --assignee "<user@domain>" \
--role "Azure Event Hubs Data Owner" \
--scope "<your-resource-id>"

PowerShell

Para atribuir uma função no nível de recurso usando o Azure PowerShell, primeiro obtenha a ID do recurso usando o Get-AzResource comando.

Get-AzResource -ResourceGroupName "<your-event-hub-resource-group>" -Name "<your-event-hub-name>"

Copie o valor Id da saída do comando anterior. Em seguida, você pode atribuir funções usando o comando New-AzRoleAssignment .

New-AzRoleAssignment -SignInName <user@domain> `
-RoleDefinitionName "Azure Event Hubs Data Owner" `
-Scope <yourResourceId>

Cadeia de conexão

Obter a string de conexã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 que concedem controle total sobre todos os aspetos do namespace. Para obter informações sobre como criar regras com direitos mais restritos para remetentes e recetores regulares, consulte Autenticação e autorização de Hubs de Eventos.

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

1. Na página Namespace do Hub de Eventos, 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.

Enviar eventos

Nesta seção, você cria um aplicativo JavaScript que envia eventos para um hub de eventos.

1. Abra um editor de texto, como o Visual Studio Code.

2. Crie um arquivo chamado send.js. Cole o seguinte código nele:

   Sem Palavra-passe (Recomendado)

   No código, use valores reais para substituir os seguintes espaços reservados:

   • EVENT HUBS NAMESPACE NAME
   • EVENT HUB NAME

   const { EventHubProducerClient } = require("@azure/event-hubs");
   const { DefaultAzureCredential } = require("@azure/identity");
   
   // Event hubs 
   const eventHubsResourceName = "EVENT HUBS NAMESPACE NAME";
   const fullyQualifiedNamespace = `${eventHubsResourceName}.servicebus.windows.net`; 
   const eventHubName = "EVENT HUB NAME";
   
   // Azure Identity - passwordless authentication
   const credential = new DefaultAzureCredential();
   
   async function main() {
   
     // Create a producer client to send messages to the event hub.
     const producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential);
   
     // Prepare a batch of three events.
     const batch = await producer.createBatch();
     batch.tryAdd({ body: "passwordless First event" });
     batch.tryAdd({ body: "passwordless Second event" });
     batch.tryAdd({ body: "passwordless Third event" });    
   
     // Send the batch to the event hub.
     await producer.sendBatch(batch);
   
     // Close the producer client.
     await producer.close();
   
     console.log("A batch of three events have been sent to the event hub");
   }
   
   main().catch((err) => {
     console.log("Error occurred: ", err);
   });
   

   Cadeia de conexão

   No código, use valores reais para substituir os seguintes espaços reservados:

   • EVENT HUB NAME
   • EVENT HUBS NAMESPACE CONNECTION STRING

   const { EventHubProducerClient } = require("@azure/event-hubs");
   
   const connectionString = "EVENT HUBS NAMESPACE CONNECTION STRING";
   const eventHubName = "EVENT HUB NAME";
   
   async function main() {
   
     // Create a producer client to send messages to the event hub.
     const producer = new EventHubProducerClient(connectionString, eventHubName);
   
     // Prepare a batch of three events.
     const batch = await producer.createBatch();
     batch.tryAdd({ body: "First event" });
     batch.tryAdd({ body: "Second event" });
     batch.tryAdd({ body: "Third event" });    
   
     // Send the batch to the event hub.
     await producer.sendBatch(batch);
   
     // Close the producer client.
     await producer.close();
   
     console.log("A batch of three events have been sent to the event hub");
   }
   
   main().catch((err) => {
     console.log("Error occurred: ", err);
   });
   

3. Para executar o aplicativo, use este comando:

   node send.js
   

   O comando envia um lote de três eventos para o hub de eventos.

   Se estiver a utilizar a autenticação sem palavra-passe (Microsoft Entra ID Role-based access control (RBAC)), poderá ter de iniciar sessão no Azure utilizando a conta que adicionou à função de Proprietário de Dados dos Hubs de Eventos do Azure. Use o comando az login.

4. No portal do Azure, verifique se o hub de eventos recebeu as mensagens. Para atualizar o gráfico, atualize a página. Pode levar alguns segundos para mostrar que as mensagens foram recebidas.

   

   Observação

   Para obter mais informações e o código-fonte completo, consulte a página sendEvents.js do GitHub.

Receber eventos

Nesta seção, recebe-se eventos de um hub de eventos utilizando um armazenamento de pontos de verificação em Blob do Azure numa aplicação JavaScript. Ele executa pontos de verificação de metadados em mensagens recebidas em intervalos regulares em um blob de Armazenamento do Azure. Essa abordagem facilita continuar recebendo mensagens mais tarde de onde você parou.

Siga estas recomendações ao usar o Armazenamento de Blobs do Azure como um armazenamento de ponto de verificação:

• Use um contêiner separado para cada grupo de consumidores. Você pode usar a mesma conta de armazenamento, mas usar um contêiner por cada grupo.
• Não use a conta de armazenamento para mais nada.
• Não use o recipiente para mais nada.
• Crie a conta de armazenamento na mesma região do aplicativo implantado. Se a aplicação for local, tente escolher a região mais próxima possível.

Na página Conta de armazenamento no portal do Azure, na seção Serviço de Blob, verifique se as configurações a seguir estão desabilitadas.

• Espaço de nomes hierárquico
• Eliminação de forma recuperável de blobs
• Gestão de Versões

Criar uma conta de armazenamento do Azure e um contêiner de blob

Para criar uma conta de armazenamento do Azure com um contêiner de blob:

1. Criar uma conta de armazenamento do Azure
2. Criar um contêiner de blob na conta de armazenamento
3. Autenticar o acesso ao contêiner de blob

Sem Palavra-passe (Recomendado)

Ao desenvolver localmente, certifique-se de que a conta de usuário que acessa os dados de blob tenha as permissões corretas. Você precisa do Storage Blob Data Contributor para ler e gravar dados de blob. Para atribuir essa função a si mesmo, você precisa receber a função de Administrador de Acesso de Usuário ou outra função que inclua a ação Microsoft.Authorization/roleAssignments/write . 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. Para obter mais informações, consulte Entender o escopo do Azure RBAC.

Nesse cenário, você atribui permissões à sua conta de usuário, com escopo para a conta de armazenamento, para seguir o Princípio do Menor Privilégio. Essa prática oferece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribui a função de Colaborador de Dados de Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob em sua conta de armazenamento.

Importante

Na maioria dos casos, leva 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.

portal do Azure

1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

2. Na página da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

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

4. Selecione + Adicionar no menu superior. Em seguida, selecione Adicionar atribuição de função.

   

5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, procure por Storage Blob Data Contributor. Selecione o resultado correspondente e, 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. Selecione Rever + atribuir novamente para concluir o processo.

Azure CLI

Para atribuir uma função no nível de recurso usando a CLI do Azure, primeiro obtenha a ID do recurso usando o az storage account show comando. Você pode filtrar as propriedades de saída usando o --query parâmetro.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Copie a saída Id do comando anterior. Em seguida, você pode atribuir funções usando o comando az role .

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Para atribuir uma função no nível de recurso usando o Azure PowerShell, primeiro obtenha a ID do recurso usando o Get-AzResource comando.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Copie o valor Id da saída do comando anterior. Em seguida, você pode atribuir funções usando o comando New-AzRoleAssignment .

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Cadeia de conexão

Obtenha a string de ligação para a conta de armazenamento. Consulte Configurar cadeias de conexão do Armazenamento do Azure.

Observe a cadeia de conexão e o nome do contêiner. Você os usa no código para receber eventos.

Instalar os pacotes npm para receber eventos

Para o lado recetor, você precisa instalar mais dois pacotes. Neste início rápido, você usa o armazenamento de Blob do Azure para persistir pontos de verificação para que o programa não leia os eventos que já leu. Ele executa pontos de verificação de metadados em mensagens recebidas em intervalos regulares em um blob. Essa abordagem facilita continuar recebendo mensagens mais tarde de onde você parou.

Sem Palavra-passe (Recomendado)

Execute estes comandos:

npm install @azure/storage-blob
npm install @azure/eventhubs-checkpointstore-blob
npm install @azure/identity

Cadeia de conexão

Execute estes comandos:

npm install @azure/storage-blob
npm install @azure/eventhubs-checkpointstore-blob

Escrever código para receber eventos

1. Abra um editor de texto, como o Visual Studio Code.

2. Crie um arquivo chamado receive.js. Cole o seguinte código nele:

   Sem Palavra-passe (Recomendado)

   No código, use valores reais para substituir os seguintes espaços reservados:

   • EVENT HUBS NAMESPACE NAME
   • EVENT HUB NAME
   • STORAGE ACCOUNT NAME
   • STORAGE CONTAINER NAME

   const { DefaultAzureCredential } = require("@azure/identity");
   const { EventHubConsumerClient, earliestEventPosition  } = require("@azure/event-hubs");
   const { ContainerClient } = require("@azure/storage-blob");    
   const { BlobCheckpointStore } = require("@azure/eventhubs-checkpointstore-blob");
   
   // Event hubs 
   const eventHubsResourceName = "EVENT HUBS NAMESPACE NAME";
   const fullyQualifiedNamespace = `${eventHubsResourceName}.servicebus.windows.net`; 
   const eventHubName = "EVENT HUB NAME";
   const consumerGroup = "$Default"; // name of the default consumer group
   
   // Azure Storage 
   const storageAccountName = "STORAGE ACCOUNT NAME";
   const storageContainerName = "STORAGE CONTAINER NAME";
   const baseUrl = `https://${storageAccountName}.blob.core.windows.net`;
   
   // Azure Identity - passwordless authentication
   const credential = new DefaultAzureCredential();
   
   async function main() {
   
     // Create a blob container client and a blob checkpoint store using the client.
     const containerClient = new ContainerClient(
       `${baseUrl}/${storageContainerName}`,
       credential
     );  
     const checkpointStore = new BlobCheckpointStore(containerClient);
   
     // Create a consumer client for the event hub by specifying the checkpoint store.
     const consumerClient = new EventHubConsumerClient(consumerGroup, fullyQualifiedNamespace, eventHubName, credential, checkpointStore);
   
     // Subscribe to the events, and specify handlers for processing the events and errors.
     const subscription = consumerClient.subscribe({
         processEvents: async (events, context) => {
           if (events.length === 0) {
             console.log(`No events received within wait time. Waiting for next interval`);
             return;
           }
   
           for (const event of events) {
             console.log(`Received event: '${event.body}' from partition: '${context.partitionId}' and consumer group: '${context.consumerGroup}'`);
           }
           // Update the checkpoint.
           await context.updateCheckpoint(events[events.length - 1]);
         },
   
         processError: async (err, context) => {
           console.log(`Error : ${err}`);
         }
       },
       { startPosition: earliestEventPosition }
     );
   
     // After 30 seconds, stop processing.
     await new Promise((resolve) => {
       setTimeout(async () => {
         await subscription.close();
         await consumerClient.close();
         resolve();
       }, 30000);
     });
   }
   
   main().catch((err) => {
     console.log("Error occurred: ", err);
   });
   

   Cadeia de conexão

   No código, use valores reais para substituir os seguintes espaços reservados:

   • EVENT HUBS NAMESPACE CONNECTION STRING
   • EVENT HUB NAME
   • STORAGE CONNECTION STRING
   • STORAGE CONTAINER NAME

   const { EventHubConsumerClient, earliestEventPosition  } = require("@azure/event-hubs");
   const { ContainerClient } = require("@azure/storage-blob");    
   const { BlobCheckpointStore } = require("@azure/eventhubs-checkpointstore-blob");
   
   const connectionString = "EVENT HUBS NAMESPACE CONNECTION STRING";    
   const eventHubName = "EVENT HUB NAME";
   const consumerGroup = "$Default"; // name of the default consumer group
   const storageConnectionString = "STORAGE CONNECTION STRING";
   const containerName = "STORAGE CONTAINER NAME";
   
   async function main() {
     // Create a blob container client and a blob checkpoint store using the client.
     const containerClient = new ContainerClient(storageConnectionString, containerName);
     const checkpointStore = new BlobCheckpointStore(containerClient);
   
     // Create a consumer client for the event hub by specifying the checkpoint store.
     const consumerClient = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName, checkpointStore);
   
     // Subscribe to the events, and specify handlers for processing the events and errors.
     const subscription = consumerClient.subscribe({
         processEvents: async (events, context) => {
           if (events.length === 0) {
             console.log(`No events received within wait time. Waiting for next interval`);
             return;
           }
   
           for (const event of events) {
             console.log(`Received event: '${event.body}' from partition: '${context.partitionId}' and consumer group: '${context.consumerGroup}'`);
           }
           // Update the checkpoint.
           await context.updateCheckpoint(events[events.length - 1]);
         },
   
         processError: async (err, context) => {
           console.log(`Error : ${err}`);
         }
       },
       { startPosition: earliestEventPosition }
     );
   
     // After 30 seconds, stop processing.
     await new Promise((resolve) => {
       setTimeout(async () => {
         await subscription.close();
         await consumerClient.close();
         resolve();
       }, 30000);
     });
   }
   
   main().catch((err) => {
     console.log("Error occurred: ", err);
   });
   

3. Para executar esse código, use o comando node receive.js. A janela exibe mensagens sobre eventos recebidos.

   C:\Self Study\Event Hubs\JavaScript>node receive.js
   Received event: 'First event' from partition: '0' and consumer group: '$Default'
   Received event: 'Second event' from partition: '0' and consumer group: '$Default'
   Received event: 'Third event' from partition: '0' and consumer group: '$Default'
   

   Observação

   Para obter o código-fonte completo, incluindo comentários informativos, consulte receiveEventsUsingCheckpointStore.js.

   O programa recetor recebe eventos de todas as partições do grupo de consumidores padrão no hub de eventos.

Limpeza de recursos

Exclua o grupo de recursos que tem o namespace Hubs de Eventos ou exclua apenas o namespace se quiser manter o grupo de recursos.

Conteúdo relacionado

• Exemplos de JavaScript
• Exemplos de TypeScript