Partager via

bibliothèque cliente Azure Event Grid pour Java - version 4.19.0

  • Article

Azure Event Grid vous permet de créer facilement des applications avec les architectures basées sur des événements. Le service Event Grid gère entièrement tout le routage des événements de n’importe quelle source, vers n’importe quelle destination, pour n’importe quelle application. Les événements de service Azure et les événements personnalisés peuvent être publiés directement sur le service, où les événements peuvent ensuite être filtrés et envoyés à différents destinataires, tels que des gestionnaires intégrés ou des webhooks personnalisés. Pour en savoir plus sur Azure Event Grid : Qu’est-ce qu’Event Grid ?

Utilisez la bibliothèque cliente pour Azure Event Grid pour :

  • Publier des événements sur le service Event Grid à l’aide de l’événement Event Grid, cloud Event 1.0 ou de schémas personnalisés
  • Consommer des événements qui ont été remis aux gestionnaires d’événements
  • Générer des jetons SAP pour authentifier les événements de publication du client dans Azure Event Grid rubriques

Sources | Documentation de référence sur l’API | Documentation | produitÉchantillons

Prise en main

Prérequis

Si vous utilisez Azure CLI, remplacez <your-resource-group-name> et <your-resource-name> par vos propres noms uniques et <location> par un emplacement de service Azure valide.

Création d’une rubrique (Azure CLI)

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

Création d’un domaine (Azure CLI)

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

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version ga de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL 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>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

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

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Authentifier le client

Pour envoyer des événements, nous avons besoin d’un point de terminaison à envoyer et d’une certaine authentification pour le point de terminaison. L’authentification peut être une clé d’identification, une signature d’accès partagé ou une authentification par jeton Azure Active Directory. Le point de terminaison et la clé peuvent être obtenus via le portail Azure ou Azure CLI.

Point de terminaison

Le point de terminaison est répertorié dans le tableau de bord de la rubrique ou du domaine dans le portail Azure, ou peut être obtenu à l’aide de la commande suivante dans Azure CLI.

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

Clé d’accès

Les clés sont répertoriées sous l’onglet « Clés d’accès » du portail Azure ou peuvent être obtenues à l’aide de la commande suivante dans Azure CLI. Toutes les clés répertoriées fonctionnent.

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

Authentification par jeton Azure Active Directory (AAD)

Azure Event Grid fournit une intégration à Azure Active Directory (Azure AD) pour l’authentification basée sur l’identité des demandes. Avec Azure AD, vous pouvez utiliser le contrôle d’accès en fonction du rôle (RBAC) pour accorder l’accès à vos ressources Azure Event Grid à des utilisateurs, des groupes ou des applications. Pour envoyer des événements à une rubrique ou un domaine avec un TokenCredential, le rôle « Expéditeur de données EventGrid » doit être attribué à l’identité authentifiée.

Création du client

Utilisation du point de terminaison et de la clé d’accès pour créer le client

Une fois que vous avez votre clé d’accès et votre point de terminaison de rubrique, vous pouvez créer le client d’éditeur comme suit :

Synchroniser le client qui fonctionne pour chaque développeur 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();

ou un client asynchrone si votre pile technologique a une programmation réactive, telle que le réacteur de projet :

// 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();
Utilisation du point de terminaison et du jeton SAP pour créer le client

Si vous disposez d’une signature d’accès partagé (SAP) qui peut être utilisée pour envoyer des événements à une rubrique ou à un domaine Event Grid pendant une durée limitée, vous pouvez l’utiliser pour créer le client d’éditeur :

Synchroniser le client :

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

Client asynchrone :

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();
Utilisation du point de terminaison et des informations d’identification de jeton Azure Active Directory (AAD) pour créer le client

Pour utiliser les informations d’identification du jeton AAD, incluez azure-identity l’artefact en tant que dépendance. Pour plus d’informations, reportez-vous à azure-identity README .

Synchroniser le client :

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

Client asynchrone :

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

Créer un jeton SAS pour permettre à d’autres personnes d’envoyer des événements pendant une période limitée

Si vous souhaitez autoriser d’autres personnes à publier des événements dans votre rubrique ou domaine Event Grid pendant un certain temps, vous pouvez créer une signature d’accès partagé (SAS) pour ces personnes afin qu’elles puissent créer un EventGridPublisherClient objet similaire à celui ci-dessus à utiliser AzureSasCredential pour créer le client d’éditeur.

Voici un exemple de code pour créer une signature d’accès partagé qui expire après 20 minutes :

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

Utilisez BinaryData.

Ce Kit de développement logiciel (SDK) utilise com.azure.util.BinaryData pour représenter la charge utile des données des événements. BinaryData prend en charge la sérialisation et la désérialisation des objets via com.azure.core.util.BinaryData.fromObject(Object object) des méthodes et toObject() , qui utilisent un sérialiseur Json Jackson par défaut, ou fromObject(Object object, ObjectSerializer customSerializer) des méthodes et toObject(Class<T> clazz, ObjectSerializer serializer) , qui acceptent votre sérialiseur Json personnalisé. Pour plus d’informations, consultez la documentation BinaryData .

Concepts clés

Pour plus d’informations sur les concepts généraux d’Event Grid : Concepts dans Azure Event Grid.

EventGridPublisherClient

EventGridPublisherClient est utilisé pour envoyer des événements à une rubrique Event Grid ou à un domaine Event Grid. EventGridPublisherAsyncClient est la version asynchrone de EventGridPublisherClient.

Schémas d’événement

Event Grid prend en charge plusieurs schémas pour l’encodage des événements. Lors de la création d’une rubrique ou d’un domaine Event Grid, vous spécifiez le schéma qui sera utilisé lors de la publication d’événements. Vous pouvez configurer votre rubrique pour utiliser un schéma personnalisé , mais il est plus courant d’utiliser le schéma EventGridEvent ou le schéma CloudEvent déjà défini. CloudEvent est un projet Cloud Native Computing Foundation qui produit une spécification pour décrire les données d’événement de manière commune. Le service Event Grid est compatible avec la spécification CloudEvent Quel que soit le schéma que votre rubrique ou domaine est configuré pour utiliser, EventGridPublisherClient sera utilisé pour publier des événements sur celui-ci. Toutefois, vous devez utiliser le type correct pour l’instancier :

Schéma d’événement Instanciation générique du client publisher
Événements Event Grid EventGridPublisherClient<EventGridEvent>
Événements cloud EventGridPublisherClient<CloudEvent>
Événements personnalisés EventGridPublisherClient<BinaryData>

L’utilisation d’un type incorrect entraîne une erreur BadRequest à partir du service et vos événements ne seront pas publiés. Utilisez cette commande Azure CLI pour interroger le schéma accepté par une rubrique ou un domaine Event Grid :

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

Gestionnaires d’événements et désérialisation des événements.

EventGrid ne stocke aucun événement dans la rubrique ou le domaine Event Grid lui-même. Vous devez créer des abonnements à la rubrique ou au domaine EventGrid. Les événements envoyés à la rubrique ou au domaine sont stockés dans le point de terminaison de l’abonnement, également appelé « Gestionnaire d’événements ».

Vous pouvez utiliser le Kit de développement logiciel (SDK) du gestionnaire d’événements pour recevoir les événements dans la chaîne Json, puis utiliser ou EventGridEvent.fromString()CloudEvent.fromString() désérialiser les événements. La partie données des événements peut être en données binaires, string ou JSON.

Exemples

Envoi d’événements aux rubriques Event Grid

Les événements peuvent être envoyés dans , EventGridEventCloudEventou dans un schéma personnalisé, comme indiqué dans Schémas d’événements. La rubrique ou le domaine doit être configuré pour accepter le schéma envoyé. Par souci de simplicité, le client synchrone est utilisé pour les exemples, mais le client asynchrone a les mêmes noms de méthode.

Remarque : déterminez le schéma (événement cloud, événement event grid ou événement personnalisé) que la rubrique Event Grid accepte avant de commencer à envoyer.

Envoi EventGridEvent à une rubrique qui accepte le schéma 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);

Envoi CloudEvent à une rubrique qui accepte le schéma 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);

Envoi d’événements personnalisés à une rubrique qui accepte le schéma d’événement personnalisé

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

Envoi d’événements au domaine Event Grid

Un domaine Event Grid peut comporter des milliers de rubriques, mais n’a qu’un seul point de terminaison. Vous pouvez utiliser un domaine pour gérer un ensemble de rubriques associées. L’envoi d’événements aux rubriques d’un domaine Event Grid est identique à l’envoi d’événements à une rubrique Event Grid standard, sauf que vous devez spécifier le topic d’un EventGridEvent si le domaine accepte EventGridEvent le schéma.

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 le domaine accepte CloudEvent le schéma, l’attribut CloudEvent configuré pour mapper le topic lors de la création du domaine doit être défini. L’attribut de mappage par défaut est source.

Réception et consommation d’événements

Le service Event Grid ne stocke pas d’événements. Par conséquent, ce Kit de développement logiciel (SDK) Event Grid n’a pas de récepteur d’événements. Au lieu de cela, les événements sont stockés dans les gestionnaires d’événements, notamment ServiceBus, EventHubs, File d’attente de stockage, point de terminaison WebHook ou de nombreux autres services Azure pris en charge. Toutefois, actuellement, tous les événements sont envoyés et stockés sous forme de données JSON encodées. Voici un code de base qui détaille la désérialisation des événements une fois qu’ils ont été reçus par les gestionnaires d’événements. Là encore, la gestion est différente en fonction du schéma d’événement reçu de la rubrique/de l’abonnement.

