Dela via

Azure Event Grid klientbibliotek för .NET – version 4.14.1

  • Artikel

Med Azure Event Grid kan du enkelt skapa program med händelsebaserade arkitekturer. Event Grid-tjänsten hanterar fullständigt all routning av händelser från alla källor, till alla mål, för alla program. Azure-tjänsthändelser och anpassade händelser kan publiceras direkt till tjänsten, där händelserna sedan kan filtreras och skickas till olika mottagare, till exempel inbyggda hanterare eller anpassade webhooks. Mer information om Azure Event Grid: Vad är Event Grid?

Använd klientbiblioteket för Azure Event Grid för att:

Komma igång

Installera paketet

Installera klientbiblioteket från NuGet:

dotnet add package Azure.Messaging.EventGrid

Förutsättningar

Du måste ha en Azure-prenumeration och en Azure-resursgrupp med ett anpassat Event Grid-ämne eller en domän. Följ den här stegvisa självstudien för att registrera Event Grid-resursprovidern och skapa Event Grid-ämnen med hjälp av Azure Portal. Det finns en liknande självstudie som använder Azure CLI.

Autentisera klienten

För att klientbiblioteket ska kunna interagera med ett ämne eller en domän behöver endpoint du event grid-ämnet och , credentialsom kan skapas med hjälp av ämnets åtkomstnyckel.

Du hittar slutpunkten för event grid-ämnet antingen i Azure-portalen eller med hjälp av Azure CLI-kodfragmentet nedan.

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

Åtkomstnyckeln kan också hittas via portalen eller med hjälp av Azure CLI-kodfragmentet nedan:

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

Autentisera med hjälp av ämnesåtkomstnyckel

När du har åtkomstnyckeln och ämnesslutpunkten kan du skapa utgivarklienten på följande sätt:

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

Autentisera med signatur för delad åtkomst

Event Grid stöder också autentisering med en signatur för delad åtkomst som gör det möjligt att ge åtkomst till en resurs som upphör att gälla vid en viss tidpunkt utan att dela din åtkomstnyckel. I allmänhet skulle arbetsflödet vara att ett program skulle generera SAS-strängen och lämna över strängen till ett annat program som skulle använda strängen. Generera SAS:

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

Så här används det ur konsumentens perspektiv:

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

EventGridPublisherClient accepterar också en uppsättning konfigurationsalternativ via EventGridPublisherClientOptions. Du kan till exempel ange en anpassad serialiserare som ska användas för att serialisera händelsedata till JSON.

Autentisera med hjälp av Azure Active Directory

Azure Event Grid tillhandahåller integrering med Azure Active Directory (Azure AD) för identitetsbaserad autentisering av begäranden. Med Azure AD kan du använda rollbaserad åtkomstkontroll (RBAC) för att ge åtkomst till dina Azure Event Grid resurser till användare, grupper eller program. Azure Identity-biblioteket tillhandahåller enkelt Azure Active Directory-stöd för autentisering.

Om du vill skicka händelser till ett ämne eller en domän med hjälp av Azure Active Directory ska den autentiserade identiteten ha rollen "EventGrid Data Sender" tilldelad.

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

Viktiga begrepp

Information om allmänna Event Grid-begrepp: Begrepp i Azure Event Grid.

EventGridPublisherClient

En utgivare skickar händelser till Event Grid-tjänsten. Microsoft publicerar händelser för flera Azure-tjänster. Du kan publicera händelser från ditt eget program med hjälp av EventGridPublisherClient.

Händelsescheman

En händelse är den minsta mängd information som fullständigt beskriver något som har hänt i systemet. Event Grid stöder flera scheman för kodning av händelser. När ett anpassat ämne eller en domän skapas anger du det schema som ska användas vid publicering av händelser.

Event Grid-schema

Du kan konfigurera ämnet så att det använder ett anpassat schema, men det är vanligare att använda det redan definierade Event Grid-schemat. Se specifikationerna och kraven här.

CloudEvents v1.0-schema

Ett annat alternativ är att använda schemat CloudEvents v1.0. CloudEvents är ett Cloud Native Computing Foundation-projekt som skapar en specifikation för att beskriva händelsedata på ett vanligt sätt. Tjänstsammanfattningen för CloudEvents finns här.

Oavsett vilket schema ditt ämne eller din domän är konfigurerad för att använda EventGridPublisherClient , kommer att användas för att publicera händelser till den. SendEvents Använd metoden eller SendEventsAsync för publicering.

Händelseleverans

Händelser som levereras till konsumenter av Event Grid levereras som JSON. Beroende på vilken typ av konsument som levereras till kan Event Grid-tjänsten leverera en eller flera händelser som en del av en enda nyttolast. Hanteringen av händelser skiljer sig åt beroende på vilket schema händelsen levererades som. Det allmänna mönstret förblir dock detsamma:

  • Parsa händelser från JSON till enskilda händelser. Baserat på händelseschemat (Event Grid eller CloudEvents) kan du nu komma åt grundläggande information om händelsen på kuvertet (egenskaper som finns för alla händelser, till exempel händelsetid och typ).
  • Deserialisera händelsedata. EventGridEvent Med en eller CloudEventkan användaren försöka komma åt händelsenyttolasten, eller data, genom att avserialisera till en viss typ. Du kan ange en anpassad serialiserare nu för att avkoda data korrekt.

Trådsäkerhet

Vi garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra (riktlinje). Detta säkerställer att rekommendationen att återanvända klientinstanser alltid är säker, även över trådar.

