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

  • Статья

Из этого краткого руководства вы узнаете, как отправлять события в концентратор событий, а затем получать эти события из концентратора событий с помощью библиотеки .NET Azure.Messaging.EventHubs .

Примечание.

Краткие руководства предназначены для быстрого увеличения работы службы. Если вы уже знакомы со службой, вы можете просмотреть примеры .NET для центров событий в нашем репозитории пакета SDK для .NET на GitHub: примеры центров событий на GitHub, примеры обработчика событий на GitHub.

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

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

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

  • Подписка Microsoft Azure. Чтобы использовать службы Azure, в том числе Центры событий Azure, потребуется действующая подписка. Если у вас еще нет учетной записи Azure, зарегистрируйтесь для работы с бесплатной пробной версией или активируйте преимущества для подписчиков MSDN при создании учетной записи.
  • Microsoft Visual Studio 2022. Клиентская библиотека для Центров событий Azure использует новые возможности, реализованные в C# версии 8.0. Вы по-прежнему можете использовать библиотеку с предыдущими версиями языка C#, но новый синтаксис недоступен. Чтобы использовать полный синтаксис, рекомендуется выполнять компиляцию с помощью пакета SDK для .NET Core 3.0 или более поздней версии, а для языковой версии должно быть установлено значение latest. Если вы используете Visual Studio, версии до Visual Studio 2022 несовместимы с инструментами, необходимыми для сборки проектов C# 8.0. Visual Studio 2022, включая бесплатный выпуск Community, можно скачать здесь.
  • Создайте пространство имен Центров событий и концентратор событий. Первым шагом является использование портал Azure для создания пространства имен Центров событий и концентратора событий в пространстве имен. Затем получите учетные данные управления, необходимые приложению для взаимодействия с концентратором событий. Сведения о создании пространства имен и концентратора событий см. в кратком руководстве по созданию концентратора событий с помощью портал Azure.

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

В этом кратком руководстве показано два способа подключения к Центры событий Azure:

  • Без пароля (проверка подлинности Microsoft Entra)
  • Connection string

