Delen via

Azure Event Grid clientbibliotheek voor .NET - versie 4.14.1

  • Artikel

Met Azure Event Grid kunt u eenvoudig toepassingen bouwen met op gebeurtenissen gebaseerde architecturen. De Event Grid-service beheert alle routering van gebeurtenissen van elke bron naar elke bestemming voor elke toepassing volledig. Azure-servicegebeurtenissen en aangepaste gebeurtenissen kunnen rechtstreeks naar de service worden gepubliceerd, waar de gebeurtenissen vervolgens kunnen worden gefilterd en verzonden naar verschillende ontvangers, zoals ingebouwde handlers of aangepaste webhooks. Voor meer informatie over Azure Event Grid: Wat is Event Grid?

Gebruik de clientbibliotheek voor Azure Event Grid om het volgende te doen:

Aan de slag

Het pakket installeren

Installeer de clientbibliotheek vanuit NuGet:

dotnet add package Azure.Messaging.EventGrid

Vereisten

U moet een Azure-abonnement en een Azure-resourcegroep met een aangepast Event Grid-onderwerp of -domein hebben. Volg deze stapsgewijze zelfstudie om de Event Grid-resourceprovider te registreren en Event Grid-onderwerpen te maken met behulp van de Azure Portal. Er is een vergelijkbare zelfstudie met behulp van Azure CLI.

De client verifiëren

Om de clientbibliotheek te laten communiceren met een onderwerp of domein, hebt u de endpoint van het Event Grid-onderwerp en een credentialnodig, die kan worden gemaakt met behulp van de toegangssleutel van het onderwerp.

U vindt het eindpunt voor uw Event Grid-onderwerp in de Azure-portal of met behulp van het Azure CLI-fragment hieronder.

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

De toegangssleutel is ook te vinden via de portal of met behulp van het Azure CLI-fragment hieronder:

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

Verifiëren met behulp van toegangssleutel voor onderwerp

Zodra u uw toegangssleutel en onderwerpeindpunt hebt, kunt u de uitgeversclient als volgt maken:

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

Verifiëren met Shared Access Signature

Event Grid ondersteunt ook verificatie met een shared access signature, waarmee toegang kan worden verleend tot een resource die voor een bepaalde tijd verloopt zonder uw toegangssleutel te delen. Over het algemeen zou de werkstroom zijn dat één toepassing de SAS-tekenreeks genereert en de tekenreeks aan een andere toepassing zou overdragen die de tekenreeks zou gebruiken. De SAS genereren:

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

Dit zou als volgt worden gebruikt vanuit het perspectief van de consument:

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

EventGridPublisherClient accepteert ook een set configuratieopties via EventGridPublisherClientOptions. U kunt bijvoorbeeld een aangepaste serialisatiefunctie opgeven die wordt gebruikt om de gebeurtenisgegevens te serialiseren naar JSON.

Verifiëren met Azure Active Directory

Azure Event Grid biedt integratie met Azure Active Directory (Azure AD) voor verificatie op basis van identiteit van aanvragen. Met Azure AD kunt u op rollen gebaseerd toegangsbeheer (RBAC) gebruiken om toegang te verlenen tot uw Azure Event Grid resources aan gebruikers, groepen of toepassingen. De Azure Identity-bibliotheek biedt eenvoudige Ondersteuning voor Azure Active Directory voor verificatie.

Als u gebeurtenissen naar een onderwerp of domein wilt verzenden met behulp van Azure Active Directory, moet aan de geverifieerde identiteit de rol 'EventGrid-gegevenszender' zijn toegewezen.

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

Belangrijkste concepten

Voor informatie over algemene Event Grid-concepten: Concepten in Azure Event Grid.

EventGridPublisherClient

Een uitgever verzendt gebeurtenissen naar de Event Grid-service. Microsoft publiceert gebeurtenissen voor verschillende Azure-services. U kunt gebeurtenissen vanuit uw eigen toepassing publiceren met behulp van de EventGridPublisherClient.

Gebeurtenisschema's

Een gebeurtenis is de kleinste hoeveelheid informatie die een volledige beschrijving geeft van iets dat in het systeem is gebeurd. Event Grid ondersteunt meerdere schema's voor het coderen van gebeurtenissen. Wanneer een aangepast onderwerp of domein wordt gemaakt, geeft u het schema op dat wordt gebruikt bij het publiceren van gebeurtenissen.

Event Grid-schema

Hoewel u uw onderwerp kunt configureren voor het gebruik van een aangepast schema, is het gebruikelijker om het al gedefinieerde Event Grid-schema te gebruiken. Bekijk hier de specificaties en vereisten.

CloudEvents v1.0-schema

Een andere optie is om het Schema CloudEvents v1.0 te gebruiken. CloudEvents is een Cloud Native Computing Foundation-project dat een specificatie produceert voor het beschrijven van gebeurtenisgegevens op een algemene manier. Het serviceoverzicht van CloudEvents vindt u hier.

Ongeacht welk schema uw onderwerp of domein is geconfigureerd voor gebruik, EventGridPublisherClient wordt gebruikt om gebeurtenissen naar het onderwerp of domein te publiceren. Gebruik de SendEvents methode of SendEventsAsync voor publicatie.

Gebeurtenisverzending

Gebeurtenissen die door Event Grid aan consumenten worden geleverd , worden geleverd als JSON. Afhankelijk van het type consument dat wordt geleverd, kan de Event Grid-service een of meer gebeurtenissen leveren als onderdeel van één nettolading. Het verwerken van gebeurtenissen is anders op basis van het schema waarop de gebeurtenis is geleverd. Het algemene patroon blijft echter hetzelfde:

  • Parseer gebeurtenissen van JSON in afzonderlijke gebeurtenissen. Op basis van het gebeurtenisschema (Event Grid of CloudEvents) hebt u nu toegang tot basisinformatie over de gebeurtenis op de envelop (eigenschappen die aanwezig zijn voor alle gebeurtenissen, zoals de tijd en het type van de gebeurtenis).
  • De gebeurtenisgegevens deserialiseren. Op basis van een EventGridEvent of CloudEventkan de gebruiker proberen toegang te krijgen tot de nettolading van de gebeurtenis, of gegevens, door te deserialiseren naar een specifiek type. U kunt op dit punt een aangepaste serialisatiefunctie opgeven om de gegevens correct te decoderen.

Veiligheid van schroefdraad

We garanderen dat alle clientexemplaarmethoden thread-veilig en onafhankelijk van elkaar zijn (richtlijn). Dit zorgt ervoor dat de aanbeveling om clientexemplaren opnieuw te gebruiken altijd veilig is, zelfs voor alle threads.

Aanvullende concepten

Clientopties | Toegang tot het antwoord | Langlopende bewerkingen | Afhandeling van fouten | Diagnostics | Spottende | Clientlevensduur

Voorbeelden

Event Grid-gebeurtenissen publiceren naar een Event Grid-onderwerp

Het publiceren van gebeurtenissen naar Event Grid wordt uitgevoerd met behulp van de EventGridPublisherClient. Gebruik de opgegeven SendEvent/SendEventAsync methode om één gebeurtenis naar het onderwerp te publiceren.

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

Gebruik de SendEvents/SendEventsAsync methode om een batch met gebeurtenissen te publiceren.

// 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 publiceren naar een Event Grid-onderwerp

Het publiceren van gebeurtenissen naar Event Grid wordt uitgevoerd met behulp van de EventGridPublisherClient. Gebruik de opgegeven SendEvents/SendEventsAsync methode om gebeurtenissen naar het onderwerp te publiceren.

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

Event Grid-gebeurtenissen publiceren naar een Event Grid-domein

Een gebeurtenisdomein is een beheerprogramma voor grote aantallen Event Grid-onderwerpen die betrekking hebben op dezelfde toepassing. U kunt het zien als een meta-onderwerp dat duizenden afzonderlijke onderwerpen kan bevatten. Wanneer u een gebeurtenisdomein maakt, krijgt u een publicatie-eindpunt dat vergelijkbaar is met wanneer u een onderwerp hebt gemaakt in Event Grid.

Als u gebeurtenissen wilt publiceren naar een onderwerp in een gebeurtenisdomein, pusht u de gebeurtenissen naar het eindpunt van het domein op dezelfde manier als voor een aangepast onderwerp. Het enige verschil is dat u het onderwerp moet opgeven waaraan u de gebeurtenis wilt laten bezorgen.

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

Voor het verzenden van CloudEvents wordt de CloudEvent-bron gebruikt als het domeinonderwerp:

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

Gebeurtenissen ontvangen en deserialiseren

Er zijn verschillende Azure-services die fungeren als gebeurtenis-handlers.

Opmerking: als u Webhooks gebruikt voor het leveren van gebeurtenissen van het Event Grid-schema, moet u met Event Grid bewijzen dat u eigenaar bent van uw Webhook-eindpunt voordat gebeurtenissen aan dat eindpunt worden geleverd. Op het moment dat het gebeurtenisabonnement wordt gemaakt, verzendt Event Grid een gebeurtenis voor abonnementsvalidatie naar uw eindpunt, zoals hieronder wordt weergegeven. Meer informatie over het voltooien van de handshake vindt u hier: Levering van webhookgebeurtenissen. Voor het CloudEvents-schema valideert de service de verbinding met behulp van de methode HTTP-opties. Meer informatie vindt u hier: CloudEvents-validatie.

Zodra gebeurtenissen zijn geleverd aan de gebeurtenis-handler, kunnen we de JSON-nettolading deserialiseren in een lijst met gebeurtenissen.

Met behulp van EventGridEvent:

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

Met behulp van CloudEvent:

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

Gebeurtenisgegevens deserialiseren

Vanaf hier kan men toegang krijgen tot de gebeurtenisgegevens door deserialisatie te deserialiseren naar een specifiek type door aan te roepen ToObjectFromJson<T>() op de Data eigenschap. Als u wilt deserialiseren naar het juiste type, helpt de EventType eigenschap (Type voor CloudEvents) om onderscheid te maken tussen verschillende gebeurtenissen. Aangepaste gebeurtenisgegevens moeten worden gedeserialiseerd met behulp van de algemene methode ToObjectFromJson<T>(). Er is ook een extensiemethode ToObject<T>() die een aangepaste ObjectSerializer methode accepteert om de gebeurtenisgegevens te deserialiseren.

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

Met behulp van TryGetSystemEventData():

Als u voornamelijk systeemevenementen verwacht, is het mogelijk eenvoudiger om in te schakelen TryGetSystemEventData() en patroonkoppeling te gebruiken om op de afzonderlijke gebeurtenissen te reageren. Als een gebeurtenis geen systeem gebeurtenis is, retourneert de methode false en is de parameter out null.

Als u een aangepast gebeurtenistype gebruikt met een EventType-waarde die later als een systeemevenement wordt toegevoegd door de service en SDK, verandert de retourwaarde van TryGetSystemEventData in falsetrue. Dit kan zich voordoen als u preventief uw eigen aangepaste gebeurtenissen maakt voor gebeurtenissen die al door de service worden verzonden, maar nog niet zijn toegevoegd aan de SDK. In dit geval is het beter om de algemene ToObjectFromJson<T> methode voor de Data eigenschap te gebruiken, zodat uw codestroom niet automatisch wordt gewijzigd na het upgraden (natuurlijk kunt u uw code nog steeds wijzigen om het zojuist uitgebrachte systeemgebeurtenismodel te gebruiken in plaats van uw aangepaste model).

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

Problemen oplossen

Servicereacties

SendEvents() retourneert een HTTP-antwoordcode van de service. Een RequestFailedException wordt gegenereerd als een serviceantwoord voor mislukte aanvragen. De uitzondering bevat informatie over welke antwoordcode is geretourneerd door de service.

Gebeurtenisgegevens deserialiseren

  • Als de gebeurtenisgegevens geen geldige JSON zijn, wordt er een JsonException gegenereerd bij het aanroepen Parse van of ParseMany.
  • Als het gebeurtenisschema niet overeenkomt met het type dat wordt gedeserialiseerd (bijvoorbeeld het aanroepen CloudEvent.Parse van een EventGridSchema-gebeurtenis), wordt een ArgumentException gegenereerd.
  • Als Parse wordt aangeroepen voor gegevens die meerdere gebeurtenissen bevatten, wordt een ArgumentException gegenereerd. ParseMany moet hier worden gebruikt.

Consolelogboekregistratie instellen

U kunt ook eenvoudig consolelogboekregistratie inschakelen als u dieper wilt ingaan op de aanvragen die u tegen de service doet.

Gedistribueerde tracering

De Event Grid-bibliotheek biedt ondersteuning voor het out-of-the-box distribueren van tracering. Om te voldoen aan de richtlijnen van de CloudEvents-specificatie voor het distribueren van tracering, stelt de bibliotheek de traceparent en tracestate in op van ExtensionAttributes een CloudEvent wanneer gedistribueerde tracering is ingeschakeld. Raadpleeg de documentatie over gedistribueerde tracering van Azure SDK voor meer informatie over het inschakelen van gedistribueerde tracering in uw toepassing.

Event Grid in Kubernetes

Deze bibliotheek is getest en gevalideerd op Kubernetes met behulp van Azure Arc.

Volgende stappen

Bekijk hier meer https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples voor veelvoorkomend gebruik van de Event Grid-clientbibliotheek: Event Grid-voorbeelden.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com. voor meer informatie

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven