Partager via

bibliothèque cliente Azure Event Grid pour .NET - version 4.20.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 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 :

Prise en main

Installer le package

Installer la bibliothèque de client pour NuGet :

dotnet add package Azure.Messaging.EventGrid

Prérequis

Vous devez disposer d’un abonnement Azure et d’un groupe de ressources Azure avec une rubrique ou un domaine Event Grid personnalisé. Suivez ce tutoriel pas à pas pour inscrire le fournisseur de ressources Event Grid et créer des rubriques Event Grid à l’aide du Portail Azure. Il existe un tutoriel similaire à l’aide d’Azure CLI.

Authentifier le client

Pour que la bibliothèque cliente puisse interagir avec une rubrique ou un domaine, vous aurez besoin de la endpoint rubrique Event Grid et d’un credentialobjet , qui peut être créé à l’aide de la clé d’accès de la rubrique.

Vous trouverez le point de terminaison de votre rubrique Event Grid dans le portail Azure ou à l’aide de l’extrait de code Azure CLI ci-dessous.

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

La clé d’accès peut également être trouvée via le portail ou à l’aide de l’extrait de code Azure CLI ci-dessous :

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

S’authentifier à l’aide de la clé d’accès à la rubrique

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 :

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

S’authentifier à l’aide d’une signature d’accès partagé

Event Grid prend également en charge l’authentification avec une signature d’accès partagé qui permet de fournir l’accès à une ressource qui expire avant un certain temps sans partager votre clé d’accès. En règle générale, le flux de travail consiste à ce qu’une application génère la chaîne SAS et la ressaisit à une autre application qui consommerait la chaîne. Générez la signature d’accès partagé :

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

Voici comment il serait utilisé du point de vue du consommateur :

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

EventGridPublisherClient accepte également un ensemble d’options de configuration via EventGridPublisherClientOptions. Par exemple, vous pouvez spécifier un sérialiseur personnalisé qui sera utilisé pour sérialiser les données d’événement au format JSON.

S’authentifier à l’aide d’Azure Active Directory

Azure Event Grid fournit l’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. La bibliothèque Azure Identity fournit une prise en charge facile d’Azure Active Directory pour l’authentification.

Pour envoyer des événements à une rubrique ou à un domaine à l’aide d’Azure Active Directory, le rôle « Expéditeur de données EventGrid » doit être attribué à l’identité authentifiée.

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

Concepts clés

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

EventGridPublisherClient

Un éditeur envoie des événements au service Event Grid. Microsoft publie des événements pour plusieurs services Azure. Vous pouvez publier des événements à partir de votre propre application à l’aide de EventGridPublisherClient.

Schémas d’événement

Un événement est la plus petite quantité d’informations qui décrit entièrement un événement qui s’est produit dans le système. Event Grid prend en charge plusieurs schémas pour les événements d’encodage. Lors de la création d’une rubrique ou d’un domaine personnalisé, vous spécifiez le schéma qui sera utilisé lors de la publication d’événements.

Schéma Event Grid

Même si vous pouvez configurer votre rubrique pour utiliser un schéma personnalisé, il est plus courant d’utiliser le schéma Event Grid déjà défini. Consultez les spécifications et les exigences ici.

Schéma CloudEvents v1.0

Une autre option consiste à utiliser le schéma CloudEvents v1.0. CloudEvents est un projet Cloud Native Computing Foundation qui produit une spécification pour décrire les données d’événement d’une manière commune. Le résumé du service de CloudEvents est disponible ici.

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. Utilisez la SendEvents méthode ou SendEventsAsync pour la publication.

Remise d’événement

Les événements remis aux consommateurs par Event Grid sont remis au format JSON. En fonction du type de consommateur à qui la livraison est effectuée, le service Event Grid peut fournir un ou plusieurs événements dans le cadre d’une seule charge utile. La gestion des événements sera différente en fonction du schéma sous lequel l’événement a été remis. Toutefois, le modèle général reste le même :

  • Analysez les événements de JSON en événements individuels. En fonction du schéma d’événement (Event Grid ou CloudEvents), vous pouvez désormais accéder aux informations de base sur l’événement dans l’enveloppe (propriétés présentes pour tous les événements, comme l’heure et le type de l’événement).
  • Désérialisez les données d’événement. Étant donné un EventGridEvent ou CloudEvent, l’utilisateur peut tenter d’accéder à la charge utile de l’événement, ou aux données, en désérialisant vers un type spécifique. Vous pouvez fournir un sérialiseur personnalisé à ce stade pour décoder correctement les données.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Publier des événements Event Grid dans une rubrique Event Grid

La publication d’événements dans Event Grid est effectuée à l’aide de EventGridPublisherClient. Utilisez la méthode fournie SendEvent/SendEventAsync pour publier un événement unique dans la rubrique.

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

Pour publier un lot d’événements, utilisez la SendEvents/SendEventsAsync méthode .

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

Publier CloudEvents dans une rubrique Event Grid

La publication d’événements dans Event Grid est effectuée à l’aide de EventGridPublisherClient. Utilisez la méthode fournie SendEvents/SendEventsAsync pour publier des événements dans la rubrique.

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

Publier des événements Event Grid dans un domaine Event Grid

Un domaine d’événements est un outil de gestion pour un grand nombre de rubriques Event Grid liées à la même application. Vous pouvez le considérer comme une méta-rubrique pouvant compter des milliers de rubriques individuelles. Lorsque vous créez un domaine d’événements, vous recevez un point de terminaison de publication identique à celui que vous auriez reçu si vous aviez créé une rubrique dans Event Grid.

Pour publier des événements dans une rubrique d’un domaine d’événements, envoyez-les au point de terminaison du domaine comme vous le feriez pour une rubrique personnalisée. La seule différence est que vous devez spécifier la rubrique dans laquelle vous souhaitez envoyer l’événement.

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

Pour l’envoi de CloudEvents, la source CloudEvent est utilisée comme rubrique de domaine :

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

Réception et désérialisation des événements

Il existe plusieurs services Azure différents qui agissent en tant que gestionnaires d’événements.

Remarque : si vous utilisez des webhooks pour la remise d’événements du schéma Event Grid, Event Grid vous oblige à prouver la propriété de votre point de terminaison Webhook avant de commencer à remettre des événements à ce point de terminaison. Au moment de la création de l’abonnement aux événements, Event Grid envoie un événement de validation d’abonnement à votre point de terminaison, comme indiqué ci-dessous. Pour en savoir plus sur l’établissement de l’établissement d’une négociation, cliquez ici : Remise d’événements webhook. Pour le schéma CloudEvents, le service valide la connexion à l’aide de la méthode options HTTP. En savoir plus ici : Validation CloudEvents.

Une fois les événements remis au gestionnaire d’événements, nous pouvons désérialiser la charge utile JSON dans une liste d’événements.

Utilisation de EventGridEvent:

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

Utilisation de CloudEvent:

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

Désérialisation des données d’événement

À partir de là, vous pouvez accéder aux données d’événement en désérialisant vers un type spécifique en appelant ToObjectFromJson<T>() sur la Data propriété. Pour désérialiser vers le type correct, la EventType propriété (Type pour CloudEvents) permet de faire la distinction entre différents événements. Les données d’événement personnalisées doivent être désérialisées à l’aide de la méthode ToObjectFromJson<T>()générique . Il existe également une méthode ToObject<T>() d’extension qui accepte un personnalisé ObjectSerializer pour désérialiser les données d’événement.

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

Utilisation de TryGetSystemEventData():

Si vous attendez principalement des événements système, il peut être plus propre d’activer TryGetSystemEventData() et d’utiliser la correspondance de modèle pour agir sur les événements individuels. Si un événement n’est pas un événement système, la méthode retourne false et le paramètre out est null.

En guise de mise en garde, si vous utilisez un type d’événement personnalisé avec une valeur EventType qui est ajoutée ultérieurement en tant qu’événement système par le service et le SDK, la valeur de retour de TryGetSystemEventData passerait à falsetrue. Cela peut se présenter si vous créez de manière préventive vos propres événements personnalisés pour les événements qui sont déjà envoyés par le service, mais qui n’ont pas encore été ajoutés au SDK. Dans ce cas, il est préférable d’utiliser la méthode générique ToObjectFromJson<T> sur la Data propriété afin que votre flux de code ne change pas automatiquement après la mise à niveau (bien sûr, vous pouvez toujours modifier votre code pour consommer le modèle d’événement système nouvellement publié par opposition à votre modèle personnalisé).

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

Dépannage

Réponses du service

SendEvents() retourne un code de réponse HTTP du service. Un RequestFailedException est levée en tant que réponse de service pour toutes les demandes ayant échoué. L’exception contient des informations sur le code de réponse retourné par le service.

Désérialisation des données d’événement

  • Si les données d’événement ne sont pas valides JSON, un JsonException est levée lors de l’appel Parse ou ParseMany.
  • Si le schéma d’événements ne correspond pas au type auquel est désérialisé (par exemple, l’appel CloudEvent.Parse sur un événement EventGridSchema), un ArgumentException est levée.
  • Si Parse est appelé sur les données qui contiennent plusieurs événements, un ArgumentException est levée. ParseMany doit être utilisé ici à la place.

Configuration de la journalisation de la console

Vous pouvez également activer la journalisation de la console facilement si vous souhaitez approfondir les requêtes que vous formulez sur le 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é du kit de développement logiciel (SDK) Azure.

Event Grid sur Kubernetes

Cette bibliothèque a été testée et validée sur Kubernetes à l’aide d’Azure Arc.

Étapes suivantes

Pour plus https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.20.0/sdk/eventgrid/Azure.Messaging.EventGrid/samples d’informations sur les utilisations courantes de la bibliothèque cliente Event Grid : Exemples Event Grid.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez Contrats de licence contributeur.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

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