Désérialiser EventGridEvent ou CloudEvent à partir d’une chaîne JSON

La chaîne JSON peut avoir un seul événement ou un tableau d’événements. Le résultat retourné est une liste d’événements.

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

Désérialiser des données à partir d’un CloudEvent ou EventGridEvent

Une fois que vous avez désérialisé ou EventGridEventCloudEvent à partir d’une chaîne JSON, vous pouvez utiliser getData() ou CloudEventEventGridEvent pour obtenir la charge utile de l’événement. Il retourne un BinaryData objet, qui a des méthodes pour désérialiser davantage les données en types utilisables :

  • BinaryData.toBytes() obtient les données sous forme d’octet[]
  • BinaryData.toString() obtient les données sous forme de chaîne
  • BinaryData.toObject() obtient les données en tant qu’objet d’un type spécifique. Il utilise le désérialiseur Json par défaut. Il a une surcharge d’accepter votre désérialiseur si vous souhaitez utiliser le vôtre.
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();

Désérialiser les données d’événement système à partir de CloudEvent ou EventGridEvent

Un événement envoyé à une rubrique système est appelé événement de rubrique système ou événement système. Une rubrique système dans Event Grid représente les événements publiés par une source d’événements comme Stockage Azure, Azure Event Hubs, App Configuration, etc. Par exemple, lorsqu’un objet blob est créé, un événement système avec le type d’événement « Microsoft.Storage.BlobCreated » est envoyé à la rubrique système configurée. La classe d’événements système pour ce type d’événement est StorageBlobCreatedEventData définie dans le package com.azure.messaging.eventgrid.systemevents. EventGrid a des événements système pour :

Vous ne pouvez pas envoyer un événement système à une rubrique système à l’aide de ce kit SDK.

La réception et la consommation d’événements système sont identiques à d’autres événements. En outre, un ensemble de classes de modèle pour les différentes données d’événement système sont définies dans le package com.azure.messaging.eventgrid.systemevents. Vous pouvez effectuer les opérations suivantes après avoir désérialisé un événement à l’aide EventGridEvent.fromString() de ou CloudEvent.fromString():

  • recherchez la classe de modèle de données d’événement système dans laquelle les données d’événement système peuvent être désérialisées ;
// Look up the System Event data class
Class<?> eventDataClazz = SystemEventNames.getSystemEventMappings().get(event.getEventType());
  • désérialiser les données d’un événement système dans une classe de modèle instance comme la désérialisation de toute autre donnée d’événement ;
// 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());
}
  • gérer plusieurs types d’événements.
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;
    }
}

Autres exemples

Vous trouverez des exemples de code supplémentaires ici.

Dépannage

Réponses et codes d’erreur

Les réponses de service sont retournées sous la forme de codes http status, y compris un certain nombre de codes d’erreur. Ces codes peuvent éventuellement être retournés par .PublisherClient Des codes status inattendus sont levées pour HttpResponseException encapsuler le code d’erreur.

La documentation de référence pour le service event grid est disponible ici. Il s’agit d’un bon point de départ pour les problèmes liés à la configuration des rubriques/points de terminaison, ainsi que pour les problèmes impliquant des codes d’erreur du service.

Suivi distribué

La bibliothèque Event Grid prend en charge la distribution du traçage prête à l’emploi. Pour se conformer aux directives de la spécification cloudEvents sur la distribution du suivi, la bibliothèque définit les attributs traceparent et tracestate sur extensionAttributes d’un CloudEvent lorsque le suivi distribué est activé. Pour en savoir plus sur l’activation du suivi distribué dans votre application, consultez la documentation consacrée au suivi distribué Java du kit de développement logiciel (SDK) Azure.

Aide et problèmes

La documentation de référence pour le Kit de développement logiciel (SDK) est disponible ici. Il s’agit d’une bonne première étape pour comprendre l’objectif de chaque méthode appelée, ainsi que les raisons possibles d’erreurs ou de comportement inattendu.

Si vous rencontrez des bogues avec ces SDK, veuillez déposer des problèmes via Problèmes ou vérifier StackOverflow pour le Kit de développement logiciel (SDK) Java Azure.

Étapes suivantes

Contribution

Pour plus d’informations sur la contribution à ce dépôt, consultez le guide de contribution.

  1. Fork it
  2. Créer votre branche de fonctionnalité (git checkout -b my-new-feature)
  3. Valider vos modifications (git commit -am 'Add some feature')
  4. Push vers la branche (git push origin my-new-feature)
  5. Créer une demande de tirage

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions