Share via

Azure Event Grid Clientbibliothek für .NET – Version 4.20.0

  • Artikel

Mit Azure Event Grid können Sie mühelos Anwendungen mit ereignisbasierten Architekturen erstellen. Der Event Grid-Dienst verwaltet das gesamte Routing von Ereignissen von jeder Quelle an ein beliebiges Ziel für jede Anwendung vollständig. Azure-Dienstereignisse und benutzerdefinierte Ereignisse können direkt im Dienst veröffentlicht werden, wo die Ereignisse dann gefiltert und an verschiedene Empfänger gesendet werden können, z. B. integrierte Handler oder benutzerdefinierte Webhooks. Weitere Informationen zu Azure Event Grid: Was ist Event Grid?

Verwenden Sie die Clientbibliothek für Azure Event Grid für Folgendes:

Erste Schritte

Installieren des Pakets

Installieren Sie die Clientbibliothek über NuGet:

dotnet add package Azure.Messaging.EventGrid

Voraussetzungen

Sie müssen über ein Azure-Abonnement und eine Azure-Ressourcengruppe mit einem benutzerdefinierten Event Grid-Thema oder einer benutzerdefinierten Domäne verfügen. Führen Sie dieses schrittweise Tutorial aus, um den Event Grid-Ressourcenanbieter zu registrieren und Event Grid-Themen mithilfe des Azure-Portal zu erstellen. Es gibt ein ähnliches Tutorial mit der Azure CLI.

Authentifizieren des Clients

Damit die Clientbibliothek mit einem Thema oder einer Domäne interagieren kann, benötigen Sie das endpoint des Event Grid-Themas und ein credential, das mithilfe des Zugriffsschlüssels des Themas erstellt werden kann.

Sie finden den Endpunkt für Ihr Event Grid-Thema entweder im Azure-Portal oder mithilfe des folgenden Azure CLI-Ausschnitts .

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

Der Zugriffsschlüssel kann auch über das Portal oder mithilfe des folgenden Azure CLI-Ausschnitts gefunden werden:

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

Authentifizieren mithilfe des Themazugriffsschlüssels

Sobald Sie über Ihren Zugriffsschlüssel und Den Themenendpunkt verfügen, können Sie den Herausgeberclient wie folgt erstellen:

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

Authentifizieren mithilfe der Shared Access Signature

Event Grid unterstützt auch die Authentifizierung mit einer freigegebenen Zugriffssignatur, die das Bereitstellen des Zugriffs auf eine Ressource ermöglicht, die bis zu einer bestimmten Zeit abläuft, ohne Ihren Zugriffsschlüssel frei zu geben. Im Allgemeinen wäre der Workflow, dass eine Anwendung die SAS-Zeichenfolge generiert und die Zeichenfolge an eine andere Anwendung übergibt, die die Zeichenfolge nutzt. Generieren Sie die SAS:

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

So würde es aus Sicht des Verbrauchers verwendet werden:

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

EventGridPublisherClient akzeptiert auch eine Reihe von Konfigurationsoptionen über EventGridPublisherClientOptions. Sie können beispielsweise ein benutzerdefiniertes Serialisierungsprogramm angeben, das zum Serialisieren der Ereignisdaten in JSON verwendet wird.

Authentifizieren mit Azure Active Directory

Azure Event Grid bietet die Integration in Azure Active Directory (Azure AD) für die identitätsbasierte Authentifizierung von Anforderungen. Mit Azure AD können Sie die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) verwenden, um Benutzern, Gruppen oder Anwendungen Zugriff auf Ihre Azure Event Grid Ressourcen zu gewähren. Die Azure Identity-Bibliothek bietet einfache Azure Active Directory-Unterstützung für die Authentifizierung.

Um Ereignisse mithilfe von Azure Active Directory an ein Thema oder eine Domäne zu senden, sollte der authentifizierten Identität die Rolle "EventGrid Data Sender" zugewiesen sein.

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

Wichtige Begriffe

Informationen zu allgemeinen Event Grid-Konzepten: Konzepte in Azure Event Grid.

EventGridPublisherClient

Ein Herausgeber sendet Ereignisse an den Event Grid-Dienst. Microsoft veröffentlicht Ereignisse für mehrere Azure-Dienste. Sie können Ereignisse aus Ihrer eigenen Anwendung veröffentlichen, indem Sie verwenden EventGridPublisherClient.

Ereignisschemas

Ein Ereignis ist die kleinste Menge an Informationen, die etwas vollständig beschreibt, was im System passiert ist. Event Grid unterstützt mehrere Schemas für die Codierung von Ereignissen. Wenn ein benutzerdefiniertes Thema oder eine benutzerdefinierte Domäne erstellt wird, geben Sie das Schema an, das beim Veröffentlichen von Ereignissen verwendet wird.