Ytterligare begrepp

Klientalternativ | Åtkomst till svaret | Tidskrävande åtgärder | Hantera fel | Diagnostik | Gäckande | Klientlivslängd

Exempel

Publicera Event Grid-händelser till ett Event Grid-ämne

Publicering av händelser till Event Grid utförs med hjälp av EventGridPublisherClient. Använd den angivna SendEvent/SendEventAsync metoden för att publicera en enskild händelse i ämnet.

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

Om du vill publicera en batch med händelser använder du SendEvents/SendEventsAsync metoden .

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

Publicera CloudEvents till ett Event Grid-ämne

Publicering av händelser till Event Grid utförs med hjälp av EventGridPublisherClient. Använd den angivna SendEvents/SendEventsAsync metoden för att publicera händelser i ämnet.

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

Publicera Event Grid-händelser till en Event Grid-domän

En händelsedomän är ett hanteringsverktyg för ett stort antal Event Grid-ämnen som är relaterade till samma program. Du kan se det som ett metaämne som kan innehålla tusentals enskilda ämnen. När du skapar en händelsedomän får du en publiceringsslutpunkt som liknar om du hade skapat ett ämne i Event Grid.

Om du vill publicera händelser till ett ämne i en händelsedomän skickar du händelserna till domänens slutpunkt på samma sätt som för ett anpassat ämne. Den enda skillnaden är att du måste ange det ämne som du vill att händelsen ska levereras till.

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

För att skicka CloudEvents används CloudEvent-källan som domänavsnitt:

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

Ta emot och avserialisera händelser

Det finns flera olika Azure-tjänster som fungerar som händelsehanterare.

Obs! Om du använder Webhooks för händelseleverans av Event Grid-schemat kräver Event Grid att du bevisar ägarskapet för din Webhook-slutpunkt innan den börjar leverera händelser till den slutpunkten. När händelseprenumerationen skapas skickar Event Grid en prenumerationsverifieringshändelse till din slutpunkt enligt nedan. Läs mer om hur du slutför handskakningen här: Leverans av Webhook-händelser. För CloudEvents-schemat validerar tjänsten anslutningen med hjälp av metoden HTTP-alternativ. Läs mer här: CloudEvents-validering.

När händelser har levererats till händelsehanteraren kan vi deserialisera JSON-nyttolasten till en lista över händelser.

Använda EventGridEvent:

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

Använda CloudEvent:

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

Avserialisera händelsedata

Härifrån kan man komma åt händelsedata genom att avserialisera till en viss typ genom att anropa ToObjectFromJson<T>() på Data egenskapen . För att deserialisera till rätt typ hjälper EventType egenskapen (Type för CloudEvents) till att skilja mellan olika händelser. Anpassade händelsedata ska deserialiseras med hjälp av den generiska metoden ToObjectFromJson<T>(). Det finns också en tilläggsmetod ToObject<T>() som accepterar en anpassad ObjectSerializer för att deserialisera händelsedata.

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

Använda TryGetSystemEventData():

Om du förväntar dig mestadels systemhändelser kan det vara renare att slå på TryGetSystemEventData() och använda mönstermatchning för att agera på enskilda händelser. Om en händelse inte är en systemhändelse returnerar metoden false och out-parametern är null.

Om du använder en anpassad händelsetyp med ett EventType-värde som senare läggs till som en systemhändelse av tjänsten och SDK ändras returvärdet TryGetSystemEventData för från false till true. Detta kan uppstå om du i förebyggande syfte skapar egna anpassade händelser för händelser som redan skickas av tjänsten, men som ännu inte har lagts till i SDK:t. I det här fallet är det bättre att använda den allmänna ToObjectFromJson<T> metoden i Data egenskapen så att ditt kodflöde inte ändras automatiskt efter uppgraderingen (du kanske fortfarande vill ändra koden för att använda den nyligen utgivna systemhändelsemodellen i stället för din anpassade modell).

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

Felsökning

Tjänstsvar

SendEvents() returnerar en HTTP-svarskod från tjänsten. En RequestFailedException genereras som ett tjänstsvar för misslyckade begäranden. Undantaget innehåller information om vilken svarskod som returnerades från tjänsten.

Avserialisera händelsedata

  • Om händelsedata inte är giltiga JSON utlöses en JsonException vid anrop Parse eller ParseMany.
  • Om händelseschemat inte motsvarar den typ som deserialiseras till (t.ex. anropar CloudEvent.Parse på en EventGridSchema-händelse) genereras ett ArgumentException .
  • Om Parse anropas på data som innehåller flera händelser genereras ett ArgumentException . ParseMany bör användas här i stället.

Konfigurera konsolloggning

Du kan också enkelt aktivera konsolloggning om du vill fördjupa dig i de begäranden som du gör mot tjänsten.

Distribuerad spårning

Event Grid-biblioteket stöder distribution av spårning direkt. För att följa CloudEvents-specifikationens vägledning om hur du distribuerar spårning anger traceparent biblioteket och tracestate på ExtensionAttributes för en CloudEvent när distribuerad spårning är aktiverad. Mer information om hur du aktiverar distribuerad spårning i ditt program finns i dokumentationen för distribuerad spårning i Azure SDK.

Event Grid på Kubernetes

Det här biblioteket har testats och verifierats på Kubernetes med hjälp av Azure Arc.

Nästa steg

Visa mer https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples här för vanliga användningar av Event Grid-klientbiblioteket: Event Grid-exempel.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Visningar