Краткое руководство. Отправка событий в центры событий или получение событий с помощью JavaScript

Из этого краткого руководства вы узнаете, как отправлять события и получать события из концентратора событий с помощью пакета npm @azure/event-hubs .

Необходимые компоненты

Если вы впервые используете Центры событий Azure, ознакомьтесь с общими сведениями, прежде чем приступить к работе с этим руководством.

Для работы с данным руководством необходимо следующее:

• Подписка Microsoft Azure. Чтобы использовать службы Azure, в том числе Центры событий Azure, потребуется действующая подписка. Если у вас нет существующей учетной записи Azure, вы можете зарегистрироваться и получить бесплатную пробную версию.
• Node.js LTS. Скачайте последнюю версию долгосрочной поддержки (LTS).
• Visual Studio Code (рекомендовано) или любая другая интегрированная среда разработки (IDE).
• Создайте пространство имен Центров событий и концентратор событий. Первым шагом является использование портала Azure для создания пространства имен типа Центров событий и получение учетных данных управления, необходимых приложению для взаимодействия с концентратором событий. Чтобы создать пространство имен и концентратор событий, выполните инструкции из этой статьи.

Установка пакетов npm для отправки событий

Чтобы установить пакет Node диспетчер пакетов (npm) для Центров событий, откройте командную строку с npm в пути, измените каталог на папку, в которой вы хотите сохранить примеры.

Без пароля (рекомендуется)

Выполните следующие команды.

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

Строка подключения

Выполните следующую команду:

npm install @azure/event-hubs

Проверка подлинности приложения в Azure

В этом кратком руководстве показано два способа подключения к Центры событий Azure: без пароля и строка подключения. Первый вариант показывает, как использовать субъект безопасности в идентификаторе Microsoft Entra ID и управлении доступом на основе ролей (RBAC) для подключения к пространству имен Центров событий. Вам не нужно беспокоиться о наличии жестко закодированных строка подключения в коде или в файле конфигурации или в безопасном хранилище, например Azure Key Vault. Второй вариант показывает, как использовать строка подключения для подключения к пространству имен Центров событий. Если вы не знакомы с Azure, вы можете найти вариант строка подключения проще следовать. Мы рекомендуем использовать параметр без пароля в реальных приложениях и рабочих средах. Дополнительные сведения см. в разделе "Проверка подлинности и авторизация". Дополнительные сведения о проверке подлинности без пароля см. на странице обзора.

Без пароля (рекомендуется)

Назначение ролей пользователю Microsoft Entra

При локальной разработке убедитесь, что учетная запись пользователя, которая подключается к Центры событий Azure имеет правильные разрешения. Для отправки и получения сообщений вам потребуется роль владельца данных Центры событий Azure. Чтобы назначить себе эту роль, вам потребуется роль Администратор istrator пользователя или другую роль, которая включает Microsoft.Authorization/roleAssignments/write действие. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Узнайте больше о доступных область для назначений ролей на странице обзора область.

В следующем примере роль назначается Azure Event Hubs Data Owner учетной записи пользователя, которая предоставляет полный доступ к ресурсам Центры событий Azure. В реальном сценарии следуйте принципу наименьших привилегий , чтобы предоставить пользователям только минимальные разрешения, необходимые для более безопасной рабочей среды.

Встроенные роли Azure для Центров событий Azure

Для Центры событий Azure управление пространствами имен и всеми связанными ресурсами с помощью портал Azure и API управления ресурсами Azure уже защищено с помощью модели Azure RBAC. Azure предоставляет следующие встроенные роли Azure для авторизации доступа к пространству имен Центров событий:

• Центры событий Azure владелец данных: включает доступ к пространству имен Центров событий и его сущностям (очереди, разделы, подписки и фильтры)
• Центры событий Azure отправителя данных: используйте эту роль, чтобы предоставить отправителю доступ к пространству имен Центров событий и его сущностям.
• Центры событий Azure приемник данных. Используйте эту роль, чтобы предоставить получателю доступ к пространству имен Центров событий и его сущностям.

Если вы хотите создать пользовательскую роль, см. раздел "Права", необходимые для операций Центров событий.

Внимание

В большинстве случаев для распространения назначения ролей в Azure потребуется несколько минут. В редких случаях может потребоваться до восьми минут. Если при первом запуске кода возникают ошибки аутентификации, подождите несколько минут и повторите попытку.

Портал Azure

1. В портал Azure найдите пространство имен Центров событий с помощью главной панели поиска или навигации слева.