Event Grid-Schema

Sie können Ihr Thema zwar für die Verwendung eines benutzerdefinierten Schemas konfigurieren, aber es ist häufiger, das bereits definierte Event Grid-Schema zu verwenden. Sehen Sie sich die Spezifikationen und Anforderungen hier an.

CloudEvents v1.0-Schema

Eine weitere Option ist die Verwendung des CloudEvents v1.0-Schemas. CloudEvents ist ein Cloud Native Computing Foundation-Projekt, das eine Spezifikation für die allgemeine Beschreibung von Ereignisdaten erstellt. Die Dienstzusammenfassung von CloudEvents finden Sie hier.

Unabhängig davon, welches Schema Ihr Thema oder Ihre Domäne für die Verwendung konfiguriert ist, EventGridPublisherClient werden zum Veröffentlichen von Ereignissen verwendet. Verwenden Sie die -Methode oder SendEventsAsync für die SendEvents Veröffentlichung.

Ereignisbereitstellung

Ereignisse, die von Event Grid an Consumer übermittelt werden, werden als JSON übermittelt. Je nach Art des Consumer, an den übermittelt wird, kann der Event Grid-Dienst ein oder mehrere Ereignisse als Teil einer einzelnen Nutzlast bereitstellen. Die Behandlung von Ereignissen unterscheidet sich je nachdem, unter welchem Schema das Ereignis übermittelt wurde. Das allgemeine Muster bleibt jedoch unverändert:

  • Analysieren sie Ereignisse von JSON in einzelne Ereignisse. Basierend auf dem Ereignisschema (Event Grid oder CloudEvents) können Sie jetzt auf grundlegende Informationen zum Ereignis auf dem Umschlag zugreifen (Eigenschaften, die für alle Ereignisse vorhanden sind, z. B. Ereigniszeit und -typ).
  • Deserialisieren Sie die Ereignisdaten. Bei einem EventGridEvent oder CloudEventkann der Benutzer versuchen, auf die Ereignisnutzlast oder -daten zuzugreifen, indem er auf einen bestimmten Typ deserialisiert. Sie können an dieser Stelle ein benutzerdefiniertes Serialisierer bereitstellen, um die Daten ordnungsgemäß zu decodieren.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Veröffentlichen von Event Grid-Ereignissen in einem Event Grid-Thema

Das Veröffentlichen von Ereignissen in Event Grid wird mithilfe von EventGridPublisherClientausgeführt. Verwenden Sie die bereitgestellte SendEvent/SendEventAsync Methode, um ein einzelnes Ereignis im Thema zu veröffentlichen.

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

Verwenden Sie die SendEvents/SendEventsAsync -Methode, um einen Batch von Ereignissen zu veröffentlichen.

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

Veröffentlichen von CloudEvents in einem Event Grid-Thema

Das Veröffentlichen von Ereignissen in Event Grid wird mithilfe von EventGridPublisherClientausgeführt. Verwenden Sie die bereitgestellte SendEvents/SendEventsAsync Methode, um Ereignisse im Thema zu veröffentlichen.

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

Veröffentlichen von Event Grid-Ereignissen in einer Event Grid-Domäne

Eine Ereignisdomäne ist ein Verwaltungstool für eine große Anzahl von Event Grid-Themen, die sich auf dieselbe Anwendung beziehen. Sie können sie sich als ein Metathema vorstellen, das Tausende von Einzelthemen aufweisen kann. Wenn Sie eine Ereignisdomäne erstellen, erhalten Sie einen Veröffentlichungsendpunkt, ähnlich wie beim Erstellen eines Themas in Event Grid.

Um Ereignisse in einem beliebigen Thema in einer Ereignisdomäne zu veröffentlichen, pushen Sie die Ereignisse auf die gleiche Weise wie für ein benutzerdefiniertes Thema an den Endpunkt der Domäne. Der einzige Unterschied besteht darin, dass Sie das Thema angeben müssen, an das das Ereignis übermittelt werden soll.

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

Zum Senden von CloudEvents wird die CloudEvent-Quelle als Domänenthema verwendet:

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

Empfangen und Deserialisieren von Ereignissen

Es gibt mehrere verschiedene Azure-Dienste, die als Ereignishandler fungieren.

Hinweis: Wenn Sie Webhooks für die Ereignisübermittlung des Event Grid-Schemas verwenden, müssen Sie den Besitz Ihres Webhook-Endpunkts nachweisen, bevor er mit der Übermittlung von Ereignissen an diesen Endpunkt beginnt. Zum Zeitpunkt der Erstellung eines Ereignisabonnements sendet Event Grid ein Abonnementüberprüfungsereignis an Ihren Endpunkt, wie unten dargestellt. Weitere Informationen zum Abschließen des Handshakes finden Sie hier: Webhook-Ereignisübermittlung. Für das CloudEvents-Schema überprüft der Dienst die Verbindung mithilfe der HTTP-Optionsmethode. Weitere Informationen finden Sie hier: CloudEvents-Validierung.

