Azure.Messaging.EventGrid 4.24.1

.NET 的 Azure Event Grid 客户端库

Azure Event Grid 允许您轻松构建基于事件的架构的应用程序。Event Grid 服务完全管理任何来源、任何目的地、任何应用中的所有事件的路由。可以直接将 Azure 服务事件和自定义事件发布到服务中，然后可以对这些事件进行筛选并发送到各种接收者，例如内置处理程序或自定义 webhook。要了解更多关于 Azure Event Grid 的信息： 什么是 Event Grid？

使用 Azure Event Grid 客户端库进行以下操作：

• 使用 Event Grid Event、Cloud Event 1.0 或自定义模式向 Event Grid 服务发布事件

• 消费已交付到事件处理程序的事件

• 生成 SAS 令牌以对发布到 Azure Event Grid 主题的事件客户端进行身份验证

  源代码 | 包（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>"));

使用共享访问签名进行身份验证

事件网格还支持使用共享访问签名进行身份验证，这允许在不共享访问密钥的情况下提供特定时间过期的资源访问。通常，工作流程是：一个应用程序生成 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 指定一个自定义序列化程序。

使用 Microsoft Entra ID 进行身份验证

Azure 事件网格提供了与 Microsoft Entra ID 的集成，以实现基于身份的请求身份验证。借助 Azure AD，您可以使用基于角色的访问控制（RBAC）向用户、组或应用程序授予对 Azure 事件网格资源的访问权限。Azure Identity 库为身份验证提供了简单的 Microsoft Entra ID 支持。

要使用 Microsoft Entra ID 向主题或域发送事件，已验证的身份应分配有 "EventGrid Data Sender" 角色。

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

核心概念

有关一般事件网格概念的更多信息：Azure 事件网格概念。

EventGridPublisherClient

发布者 向事件网格服务发送事件。Microsoft 为多个 Azure 服务发布事件。您可以使用 EventGridPublisherClient 从自己的应用程序发布事件。

事件架构

事件是描述系统发生的某一事件的全部信息的最小数据量。事件网格支持多种编码事件的模式。当创建自定义主题或域时，您指定用于发布事件的模式。

事件网格模式

虽然您可以配置您的主题以使用自定义模式，但更常见的是使用预定义的事件网格模式。有关规范和要求，请参阅此处。

CloudEvents v1.0 模式

另一种选择是使用 CloudEvents v1.0 模式。CloudEvents 是云原生计算基金会的一个项目，它产生了一种描述事件数据的标准方式。可以在此处找到 CloudEvents 的服务概要。

无论主题或域配置了什么模式，都会使用 EventGridPublisherClient 将事件发布到其中。使用 SendEvents 或 SendEventsAsync 方法进行发布。

事件交付

事件网格向消费者交付的事件是以 JSON 的形式交付的。根据要交付的消费类型，事件网格服务可能会将一个或多个事件作为单个有效载荷的一部分进行交付。根据事件交付的模式（事件网格或 CloudEvents），事件的处理方式会有所不同。但是，一般模式将保持一致。

• 从 JSON 解析事件为单独的事件。根据事件模式（事件网格或 CloudEvents），您现在可以访问关于事件的基本信息（所有事件都存在的属性，如事件时间和类型）。
• 反序列化事件数据。对于 EventGridEvent 或 CloudEvent，用户现在可以尝试通过反序列化到特定类型来访问事件有效负载或数据。您可以在此时提供一个自定义序列化器以正确解码数据。

线程安全

我们保证所有客户端实例方法是线程安全的，且彼此独立（指南）。这确保了重用客户端实例的建议始终是安全的，即使在跨线程的情况下。

其他概念

客户端选项 | 获取响应 | 长期运行的操作 | 处理失败 | 诊断 | Mocking | 客户端生命周期

示例

• 将事件网格事件发布到事件网格主题
• 将 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服务充当事件处理器。

注意：如果使用Webhooks进行事件网格架构的事件交付，Event Grid需要你在该端点开始交付事件之前证明对该Webhook端点的所有权。在创建事件订阅时，Event Grid会将一个订阅验证事件发送到你的端点，如下所示。有关更多信息，请参阅Webhook事件交付。对于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));

反序列化事件数据

从这里，可以通过在Data属性上调用ToObjectFromJson<T>()来将事件数据反序列化到特定类型。为了能够反序列化到正确的类型，需要使用EventType属性（CloudEvents的Type）来区分不同的事件。应使用泛型方法ToObjectFromJson<T>()反序列化自定义事件数据。还有一个接受自定义ObjectSerializer的扩展方法ToObject<T>()，用于反序列化事件数据。

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，并将输出参数设置为null。

作为备注，如果你使用了一个后来由服务SDK添加为系统事件的自定义事件类型，则TryGetSystemEventData的返回值将从不正确（false）变为正确（true）。这可能会发生在你预先创建了自己自定义事件来处理服务正在发送的但尚未添加到SDK的事件时。在这种情况下，最好在Data属性上使用泛型方法ToObjectFromJson<T>，这样在升级后，你的代码流就不会自动更改（当然，你可能仍然希望修改你的代码以消费新发布的服务系统事件模型，而不是您自定义的模型）。

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，则在调用Parse或ParseMany时将抛出JsonException。
• 如果事件架构与正在反序列化的类型不匹配（例如，在EventGridSchema事件上调用CloudEvent.Parse），则抛出ArgumentException。
• 如果对包含多个事件的函数调用Parse，则抛出ArgumentException。应在此处使用ParseMany。

设置控制台日志

您还可以轻松启用控制台日志记录，如果您想深入了解对服务的请求，请访问以下链接：启用控制台日志记录。

分布式跟踪

Event Grid 库支持开箱即用的分布式跟踪。为了遵守 CloudEvents 规范在分布式跟踪方面的指导原则，当启用分布式跟踪时，库将在 CloudEvent 的 ExtensionAttributes 上设置 traceparent 和 tracestate。要了解如何在您的应用程序中启用分布式跟踪，请参阅 Azure SDK 的分布式跟踪文档。

Kubernetes 上的 Event Grid

此库已在 Azure Arc 的支持下经过测试和验证。

下一步

这里提供了更多示例，供您参考 Event Grid 客户端库的常用用法： Event Grid 示例。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一项贡献者许可协议（CLA），声明您有权，并且确实授予了我们使用您贡献的权利。有关详细信息，请访问贡献者许可协议。

当您提交拉取请求时，CLA 机器人将自动确定您是否需要提供 CLA，并相应地标记 PR（例如，标签、注释）。只需按照机器人提供的说明操作。您只需在整个使用我们的 CLA 的所有存储库中做一次。

本项目采用了 Microsoft 开源行为准则。有关更多信息，请参阅行为准则常见问题解答或联系[email protected]咨询任何额外的问题或评论。