2. На странице обзора выберите элемент управления доступом (IAM) в меню слева.

3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

4. Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.

   

5. Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите Azure Event Hubs Data Owner и выберите соответствующий результат. Теперь щелкните Далее.

6. В разделе Назначение доступа для выберите Пользователь, группа или субъект-служба и + Выбрать членов.

7. В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш user@domain адрес электронной почты), а затем выберите в нижней части диалогового окна.

8. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Azure CLI

Чтобы назначить роль на уровне ресурса с помощью Azure CLI, сначала необходимо получить идентификатор ресурса с помощью az eventhubs namespace show команды. Вы можете отфильтровать выходные свойства с помощью параметра --query.

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

Скопируйте выходной Id из предыдущей команды. Затем можно назначить роли с помощью команды az role в Azure CLI.

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

PowerShell

Чтобы назначить роль на уровне ресурсов с помощью Azure PowerShell, сначала необходимо получить идентификатор ресурса с помощью Get-AzResource команды.

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

Скопируйте значение Id из выходных данных предыдущей команды. После этого можно назначить роли с помощью команды New-AzRoleAssignment в PowerShell.

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

Строка подключения

Получение строки подключения

Создание нового пространства имен автоматически создает начальную политику подписанного URL-адреса (SAS) с первичными и вторичными ключами и строка подключения, которые предоставляют полный контроль над всеми аспектами пространства имен. Сведения о создании правил с более ограниченными правами для обычных отправителей и получателей см. в разделе "Центры событий" и авторизации .

Клиент может использовать строка подключения для подключения к пространству имен Центров событий. Чтобы скопировать первичную строку подключения для пространства имен, выполните следующие действия:

1. На странице пространства имен концентратора событий выберите политики общего доступа в меню слева.

2. На странице Политики общего доступа щелкните RootManageSharedAccessKey.

3. В окне Политика: RootManageSharedAccessKey нажмите кнопку копирования рядом с полем Первичная строка подключения, чтобы скопировать строку подключения в буфер обмена для последующего использования. Вставьте на время эти значения в Блокноте или любом другом месте.

   

   Эту страницу можно использовать для копирования первичного и вторичного ключей, а также первичной и вторичной строки подключения.

Отправка событий

В этом разделе вы создадите приложение JavaScript, которое отправляет события в концентратор событий.

1. Откройте редактор, например Visual Studio Code.

2. Создайте файл с именем send.js и вставьте в него следующий код.

   Без пароля (рекомендуется)

   В коде используйте реальные значения для замены следующих заполнителей:

   • 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);
   });
   

   Строка подключения

   В коде используйте реальные значения для замены следующих заполнителей:

   • 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. запустите node send.js, чтобы выполнить этот файл. Эта команда отправляет в концентратор событий пакет из трех событий. Если вы используете проверку подлинности контроль доступа на основе ролей Azure Active Directory, вы можете запустить az login и войти в Azure, используя учетную запись, добавленную в роль владельца данных Центры событий Azure.

4. В портал Azure убедитесь, что концентратор событий получил сообщения. Обновите страницу, чтобы обновить диаграмму. Может потребоваться несколько секунд, чтобы показать, что сообщения получены.

   

   Примечание.

   Полный исходный код, включая дополнительные информационные комментарии, можно найти на странице GitHub sendEvents.js.

Получение событий

В этом разделе вы получаете события из концентратора событий с помощью хранилища контрольных точек хранилища BLOB-объектов Azure в приложении JavaScript. Оно регулярно создает контрольные точки метаданных для полученных сообщений в Azure Storage blob. Благодаря такому подходу позже можно легко продолжить получать сообщения с того места, где вы остановились.

Следуйте этим рекомендациям при использовании Хранилище BLOB-объектов Azure в качестве хранилища проверка point:

• Используйте отдельный контейнер для каждой группы потребителей. Вы можете использовать одну и ту же учетную запись хранения, но использовать один контейнер для каждой группы.
• Не используйте контейнер для других компонентов и не используйте учетную запись хранения для других действий.
• служба хранилища учетная запись должна находиться в том же регионе, в который находится развернутое приложение. Если приложение находится в локальной среде, попробуйте выбрать ближайший регион.

На странице учетной записи служба хранилища в портал Azure в разделе службы BLOB-объектов убедитесь, что следующие параметры отключены.

• Иерархическое пространство имен
• Обратимое удаление BLOB-объекта
• Управление версиями

Создание учетной записи хранения Azure и контейнера больших двоичных объектов

Для создания учетной записи хранения Azure и контейнера больших двоичных объектов в ней, выполните действия в следующих ресурсах.

1. Создание учетной записи службы хранилища Azure
2. Создание контейнера
3. Проверка подлинности в контейнере BLOB-объектов

Без пароля (рекомендуется)

Если вы выполняете разработку локально, убедитесь, что учетная запись пользователя, через которую осуществляется доступ к данным BLOB-объектов, имеет правильные разрешения. Вам потребуется служба хранилища участник данных BLOB-объектов для чтения и записи данных BLOB-объектов. Чтобы назначить себе эту роль, вам потребуется назначить роль Администратор istrator для доступа пользователей или другую роль, включающую действие Microsoft.Authorization/roleAssignments/write. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Дополнительные сведения о доступных областях назначения ролей можно узнать на странице обзора области.

В этом сценарии вы назначите разрешения учетной записи пользователя, которая ограничена учетной записью хранения, чтобы обеспечить соблюдение принципа минимальных привилегий. В рамках этой практики пользователям предоставляются только минимальные необходимые разрешения, что позволяет создавать более защищенные рабочие среды.

В следующем примере будет назначена роль участника данных BLOB-объектов служба хранилища учетной записи пользователя, которая предоставляет доступ для чтения и записи к данным BLOB-объектов в вашей учетной записи хранения.

Внимание

В большинстве случаев для распространения назначения ролей в Azure потребуется минута или две, но в редких случаях может потребоваться до восьми минут. Если при первом запуске кода возникают ошибки аутентификации, подождите несколько минут и повторите попытку.

Портал Azure

1. На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.

2. На странице обзора учетной записи хранения выберите Контроль доступа (IAM) в меню слева.

3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

4. Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.

   

5. Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите участника данных BLOB-объектов хранилища и выберите соответствующий результат, а затем нажмите кнопку Далее.

6. В разделе Назначение доступа для выберите Пользователь, группа или субъект-служба и + Выбрать членов.

7. В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш user@domain адрес электронной почты), а затем выберите в нижней части диалогового окна.

8. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Azure CLI

Чтобы назначить роль на уровне ресурса с помощью Azure CLI, сначала необходимо получить идентификатор ресурса с помощью az storage account show команды. Вы можете отфильтровать выходные свойства с помощью параметра --query.

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

Скопируйте выходной Id из предыдущей команды. Затем можно назначить роли с помощью команды az role в Azure CLI.

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

PowerShell

Чтобы назначить роль на уровне ресурсов с помощью Azure PowerShell, сначала необходимо получить идентификатор ресурса с помощью Get-AzResource команды.

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

Скопируйте значение Id из выходных данных предыдущей команды. После этого можно назначить роли с помощью команды New-AzRoleAssignment в PowerShell.

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

Строка подключения

Получите строка подключения в учетную запись хранения.

Обратите внимание на строка подключения и имя контейнера. Они используются в коде для получения событий.

Установка пакетов npm для получения событий

Для принимающей стороны необходимо установить еще два пакета. В этом кратком руководстве вы используете хранилище BLOB-объектов Azure для сохранения проверка точек, чтобы программа не считывала уже прочитанные события. Оно регулярно выполняет фиксацию метаданных для полученных сообщений в большом двоичном объекте. Благодаря такому подходу позже можно легко продолжить получать сообщения с того места, где вы остановились.

Без пароля (рекомендуется)

Выполните следующие команды.

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

Строка подключения

Выполните следующие команды.

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

Написание кода для получения событий

1. Откройте редактор, например Visual Studio Code.

2. Создайте файл с именем receive.js и вставьте в него следующий код.

   Без пароля (рекомендуется)

   В коде используйте реальные значения для замены следующих заполнителей:

   • 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);
   });
   

   Строка подключения

   В коде используйте реальные значения для замены следующих заполнителей:

   • 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. В окне командной строки выполните команду node receive.js, которая запускает этот файл. Сообщения о полученных событиях должны отображаться в окне.

   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'
   

   Примечание.

   Полный исходный код, включая дополнительные информационные комментарии, можно найти на странице GitHub receiveEventsUsingCheckpointStore.

   Программа-получатель получает события от всех секций группы потребителей по умолчанию в концентраторе событий.

Очистка ресурсов

Удалите группу ресурсов с пространством имен Центров событий или удалите только пространство имен, если вы хотите сохранить группу ресурсов.

Связанный контент

Ознакомьтесь с примерами в GitHub:

• Примеры JavaScript
• Примеры TypeScript