Первый вариант показывает, как использовать субъект безопасности в Azure Active Directory и управление доступом на основе ролей (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 потребуется несколько минут. В редких случаях может потребоваться до восьми минут. Если при первом запуске кода возникают ошибки аутентификации, подождите несколько минут и повторите попытку.

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

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

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

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

    Снимок экрана, на котором продемонстрировано назначение роли.

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

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

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

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

Запуск Visual Studio и вход в Azure

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

  1. Запустите Visual Studio. Если появится окно "Начало работы ", выберите " Продолжить без ссылки на код " в правой области.

  2. Нажмите кнопку Войти в правом верхнем углу Visual Studio.

    Снимок экрана: кнопка для входа в Azure с помощью Visual Studio.

  3. Войдите с помощью учетной записи Microsoft Entra, назначенной ранее роли.

    Снимок экрана, на котором показан выбор учетной записи.

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

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

Создание консольного приложение

  1. Если у вас уже открыт Visual Studio 2022, выберите "Файл " в меню, выберите "Создать" и выберите "Проект". В противном случае запустите Visual Studio 2022 и выберите "Создать проект ", если появится всплывающее окно.

  2. В диалоговом окне Создать проект выполните следующие действия: (если это диалоговое окно не отображается, щелкните в меню пункт Файл, затем последовательно выберите Создать и Проект).

    1. Выберите язык программирования C#.

    2. Для типа приложения выберите значение Консоль.

    3. В списке результатов выберите Консольное приложение.

    4. Затем выберите Далее.

      Изображение диалогового окна

  3. Введите EventHubsSender для имени проекта, EventHubsQuickStart для имени решения и нажмите кнопку "Далее".

    Изображение страницы, где вводятся имена решений и проектов

  4. На странице Дополнительные сведения выберите Создать.

Добавление пакетов NuGet в проект

  1. Выберите в меню элементы Инструменты>Диспетчер пакетов NuGet>Консоль диспетчера пакетов.

  2. Выполните следующие команды, чтобы установить пакеты Azure.Messaging.EventHubs и Azure.Identity NuGet. Нажмите клавишу ВВОД , чтобы выполнить вторую команду.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Identity

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

  1. Замените существующий Program.cs код в файле следующим примером кода. Затем замените и <HUB_NAME> заполнители <EVENT_HUB_NAMESPACE> для EventHubProducerClient параметров именами пространства имен Центров событий и концентратора событий. Например, "spehubns0309.servicebus.windows.net" и "spehub".

    Вот важные шаги из кода:

    1. Создает объект EventHubProducerClient с помощью пространства имен и имени концентратора событий.
    2. Вызывает метод CreateBatchAsync в объекте EventHubProducerClient для создания объекта EventDataBatch.
    3. Добавление событий в пакет с помощью метода EventDataBatch.TryAdd.
    4. Отправка пакета сообщений в концентратор событий с помощью метода EventHubProducerClient.SendAsync.
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;
using System.Text;

// number of events to be sent to the event hub
int numOfEvents = 3;

// The Event Hubs client types are safe to cache and use as a singleton for the lifetime
// of the application, which is best practice when events are being published or read regularly.
// TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
EventHubProducerClient producerClient = new EventHubProducerClient(
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Create a batch of events 
using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

for (int i = 1; i <= numOfEvents; i++)
{
    if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
    {
        // if it is too large for the batch
        throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
    }
}

try
{
    // Use the producer client to send the batch of events to the event hub
    await producerClient.SendAsync(eventBatch);
    Console.WriteLine($"A batch of {numOfEvents} events has been published.");
    Console.ReadLine();
}
finally
{
    await producerClient.DisposeAsync();
}

  1. Выполните сборку проекта и убедитесь, что она прошла без ошибок.

  2. Выполните программу и дождитесь подтверждающего сообщения.

    A batch of 3 events has been published.

    Внимание

    Если вы используете проверку подлинности без пароля (контроль доступа на основе ролей Azure Active Directory), выберите "Сервис", а затем выберите "Параметры". В окне "Параметры" разверните узел "Проверка подлинности службы Azure" и выберите пункт "Выбор учетной записи". Убедитесь, что вы используете учетную запись, добавленную в роль владельца данных Центры событий Azure в пространстве имен Центров событий.

  3. На странице пространства имен Центров событий в портал Azure отображаются три входящих сообщения на диаграмме "Сообщения". При необходимости обновите страницу, чтобы обновить диаграмму. На отображение полученных сообщений может уйти несколько секунд.

    Изображение страницы портала Azure, на которой можно проверить, получил ли события центр событий

    Примечание.

    Полный исходный код с более подробными комментариями можно найти в этом файле в GitHub.

Получение событий из концентратора событий

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

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

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

  1. Создайте учетную запись хранения Azure
  2. Создание контейнера больших двоичных объектов
  3. Проверка подлинности в контейнере BLOB-объектов с помощью проверки подлинности Microsoft Entra ID (без пароля) или строка подключения в пространство имен.

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

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

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

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

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

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

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

Внимание

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

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

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

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

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

    Снимок экрана: назначение роли учетной записи хранения.

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

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

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

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

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

  1. В окне обозревателя решений щелкните правой кнопкой мыши решение EventHubQuickStart, выберите элемент Добавить и действие Создать проект.
  2. Выберите Консольное приложение и нажмите Далее.
  3. Введите строку EventHubsReceiver в качестве имени проекта и нажмите кнопку Создать.
  4. В окне Обозреватель решений щелкните правой кнопкой мыши EventHubsReceiver и выберите Назначить запускаемым проектом.

Добавление пакетов NuGet в проект

  1. Выберите в меню элементы Инструменты>Диспетчер пакетов NuGet>Консоль диспетчера пакетов.

  2. В окне Консоль диспетчера пакетов для параметра Проект по умолчанию выберите EventHubsReceiver. В противном случае в раскрывающемся списке выберите EventHubsReceiver.

  3. Выполните следующую команду, чтобы установить Azure.Messaging.EventHubs и пакеты NuGet Azure.Identity . Нажмите клавишу ВВОД , чтобы выполнить последнюю команду.

    Install-Package Azure.Messaging.EventHubs
Install-Package Azure.Messaging.EventHubs.Processor
Install-Package Azure.Identity

Обновление кода

Замените содержимое файла Program.cs кодом, приведенным ниже.

  1. Замените существующий Program.cs код в файле следующим примером кода. Затем замените <STORAGE_ACCOUNT_NAME> значения заполнителей <BLOB_CONTAINER_NAME> для BlobContainerClient URI. Замените <EVENT_HUB_NAMESPACE> значения заполнителей и <HUB_NAME> для этого EventProcessorClient .

    Вот важные шаги из кода:

    1. Создает объект EventProcessorClient с помощью пространства имен Центров событий и имени концентратора событий. Необходимо создать объект BlobContainerClient для контейнера в хранилище Azure, созданном ранее.
    2. Указание обработчиков для событий ProcessEventAsync и ProcessErrorAsync объекта EventProcessorClient.
    3. Запуск обработки событий путем вызова StartProcessingAsync для объекта EventProcessorClient.
    4. Останавливает обработку событий через 30 секунд, вызвав StopProcessingAsync в объекте EventProcessorClient .
    using Azure.Identity;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;
using Azure.Storage.Blobs;
using System.Text;

// Create a blob container client that the event processor will use
// TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTATINAER_NAME> with actual names
BlobContainerClient storageClient = new BlobContainerClient(
    new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
    new DefaultAzureCredential());

// Create an event processor client to process events in the event hub
// TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
var processor = new EventProcessorClient(
    storageClient,
    EventHubConsumerClient.DefaultConsumerGroupName,
    "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
    "<HUB_NAME>",
    new DefaultAzureCredential());

// Register handlers for processing events and handling errors
processor.ProcessEventAsync += ProcessEventHandler;
processor.ProcessErrorAsync += ProcessErrorHandler;

// Start the processing
await processor.StartProcessingAsync();

// Wait for 30 seconds for the events to be processed
await Task.Delay(TimeSpan.FromSeconds(30));

// Stop the processing
await processor.StopProcessingAsync();

Task ProcessEventHandler(ProcessEventArgs eventArgs)
{
    // Write the body of the event to the console window
    Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
    Console.ReadLine();
    return Task.CompletedTask;
}

Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
{
    // Write details about the error to the console window
    Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
    Console.WriteLine(eventArgs.Exception.Message);
    Console.ReadLine();
    return Task.CompletedTask;
}

  1. Выполните сборку проекта и убедитесь, что она прошла без ошибок.

    Примечание.

    Полный исходный код с более подробными комментариями приводится в этом файле в GitHub.

  2. Запустите приложение получателя.

  3. Отобразится сообщение о том, что события успешно получены. Нажмите клавишу ВВОД после того, как появится полученное сообщение о событии.

    Received event: Event 1
Received event: Event 2
Received event: Event 3

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

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

    Изображение страницы портала Azure, на которой можно проверить, отправляет ли события центр события в принимающее приложение

Проверка схемы для приложений пакета SDK для Центров событий

Реестр схем Azure можно использовать для проверки схемы при потоковой передаче данных с помощью приложений пакета SDK для Центров событий. Реестр схем Azure центров событий предоставляет централизованный репозиторий для управления схемами, и вы можете легко подключить новые или существующие приложения с реестром схем.

Дополнительные сведения см. в статье "Проверка схем с помощью пакета SDK центров событий".

Примеры и справочные материалы

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

Полный справочник по библиотеке .NET см. в нашей документации по пакету SDK.

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

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

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

См. следующее руководство.

Руководство. Визуализация аномалий данных в событиях в режиме реального времени, отправленных в Центры событий Azure