biblioteca cliente de Azure Event Grid para Java: versión 4.19.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:

  • Publicación de eventos en el servicio Event Grid mediante event, cloud Event 1.0 o esquemas personalizados
  • Consumo de eventos que se han entregado a los controladores de eventos
  • Generación de tokens de SAS para autenticar los eventos de publicación de clientes en temas de Azure Event Grid

Fuentes | Documentación | de referencia de APIDocumentación | del productoMuestras

Introducción

Requisitos previos

Si usa la CLI de Azure, reemplace <your-resource-group-name> y <your-resource-name> por sus propios nombres únicos y <location> por una ubicación de servicio de Azure válida.

Creación de un tema (CLI de Azure)

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Creación de un dominio (CLI de Azure)

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid</artifactId>
    <version>4.19.0</version>
</dependency>

Autenticar el cliente

Para enviar eventos, necesitamos un punto de conexión para enviar y alguna autenticación para el punto de conexión. La autenticación puede ser una credencial de clave, una firma de acceso compartido o una autenticación de token de Azure Active Directory. El punto de conexión y la clave se pueden obtener a través de Azure Portal o la CLI de Azure.

Punto de conexión

El punto de conexión aparece en el panel del tema o dominio de Azure Portal, o se puede obtener mediante el siguiente comando en la CLI de Azure.

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

Clave de acceso

Las claves se muestran en la pestaña "Claves de acceso" de Azure Portal o se pueden obtener mediante el siguiente comando en la CLI de Azure. Cualquiera de las claves enumeradas funcionará.

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

Autenticación de tokens de Azure Active Directory (AAD)

Azure Event Grid proporciona integración con Azure Active Directory (Azure AD) para la autenticación basada en identidades 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. Para enviar eventos a un tema o dominio con , TokenCredentialla identidad autenticada debe tener asignado el rol "Remitente de datos de EventGrid".

Creación del cliente

Uso del punto de conexión y la clave de acceso para crear el cliente

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:

Cliente de sincronización que funciona para todos los desarrolladores de Java:

// For CloudEvent
EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCloudEventPublisherClient();

// For EventGridEvent
EventGridPublisherClient<EventGridEvent> eventGridEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts EventGridEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildEventGridEventPublisherClient();

// For custom event
EventGridPublisherClient<BinaryData> customEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts custom event schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCustomEventPublisherClient();

o cliente asincrónico si la pila de tecnología tiene programación reactiva, como el reactor del proyecto:

// For CloudEvent
EventGridPublisherAsyncClient<CloudEvent> cloudEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCloudEventPublisherAsyncClient();

// For EventGridEvent
EventGridPublisherAsyncClient<EventGridEvent> eventGridEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts EventGridEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildEventGridEventPublisherAsyncClient();

// For custom event
EventGridPublisherAsyncClient<BinaryData> customEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts custom event schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCustomEventPublisherAsyncClient();
Uso del punto de conexión y el token de SAS para crear el cliente

Si tiene una SAS (firma de acceso compartido) que se puede usar para enviar eventos a un tema o dominio de Event Grid durante un tiempo limitado, puede usarlo para crear el cliente del publicador:

Cliente de sincronización:

EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureSasCredential("<sas token that can access the endpoint>"))
    .buildCloudEventPublisherClient();

Cliente asincrónico:

EventGridPublisherAsyncClient<CloudEvent> cloudEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureSasCredential("<sas token that can access the endpoint>"))
    .buildCloudEventPublisherAsyncClient();
Uso del punto de conexión y la credencial del token de Azure Active Directory (AAD) para crear el cliente

Para usar la credencial del token de AAD, incluya azure-identity el artefacto como una dependencia. Consulte Léame de azure-identity para más información.

Cliente de sincronización:

EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildCloudEventPublisherClient();

Cliente asincrónico:

EventGridPublisherAsyncClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildCloudEventPublisherAsyncClient();

Creación de un token de SAS para que otras personas envíen eventos durante un período de tiempo limitado

Si desea conceder permiso a otras personas para publicar eventos en su tema o dominio de Event Grid durante algún tiempo, puede crear una SAS (firma de acceso compartido) para ellos para que puedan crear un EventGridPublisherClient elemento similar al anterior para usarlo AzureSasCredential para crear el cliente del publicador.

Este es el código de ejemplo para crear una firma de acceso compartido que expire después de 20 minutos:

OffsetDateTime expiration = OffsetDateTime.now().plusMinutes(20);
String sasToken = EventGridPublisherClient
    .generateSas("<your event grid endpoint>", new AzureKeyCredential("<key for the endpoint>"), expiration);

Use BinaryData

Este SDK usa com.azure.util.BinaryData para representar la carga de datos de los eventos. BinaryData admite la serialización y deserialización de objetos a través com.azure.core.util.BinaryData.fromObject(Object object) de métodos y toObject() , que usan un serializador Json de Jackson predeterminado, o fromObject(Object object, ObjectSerializer customSerializer) métodos , toObject(Class<T> clazz, ObjectSerializer serializer) que aceptan el serializador Json personalizado. Consulte la documentación de BinaryData para obtener más información.

Conceptos clave

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

EventGridPublisherClient

EventGridPublisherClient se usa para enviar eventos a un tema de Event Grid o a un dominio de Event Grid. EventGridPublisherAsyncClient es la versión asincrónica de EventGridPublisherClient.

Esquemas de eventos

Event Grid admite varios esquemas para codificar eventos. Cuando se crea un tema o dominio de Event Grid, se especifica el esquema que se usará al publicar eventos. Aunque puede configurar el tema para usar un esquema personalizado , es más común usar el esquema EventGridEvent ya definido o el esquema CloudEvent. CloudEvent 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 servicio Event Grid es compatible con la especificación CloudEvent Independientemente del esquema que el tema o dominio esté configurado para su uso, EventGridPublisherClient se usará para publicar eventos en él. Sin embargo, debe usar el tipo correcto para crear una instancia de él:

Esquema de eventos Creación de instancias genéricas del cliente del publicador
Eventos de Event Grid EventGridPublisherClient<EventGridEvent>
Eventos en la nube EventGridPublisherClient<CloudEvent>
Eventos personalizados EventGridPublisherClient<BinaryData>

Si se usa el tipo incorrecto, se producirá un error BadRequest del servicio y los eventos no se publicarán. Use este comando de la CLI de Azure para consultar qué esquema acepta un tema o dominio de Event Grid:

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

Controladores de eventos y deserialización de eventos.

EventGrid no almacena ningún evento en el tema o dominio de Event Grid. Debe crear suscripciones al tema o dominio de EventGrid. Los eventos enviados al tema o dominio se almacenarán en el punto de conexión de la suscripción, también conocido como "Controlador de eventos".

Puede usar el SDK del controlador de eventos para recibir los eventos en cadena Json y, a continuación, usar o EventGridEvent.fromString()CloudEvent.fromString() deserializar los eventos. La parte de datos de los eventos puede estar en datos binarios, string o JSON.

Ejemplos

Temas sobre envío de eventos a Event Grid

Los eventos se pueden enviar en , EventGridEventCloudEvento en un esquema personalizado, como se detalla en Esquemas de eventos. El tema o dominio debe configurarse para aceptar el esquema que se envía. Para simplificar, el cliente sincrónico se usa para ejemplos, pero el cliente asincrónico tiene los mismos nombres de método.

Nota: Descubra qué esquema (evento en la nube, evento de Event Grid o evento personalizado) el tema de Event Grid acepta antes de empezar a enviar.

Envío EventGridEvent a un tema que acepta el esquema EventGridEvent

// Make sure that the event grid topic or domain you're sending to is able to accept the EventGridEvent schema.
List<EventGridEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new EventGridEvent("exampleSubject", "Com.Example.ExampleEventType", BinaryData.fromObject(user), "0.1"));
eventGridEventClient.sendEvents(events);

Envío CloudEvent a un tema que acepta el esquema de CloudEvent

// Make sure that the event grid topic or domain you're sending to is able to accept the CloudEvent schema.
List<CloudEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new CloudEvent("https://source.example.com", "Com.Example.ExampleEventType",
    BinaryData.fromObject(user), CloudEventDataFormat.JSON, "application/json"));
cloudEventClient.sendEvents(events);

Envío de eventos personalizados a un tema que acepta el esquema de eventos personalizados

// Make sure that the event grid topic or domain you're sending to is able to accept the custom event schema.
List<BinaryData> events = new ArrayList<>();
events.add(BinaryData.fromObject(new HashMap<String, String>() {
    {
        put("id", UUID.randomUUID().toString());
        put("time", OffsetDateTime.now().toString());
        put("subject", "Test");
        put("foo", "bar");
        put("type", "Microsoft.MockPublisher.TestEvent");
        put("data", "example data");
        put("dataVersion", "0.1");
    }
}));
customEventClient.sendEvents(events);

Envío de eventos a un dominio de Event Grid

Un dominio de Event Grid puede tener miles de temas, pero tiene un único punto de conexión. Puede usar un dominio para administrar un conjunto de temas relacionados. El envío de eventos a los temas de un dominio de Event Grid es el mismo que el envío de eventos a un tema de Event Grid normal, excepto que debe especificar el topic de si EventGridEvent el dominio acepta EventGridEvent el esquema.

List<EventGridEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new EventGridEvent("com/example", "Com.Example.ExampleEventType", BinaryData.fromObject(user), "1")
    .setTopic("yourtopic"));
eventGridEventClient.sendEvents(events);

Si el dominio acepta CloudEvent el esquema, se debe establecer el atributo de CloudEvent que está configurado para asignar cuando topic se crea el dominio. El atributo de asignación predeterminado es source.

Recepción y consumo de eventos

El servicio Event Grid no almacena eventos. Por lo tanto, este SDK de Event Grid no tiene un receptor de eventos. En su lugar, los eventos se almacenan en los controladores de eventos, incluidos ServiceBus, EventHubs, Cola de storage, punto de conexión de WebHook o muchos otros servicios de Azure compatibles. Sin embargo, actualmente todos los eventos se enviarán y almacenarán como datos JSON codificados. Este es un código básico que detalla la deserialización de eventos una vez recibidos por los controladores de eventos. De nuevo, el control es diferente en función del esquema de eventos que se recibe del tema o la suscripción.

Deserializar EventGridEvent o CloudEvent desde una cadena JSON

La cadena Json puede tener un único evento o una matriz de eventos. El resultado devuelto es una lista de eventos.

// Deserialize an EventGridEvent
String eventGridEventJsonData = "<your EventGridEvent json String>";
List<EventGridEvent> eventGridEvents = EventGridEvent.fromString(eventGridEventJsonData);

// Deserialize a CloudEvent
String cloudEventJsonData = "<your CloudEvent json String>";
List<CloudEvent> cloudEvents = CloudEvent.fromString(cloudEventJsonData);

Deserializar datos de o CloudEventEventGridEvent

Una vez deserializar o EventGridEventCloudEvent desde una cadena Json, puede usar getData() o CloudEventEventGridEvent para obtener la carga del evento. Devuelve un BinaryData objeto , que tiene métodos para deserializar aún más los datos en tipos utilizables:

  • BinaryData.toBytes() obtiene los datos como un byte[]
  • BinaryData.toString() obtiene los datos como una cadena.
  • BinaryData.toObject() obtiene los datos como un objeto de un tipo específico. Usa el deserializador Json de forma predeterminada. Tiene una sobrecarga para aceptar el deserializador si desea usar su propio.
BinaryData eventData = eventGridEvent.getData();

//Deserialize data to a model class
User dataInModelClass = eventData.toObject(User.class);

//Deserialize data to a Map
Map<String, Object> dataMap = eventData.toObject(new TypeReference<Map<String, Object>>() {
});

//Deserialize Json String to a String
String dataString = eventData.toObject(String.class);

//Deserialize String data to a String
String dataInJsonString = eventData.toString();

//Deserialize data to byte array (byte[])
byte[] dataInBytes = eventData.toBytes();

Deserializar datos de eventos del sistema de CloudEvent o EventGridEvent

Un evento que se envía a un tema del sistema se denomina evento de tema del sistema o evento del sistema. Un tema del sistema de Event Grid representa eventos publicados por un origen de eventos como Azure Storage, Azure Event Hubs, App Configuration, etc. Un ejemplo es cuando se crea un blob, se envía un evento del sistema con el tipo de evento "Microsoft.Storage.BlobCreated" al tema del sistema configurado. La clase de eventos del sistema para este tipo de evento se StorageBlobCreatedEventData define en el paquete com.azure.messaging.eventgrid.systemevents. EventGrid tiene eventos del sistema para:

No se puede enviar un evento del sistema a un tema del sistema mediante este SDK.

Recibir y consumir eventos del sistema es el mismo que otros eventos. Además, un conjunto de clases de modelo para los distintos datos de eventos del sistema se definen en el paquete com.azure.messaging.eventgrid.systemevents. Puede hacer lo siguiente después de deserializar un evento mediante EventGridEvent.fromString() o CloudEvent.fromString():

  • busque la clase del modelo de datos de eventos del sistema en la que se pueden deserializar los datos del evento del sistema;
// Look up the System Event data class
Class<?> eventDataClazz = SystemEventNames.getSystemEventMappings().get(event.getEventType());
  • deserializar los datos de un evento del sistema en una instancia de clase de modelo, como deserializar cualquier otro dato de evento;
// Deserialize the event data to an instance of a specific System Event data class type
BinaryData data = event.getData();
if (data != null) {
    StorageBlobCreatedEventData blobCreatedData = data.toObject(StorageBlobCreatedEventData.class);
    System.out.println(blobCreatedData.getUrl());
}
  • tratar con varios tipos de eventos.
List<EventGridEvent> eventGridEvents = EventGridEvent.fromString("<Your EventGridEvent Json String>");
for (EventGridEvent eventGridEvent : eventGridEvents) {
    BinaryData binaryData = eventGridEvent.getData();
    switch (eventGridEvent.getEventType()) {
        case SystemEventNames.APP_CONFIGURATION_KEY_VALUE_DELETED:
            AppConfigurationKeyValueDeletedEventData keyValueDeletedEventData =
                binaryData.toObject(TypeReference.createInstance(AppConfigurationKeyValueDeletedEventData.class));
            System.out.println("Processing the AppConfigurationKeyValueDeletedEventData...");
            System.out.printf("The key is: %s%n", keyValueDeletedEventData.getKey());
            break;
        case SystemEventNames.APP_CONFIGURATION_KEY_VALUE_MODIFIED:
            AppConfigurationKeyValueModifiedEventData keyValueModifiedEventData =
                binaryData.toObject(TypeReference.createInstance(AppConfigurationKeyValueModifiedEventData.class));
            System.out.println("Processing the AppConfigurationKeyValueModifiedEventData...");
            System.out.printf("The key is: %s%n", keyValueModifiedEventData.getKey());
            break;
        default:
            System.out.printf("%s isn't an AppConfiguration event data%n", eventGridEvent.getEventType());
            break;
    }
}

Más ejemplos

Puede encontrar código de ejemplo adicional aquí.

Solución de problemas

Respuestas y códigos de error

Las respuestas de servicio se devuelven en forma de códigos de estado Http, incluidos varios códigos de error. Opcionalmente, los códigos pueden devolverse mediante PublisherClient. Los códigos de estado inesperados se inician como HttpResponseException los que encapsulan el código de error.

Puede encontrar la documentación de referencia del servicio Event Grid aquí. Este es un buen punto de partida para problemas relacionados con la configuración de temas o puntos de conexión, así como para problemas relacionados con códigos de error del 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 Java de Azure SDK.

Ayuda y problemas

Puede encontrar documentación de referencia para el SDK aquí. Este es un buen primer paso para comprender el propósito de cada método llamado, así como los posibles motivos de errores o comportamiento inesperado.

Si encuentra algún error con estos SDK, envíe problemas a través de problemas o desproteger StackOverflow para el SDK de Java de Azure.

Pasos siguientes

  • SDK de Java de Azure
  • Si no tiene una suscripción de Microsoft Azure, puede obtener una cuenta de evaluación GRATUITA aquí.
  • Puede encontrar código de ejemplo adicional aquí.
  • Puede encontrar tutoriales adicionales de Event Grid aquí.

Contribuciones

Para más información sobre cómo contribuir a este repositorio, consulte la guía de contribución.

  1. Bifurcación
  2. Creación de la rama de características (git checkout -b my-new-feature)
  3. Confirmar los cambios (git commit -am 'Add some feature')
  4. Inserción en la rama (git push origin my-new-feature)
  5. Creación de una nueva solicitud de incorporación de cambios

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