biblioteca cliente de Azure Event Grid para .NET: versión 4.20.0

  • Artículo

Azure Event Grid permite crear fácilmente aplicaciones con arquitecturas basadas en eventos. El servicio Event Grid administra completamente todo el enrutamiento de eventos desde cualquier origen, a cualquier destino, para cualquier aplicación. Los eventos de servicio de Azure y los eventos personalizados se pueden publicar directamente en el servicio, donde los eventos se pueden filtrar y enviar a varios destinatarios, como controladores integrados o webhooks personalizados. Para más información sobre Azure Event Grid: ¿Qué es Event Grid?

Use la biblioteca cliente para Azure Event Grid para:

Introducción

Instalar el paquete

Instale la biblioteca cliente desde NuGet:

dotnet add package Azure.Messaging.EventGrid

Requisitos previos

Debe tener una suscripción de Azure y un grupo de recursos de Azure con un tema o dominio personalizados de Event Grid. Siga este tutorial paso a paso para registrar el proveedor de recursos de Event Grid y crear temas de Event Grid mediante el Azure Portal. Hay un tutorial similar con la CLI de Azure.

Autenticar el cliente

Para que la biblioteca cliente interactúe con un tema o dominio, necesitará el endpoint del tema de Event Grid y un credential, que se puede crear mediante la clave de acceso del tema.

Puede encontrar el punto de conexión del tema de Event Grid en Azure Portal o mediante el fragmento de código de la CLI de Azure siguiente.

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

La clave de acceso también se puede encontrar a través del portal o mediante el siguiente fragmento de código de la CLI de Azure:

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

Autenticación mediante la clave de acceso del tema

Una vez que tenga la clave de acceso y el punto de conexión del tema, puede crear el cliente del publicador de la siguiente manera:

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

Autenticación mediante firma de acceso compartido

Event Grid también admite la autenticación con una firma de acceso compartido que permite proporcionar acceso a un recurso que expira en un tiempo determinado sin compartir la clave de acceso. Por lo general, el flujo de trabajo sería que una aplicación generaría la cadena SAS y entregaría la cadena a otra aplicación que consumiría la cadena. Genere la SAS:

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

Aquí se muestra cómo se usaría desde la perspectiva del consumidor:

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

EventGridPublisherClient también acepta un conjunto de opciones de configuración a través EventGridPublisherClientOptionsde . Por ejemplo, puede especificar un serializador personalizado que se usará para serializar los datos del evento en JSON.

Autenticación mediante Azure Active Directory

Azure Event Grid proporciona integración con Azure Active Directory (Azure AD) para la autenticación basada en identidad de las solicitudes. Con Azure AD, puede usar el control de acceso basado en rol (RBAC) para conceder acceso a los recursos de Azure Event Grid a usuarios, grupos o aplicaciones. La biblioteca de identidades de Azure proporciona compatibilidad sencilla con Azure Active Directory para la autenticación.

Para enviar eventos a un tema o dominio mediante Azure Active Directory, la identidad autenticada debe tener asignado el rol "Remitente de datos de EventGrid".

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

Conceptos clave

Para obtener información sobre los conceptos generales de Event Grid: Conceptos de Azure Event Grid.

EventGridPublisherClient

Un publicador envía eventos al servicio Event Grid. Microsoft publica eventos para varios servicios de Azure. Puede publicar eventos desde su propia aplicación mediante EventGridPublisherClient.

Esquemas de eventos

Un evento es la menor cantidad de información que describe completamente algo que ocurrió en el sistema. Event Grid admite varios esquemas para codificar eventos. Cuando se crea un tema o dominio personalizado, se especifica el esquema que se usará al publicar eventos.

Esquema de Event Grid

Aunque puede configurar el tema para usar un esquema personalizado, es más habitual usar el esquema de Event Grid ya definido. Consulte las especificaciones y los requisitos aquí.

Esquema de CloudEvents v1.0

Otra opción es usar el esquema de CloudEvents v1.0. CloudEvents es un proyecto de Cloud Native Computing Foundation que genera una especificación para describir los datos de eventos de una manera común. El resumen del servicio de CloudEvents se puede encontrar aquí.

Independientemente del esquema que el tema o dominio esté configurado para usarse, EventGridPublisherClient se usará para publicar eventos en él. Use el SendEvents método o SendEventsAsync para la publicación.

Entrega de eventos

Los eventos entregados a los consumidores por Event Grid se entregan como JSON. Según el tipo de consumidor al que se entrega, el servicio Event Grid puede entregar uno o varios eventos como parte de una sola carga. El control de eventos será diferente en función del esquema en el que se entregó el evento. Sin embargo, el patrón general seguirá siendo el mismo:

  • Analice los eventos de JSON en eventos individuales. En función del esquema de eventos (Event Grid o CloudEvents), ahora puede acceder a información básica sobre el evento en el sobre (propiedades que están presentes para todos los eventos, como la hora del evento y el tipo).
  • Deserialice los datos del evento. Dado un EventGridEvent objeto o CloudEvent, el usuario puede intentar acceder a la carga del evento, o a los datos, deserializando en un tipo específico. Puede proporcionar un serializador personalizado en este momento para descodificar correctamente los datos.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

Publicación de eventos de Event Grid en un tema de Event Grid

La publicación de eventos en Event Grid se realiza mediante .EventGridPublisherClient Use el método proporcionado SendEvent/SendEventAsync para publicar un único evento en el tema.

// 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);

Para publicar un lote de eventos, use el SendEvents/SendEventsAsync método .

// 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);

Publicación de CloudEvents en un tema de Event Grid

La publicación de eventos en Event Grid se realiza mediante .EventGridPublisherClient Use el método proporcionado SendEvents/SendEventsAsync para publicar eventos en el tema.

// 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);

Publicación de eventos de Event Grid en un dominio de Event Grid

Un dominio de eventos es una herramienta de administración para un gran número de temas de Event Grid relacionados con la misma aplicación. Se puede considerar un metatema que puede contener miles de temas individuales. Cuando se crea un dominio de eventos, se le asigna un punto de conexión de publicación igual que si hubiera creado un tema de Event Grid.

Para publicar eventos en cualquier tema de un dominio de eventos, inserte los eventos en el punto de conexión del dominio de la misma manera que lo haría para un tema personalizado. La única diferencia es que debe especificar el tema en el que quiere que se entregue el evento.

// 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);

Para enviar CloudEvents, el origen de CloudEvent se usa como tema de dominio:

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

Recepción y deserialización de eventos

Hay varios servicios de Azure diferentes que actúan como controladores de eventos.

Nota: si usa Webhooks para la entrega de eventos del esquema de Event Grid, Event Grid requiere que demuestre la propiedad del punto de conexión de Webhook antes de empezar a entregar eventos a ese punto de conexión. En el momento de la creación de la suscripción de eventos, Event Grid envía un evento de validación de suscripción al punto de conexión, como se muestra a continuación. Obtenga más información sobre cómo completar el protocolo de enlace aquí: Entrega de eventos de webhook. Para el esquema de CloudEvents, el servicio valida la conexión mediante el método de opciones HTTP. Más información aquí: Validación de CloudEvents.

Una vez que los eventos se entregan al controlador de eventos, podemos deserializar la carga JSON en una lista de eventos.

Usar EventGridEvent:

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

Usar CloudEvent:

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

Deserialización de datos de eventos

Desde aquí, se puede acceder a los datos del evento mediante la deserialización a un tipo específico mediante una llamada a ToObjectFromJson<T>() en la Data propiedad . Para deserializar al tipo correcto, la EventType propiedad (Type para CloudEvents) ayuda a distinguir entre distintos eventos. Los datos de eventos personalizados se deben deserializar mediante el método ToObjectFromJson<T>()genérico . También hay un método ToObject<T>() de extensión que acepta un personalizado ObjectSerializer para deserializar los datos del evento.

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

Usar TryGetSystemEventData():

Si se espera principalmente eventos del sistema, puede ser más limpio activar TryGetSystemEventData() y usar la coincidencia de patrones para actuar en los eventos individuales. Si un evento no es un evento del sistema, el método devolverá false y el parámetro out será null.

Como advertencia, si usa un tipo de evento personalizado con un valor EventType que posteriormente se agrega como un evento del sistema por el servicio y el SDK, el valor devuelto de TryGetSystemEventData cambiaría de false a true. Esto podría surgir si va a crear de forma preventiva sus propios eventos personalizados para los eventos que el servicio ya está enviando, pero que aún no se han agregado al SDK. En este caso, es mejor usar el método genérico ToObjectFromJson<T> en la Data propiedad para que el flujo de código no cambie automáticamente después de actualizar (por supuesto, es posible que desee modificar el código para consumir el modelo de eventos del sistema recién publicado en lugar del modelo personalizado).

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

Solución de problemas

Respuestas de servicio

SendEvents() devuelve un código de respuesta HTTP del servicio. Se RequestFailedException produce como una respuesta de servicio para las solicitudes incorrectas. La excepción contiene información sobre qué código de respuesta se devolvió del servicio.

Deserializar datos de eventos

  • Si los datos del evento no son JSON válidos, se producirá una JsonException excepción al llamar a Parse o ParseMany.
  • Si el esquema de eventos no se corresponde con el tipo que se deserializa a (por ejemplo, llamando a CloudEvent.Parse en un evento EventGridSchema), se produce una ArgumentException excepción .
  • Si Parse se llama a en los datos que contienen varios eventos, se produce una ArgumentException excepción . ParseMany se debe usar aquí en su lugar.

Configuración del registro de la consola

También puede habilitar el registro de la consola fácilmente si desea profundizar más en las solicitudes que realiza en el servicio.

Seguimiento distribuido

La biblioteca de Event Grid admite la distribución del seguimiento de forma predeterminada. Para adherirse a la guía de la especificación de CloudEvents sobre la distribución del seguimiento, la biblioteca establece traceparent y tracestate en el valor ExtensionAttributes de CloudEvent cuando está habilitado el seguimiento distribuido. Para obtener más información sobre cómo habilitar el seguimiento distribuido en la aplicación, eche un vistazo a la documentación de seguimiento distribuido de Azure SDK.

Event Grid en Kubernetes

Esta biblioteca se ha probado y validado en Kubernetes mediante Azure Arc.

Pasos siguientes

Vea más https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.20.0/sdk/eventgrid/Azure.Messaging.EventGrid/samples aquí para ver los usos comunes de la biblioteca cliente de Event Grid: Ejemplos de Event Grid.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite Contratos de licencia de colaborador.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones