клиентская библиотека Сетка событий Azure для .NET версии 4.14.1

Служба "Сетка событий Azure" позволяет легко создавать приложения с архитектурой на основе событий. Служба "Сетка событий" полностью управляет всеми маршрутизацией событий из любого источника в любое назначение для любого приложения. События службы Azure и пользовательские события можно публиковать непосредственно в службе, где их можно фильтровать и отправлять различным получателям, таким как встроенные обработчики или пользовательские веб-перехватчики. Дополнительные сведения о Сетка событий Azure: Что такое Сетка событий?

Используйте клиентную библиотеку для Сетка событий Azure, чтобы:

• Публикация событий в службе "Сетка событий" с помощью событий Сетки событий, облачного события 1.0 или пользовательских схем

• Использование событий, доставленных в обработчики событий

• Создание маркеров SAS для проверки подлинности событий публикации клиента в Сетка событий Azure разделах

  Исходный код | Пакет (NuGet) | Справочная документация по | API Документация по продукту | Образцы | Руководство по миграции

Начало работы

Установка пакета

Установите клиентскую библиотеку из NuGet.

dotnet add package Azure.Messaging.EventGrid

Предварительные требования

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

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

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

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

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Ключ доступа также можно найти на портале или с помощью следующего фрагмента кода Azure CLI:

az eventgrid topic key list --name <your-resource-name> --resource-group <your-resource-group-name> --query "key1"

Проверка подлинности с помощью ключа доступа к разделу

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

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri("<endpoint>"),
    new AzureKeyCredential("<access-key>"));

Проверка подлинности с помощью подписанного URL-адреса

Сетка событий также поддерживает проверку подлинности с помощью подписанного URL-адреса, что позволяет предоставлять доступ к ресурсу, срок действия которого истекает через определенное время, без совместного использования ключа доступа. Как правило, рабочий процесс будет таким, чтобы одно приложение создавало строку SAS и передало строку другому приложению, которое будет использовать строку. Создайте SAS:

var builder = new EventGridSasBuilder(new Uri(topicEndpoint), DateTimeOffset.Now.AddHours(1));
var keyCredential = new AzureKeyCredential(topicAccessKey);
string sasToken = builder.GenerateSas(keyCredential);

Вот как он будет использоваться с точки зрения потребителя:

var sasCredential = new AzureSasCredential(sasToken);
EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    sasCredential);

EventGridPublisherClient также принимает набор параметров настройки с помощью EventGridPublisherClientOptions. Например, можно указать пользовательский сериализатор, который будет использоваться для сериализации данных события в JSON.

Проверка подлинности с помощью Azure Active Directory

Сетка событий Azure обеспечивает интеграцию с Azure Active Directory (Azure AD) для проверки подлинности запросов на основе удостоверений. С помощью Azure AD можно использовать управление доступом на основе ролей (RBAC), чтобы предоставить пользователям, группам или приложениям доступ к ресурсам Сетка событий Azure. Библиотека удостоверений Azure обеспечивает простую поддержку azure Active Directory для проверки подлинности.

Для отправки событий в раздел или домен с помощью Azure Active Directory удостоверению, прошедшему проверку подлинности, должна быть назначена роль "Отправитель данных EventGrid".

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    new DefaultAzureCredential());

Основные понятия

Сведения об общих понятиях Сетки событий см. в статье Основные понятия в Сетка событий Azure.

EventGridPublisherClient

Издатель отправляет события в службу "Сетка событий". Корпорация Майкрософт публикует события для нескольких служб Azure. Вы можете публиковать события из собственного EventGridPublisherClientприложения с помощью .

Схемы событий

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

Схема службы "Сетка событий"

Хотя вы можете настроить раздел для использования пользовательской схемы, чаще всего используется уже определенная схема Сетки событий. Ознакомьтесь со спецификациями и требованиями здесь.

Схема CloudEvents v1.0

Другой вариант — использовать схему CloudEvents версии 1.0. CloudEvents — это проект Cloud Native Computing Foundation, который создает спецификацию для общего описания данных событий. Сводку по службам CloudEvents можно найти здесь.

Независимо от того, какая схема настроена для использования в разделе или домене, EventGridPublisherClient будет использоваться для публикации событий в нем. SendEvents Используйте метод или SendEventsAsync для публикации.

Доставка событий

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

• Анализ событий из JSON в отдельные события. На основе схемы событий (Сетка событий или CloudEvents) теперь можно получить доступ к основным сведениям о событии на конверте (свойства, которые присутствуют для всех событий, например время и тип события).
• Десериализация данных события. При использовании EventGridEvent или CloudEventпользователь может попытаться получить доступ к полезным данным события или данным, десериализуя их до определенного типа. На этом этапе можно указать пользовательский сериализатор, чтобы правильно декодировать данные.

Потокобезопасность

Мы гарантируем, что все методы экземпляра клиента являются потокобезопасны и независимы друг от друга (руководство). Это гарантирует, что рекомендация по повторному использованию экземпляров клиента всегда будет безопасной, даже в разных потоках.

Дополнительные понятия

Параметры | клиента Доступ к ответу | Длительные операции | Обработка сбоев | Диагностики | Насмешливый | Время существования клиента

Примеры

• Публикация событий Сетки событий в разделе Сетки событий
• Публикация CloudEvents в разделе Сетки событий
• Публикация событий Сетки событий в домене Службы "Сетка событий"
• Получение и десериализация событий

Публикация событий Сетки событий в разделе Сетки событий

Публикация событий в Сетке событий выполняется с помощью EventGridPublisherClient. Используйте предоставленный SendEvent/SendEventAsync метод для публикации одного события в разделе.

// Add EventGridEvents to a list to publish to the topic
EventGridEvent egEvent =
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data");

// Send the event
await client.SendEventAsync(egEvent);

Чтобы опубликовать пакет событий, используйте SendEvents/SendEventsAsync метод .

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add EventGridEvents to a list to publish to the topic
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    // EventGridEvent with custom model serialized to JSON
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        new CustomModel() { A = 5, B = true }),

    // EventGridEvent with custom model serialized to JSON using a custom serializer
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true })),
};

// Send the events
await client.SendEventsAsync(eventsList);

Публикация CloudEvents в разделе Сетки событий

Публикация событий в Сетке событий выполняется с помощью EventGridPublisherClient. Используйте указанный метод для публикации SendEvents/SendEventsAsync событий в разделе.

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add CloudEvents to a list to publish to the topic
List<CloudEvent> eventsList = new List<CloudEvent>
{
    // CloudEvent with custom model serialized to JSON
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        new CustomModel() { A = 5, B = true }),

    // CloudEvent with custom model serialized to JSON using a custom serializer
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true }),
        "application/json"),

    // CloudEvents also supports sending binary-valued data
    new CloudEvent(
        "/cloudevents/example/binarydata",
        "Example.EventType",
        new BinaryData(Encoding.UTF8.GetBytes("This is treated as binary data")),
        "application/octet-stream")};

// Send the events
await client.SendEventsAsync(eventsList);

Публикация событий Сетки событий в домене Службы "Сетка событий"

Домен событий — это средство управления для большого количества разделов Сетки событий, связанных с тем же приложением. Его можно считать метаразделом, в котором может содержаться тысячи отдельных разделов. При создании домена событий вам предоставляется конечная точка публикации точно так же, как при создании раздела в Сетке событий.

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

// Add EventGridEvents to a list to publish to the domain
// Don't forget to specify the topic you want the event to be delivered to!
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data")
    {
        Topic = "MyTopic"
    }
};

// Send the events
await client.SendEventsAsync(eventsList);

Для отправки CloudEvents в качестве раздела домена используется источник CloudEvent:

List<CloudEvent> eventsList = new List<CloudEvent>();

for (int i = 0; i < 10; i++)
{
    CloudEvent cloudEvent = new CloudEvent(
        // the source is mapped to the domain topic
        $"Subject-{i}",
        "Microsoft.MockPublisher.TestEvent",
        "hello")
    {
        Id = $"event-{i}",
        Time = DateTimeOffset.Now
    };
    eventsList.Add(cloudEvent);
}

await client.SendEventsAsync(eventsList);

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

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

Примечание. Если для доставки событий схемы Сетки событий используются веб-перехватчики, служба "Сетка событий" должна подтвердить владение конечной точкой веб-перехватчика, прежде чем она начнет доставлять события в эту конечную точку. Во время создания подписки на события Сетка событий отправляет событие проверки подписки в конечную точку, как показано ниже. Дополнительные сведения о завершении подтверждения см. в статье Доставка событий веб-перехватчика. Для схемы CloudEvents служба проверяет подключение с помощью метода параметров HTTP. Дополнительные сведения см. в статье Проверка CloudEvents.

После доставки событий в обработчик событий можно десериализовать полезные данные JSON в список событий.

Использование среды EventGridEvent:

// Parse the JSON payload into a list of events
EventGridEvent[] egEvents = EventGridEvent.ParseMany(BinaryData.FromStream(httpContent));

Использование среды CloudEvent:

var bytes = await httpContent.ReadAsByteArrayAsync();
// Parse the JSON payload into a list of events
CloudEvent[] cloudEvents = CloudEvent.ParseMany(new BinaryData(bytes));

Десериализация данных событий

Здесь можно получить доступ к данным события путем десериализации в определенный тип путем вызова ToObjectFromJson<T>() в свойстве Data . Чтобы выполнить десериализацию до правильного типа, EventType свойство (Type для CloudEvents) помогает различать различные события. Данные пользовательских событий следует десериализовать с помощью универсального метода ToObjectFromJson<T>(). Существует также метод ToObject<T>() расширения, который принимает пользовательский ObjectSerializer для десериализации данных события.

foreach (CloudEvent cloudEvent in cloudEvents)
{
    switch (cloudEvent.Type)
    {
        case "Contoso.Items.ItemReceived":
            // By default, ToObjectFromJson<T> uses System.Text.Json to deserialize the payload
            ContosoItemReceivedEventData itemReceived = cloudEvent.Data.ToObjectFromJson<ContosoItemReceivedEventData>();
            Console.WriteLine(itemReceived.ItemSku);
            break;
        case "MyApp.Models.CustomEventType":
            // One can also specify a custom ObjectSerializer as needed to deserialize the payload correctly
            TestPayload testPayload = cloudEvent.Data.ToObject<TestPayload>(myCustomSerializer);
            Console.WriteLine(testPayload.Name);
            break;
        case SystemEventNames.StorageBlobDeleted:
            // Example for deserializing system events using ToObjectFromJson<T>
            StorageBlobDeletedEventData blobDeleted = cloudEvent.Data.ToObjectFromJson<StorageBlobDeletedEventData>();
            Console.WriteLine(blobDeleted.BlobType);
            break;
    }
}

Использование среды TryGetSystemEventData():

Если ожидается в основном системные события, может быть более понятным включение TryGetSystemEventData() и использование сопоставления шаблонов для работы с отдельными событиями. Если событие не является системным, метод возвращает значение false, а параметр out будет иметь значение NULL.

Кроме того, если вы используете пользовательский тип события со значением EventType, которое позже добавляется службой и пакетом SDK в качестве системного события, возвращаемое значение TryGetSystemEventData изменится с false на true. Это может возникнуть, если вы заранее создаете собственные пользовательские события для событий, которые уже отправлены службой, но еще не добавлены в пакет SDK. В этом случае лучше использовать универсальный ToObjectFromJson<T> метод для Data свойства , чтобы поток кода не изменялся автоматически после обновления (конечно, вам может потребоваться изменить код для использования недавно выпущенной модели системных событий, а не пользовательской модели).

foreach (EventGridEvent egEvent in egEvents)
{
    // If the event is a system event, TryGetSystemEventData will return the deserialized system event
    if (egEvent.TryGetSystemEventData(out object systemEvent))
    {
        switch (systemEvent)
        {
            case SubscriptionValidationEventData subscriptionValidated:
                Console.WriteLine(subscriptionValidated.ValidationCode);
                break;
            case StorageBlobCreatedEventData blobCreated:
                Console.WriteLine(blobCreated.BlobType);
                break;
            // Handle any other system event type
            default:
                Console.WriteLine(egEvent.EventType);
                // we can get the raw Json for the event using Data
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
    else
    {
        switch (egEvent.EventType)
        {
            case "MyApp.Models.CustomEventType":
                TestPayload deserializedEventData = egEvent.Data.ToObjectFromJson<TestPayload>();
                Console.WriteLine(deserializedEventData.Name);
                break;
            // Handle any other custom event type
            default:
                Console.Write(egEvent.EventType);
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
}

Устранение неполадок

Ответы службы

SendEvents() возвращает код HTTP-ответа от службы. Создается RequestFailedException в качестве ответа службы для любых неудачных запросов. Исключение содержит сведения о том, какой код ответа был возвращен службой.

Десериализация данных событий

• Если данные события не являются допустимыми в формате JSON, при вызове JsonExceptionParse или ParseManyбудет возникать исключение .
• Если схема события не соответствует типу, для которой выполняется десериализация (например, вызов CloudEvent.Parse события EventGridSchema), создается исключение ArgumentException .
• Если Parse вызывается для данных, содержащих несколько событий, возникает исключение ArgumentException . ParseMany вместо этого следует использовать здесь.

Настройка ведения журнала консоли

Можно легко включить ведение журнала консоли, если вы хотите получить более подробную информацию о запросах к службе.

Распределенная трассировка

Библиотека Сетки событий поддерживает распределение трассировки из коробки. Если распределенная трассировка включена, то для соблюдения требований спецификаций CloudEvents по распределенной трассировке, библиотека задает traceparent и tracestate в ExtensionAttributes для CloudEvent. Чтобы узнать больше о том, как включить распределенную трассировку в приложении, см. документацию по распределенной трассировке пакета SDK Azure.

Сетка событий в Kubernetes

Эта библиотека была протестирована и проверена в Kubernetes с помощью Azure Arc.

Дальнейшие действия

Дополнительные сведения https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples о частом использовании клиентской библиотеки Сетки событий см. здесь: Примеры сетки событий.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см. на странице https://cla.microsoft.com..

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.