Sobald Ereignisse an den Ereignishandler übermittelt wurden, können wir die JSON-Nutzlast in einer Liste von Ereignissen deserialisieren.

Verwenden von EventGridEvent:

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

Verwenden von CloudEvent:

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

Deserialisieren von Ereignisdaten

Von hier aus können Sie auf die Ereignisdaten zugreifen, indem Sie die -Eigenschaft auf einen bestimmten Typ ToObjectFromJson<T>()Data deserialisieren. Um den richtigen Typ zu deserialisieren, hilft die Eigenschaft (Type für CloudEvents) bei der EventType Unterscheidung zwischen verschiedenen Ereignissen. Benutzerdefinierte Ereignisdaten sollten mithilfe der generischen Methode ToObjectFromJson<T>()deserialisiert werden. Es gibt auch eine Erweiterungsmethode ToObject<T>() , die eine benutzerdefinierte ObjectSerializer zum Deserialisieren der Ereignisdaten akzeptiert.

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

Verwenden von TryGetSystemEventData():

Wenn Sie hauptsächlich Systemereignisse erwarten, ist es möglicherweise sauberer, den Musterabgleich einzuschalten TryGetSystemEventData() und zu verwenden, um auf die einzelnen Ereignisse zu reagieren. Wenn ein Ereignis kein Systemereignis ist, gibt die Methode false zurück, und der out-Parameter ist NULL.

Wenn Sie einen benutzerdefinierten Ereignistyp mit einem EventType-Wert verwenden, der später vom Dienst und sdk als Systemereignis hinzugefügt wird, ändert sich der Rückgabewert von TryGetSystemEventData von in falsetrue. Dies kann auftreten, wenn Sie vorab Ihre eigenen benutzerdefinierten Ereignisse für Ereignisse erstellen, die bereits vom Dienst gesendet, aber noch nicht zum SDK hinzugefügt wurden. In diesem Fall ist es besser, die generische ToObjectFromJson<T> Methode für die Data -Eigenschaft zu verwenden, damit sich ihr Codefluss nach dem Upgrade nicht automatisch ändert (natürlich möchten Sie Ihren Code möglicherweise weiterhin ändern, um das neu veröffentlichte Systemereignismodell im Gegensatz zu Ihrem benutzerdefinierten Modell zu nutzen).

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

Problembehandlung

Dienstantworten

SendEvents() gibt einen HTTP-Antwortcode vom Dienst zurück. Ein RequestFailedException wird als Dienstantwort für alle nicht erfolgreichen Anforderungen ausgelöst. Die Ausnahme enthält Informationen darüber, welcher Antwortcode vom Dienst zurückgegeben wurde.

Deserialisieren von Ereignisdaten

  • Wenn die Ereignisdaten nicht gültigen JSON-Code sind, wird ein JsonException ausgelöst, wenn oder ParseManyaufgerufen Parse wird.
  • Wenn das Ereignisschema nicht dem Typ entspricht, für den deserialisiert wird (z. B. aufrufen CloudEvent.Parse eines EventGridSchema-Ereignisses), wird ein ArgumentException ausgelöst.
  • Wenn Parse für Daten aufgerufen wird, die mehrere Ereignisse enthalten, wird ein ArgumentException ausgelöst. ParseMany sollte stattdessen hier verwendet werden.

Einrichten der Konsolenprotokollierung

Sie können auch einfach die Konsolenprotokollierung aktivieren, wenn Sie ausführliche Informationen zu den von Ihnen an den Dienst gesendeten Anforderungen erhalten möchten.

Verteilte Ablaufverfolgung

Die Event Grid-Bibliothek unterstützt die sofort einsatzbereite Verteilung der Ablaufverfolgung. Um dem Leitfaden der CloudEvents-Spezifikation für verteilte Ablaufverfolgung zu genügen, legt die Bibliothek traceparent und tracestate für die ExtensionAttributes eines CloudEvent fest, wenn verteilte Ablaufverfolgung aktiviert ist. Weitere Informationen zum Aktivieren von verteilter Ablaufverfolgung in Ihrer Anwendung finden Sie im Azure SDK in der Dokumentation zur verteilten Ablaufverfolgung.

Event Grid in Kubernetes

Diese Bibliothek wurde mit Azure Arc in Kubernetes getestet und überprüft.

Nächste Schritte

Weitere https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.20.0/sdk/eventgrid/Azure.Messaging.EventGrid/samples Informationen zu allgemeinen Verwendungen der Event Grid-Clientbibliothek finden Sie hier: Event Grid-Beispiele.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter Lizenzvereinbarungen für Mitwirkende.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe