Sdílet prostřednictvím

Azure Event Grid klientské knihovny pro .NET – verze 4.14.1

  • Článek

Azure Event Grid umožňuje snadno sestavovat aplikace pomocí architektur založených na událostech. Služba Event Grid plně spravuje veškeré směrování událostí z libovolného zdroje do libovolného cíle pro libovolnou aplikaci. Události služby Azure a vlastní události je možné publikovat přímo do služby, kde se pak události dají filtrovat a odesílat různým příjemcům, jako jsou integrované obslužné rutiny nebo vlastní webhooky. Další informace o Azure Event Grid: Co je Event Grid?

Pomocí klientské knihovny Azure Event Grid:

Začínáme

Instalace balíčku

Nainstalujte klientskou knihovnu z NuGetu:

dotnet add package Azure.Messaging.EventGrid

Požadavky

Musíte mít předplatné Azure a skupinu prostředků Azure s vlastním tématem nebo doménou Event Gridu. Podle tohoto podrobného kurzu zaregistrujte poskytovatele prostředků Event Gridu a pomocí Azure Portal vytvořte témata event gridu. K dispozici je podobný kurz s využitím Azure CLI.

Ověření klienta

Aby klientská knihovna mohla pracovat s tématem nebo doménou, budete potřebovat endpoint téma Event Gridu a credentialobjekt , který můžete vytvořit pomocí přístupového klíče tématu.

Koncový bod pro téma Event Gridu najdete na webu Azure Portal nebo pomocí fragmentu kódu Azure CLI níže.

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

Přístupový klíč najdete také na portálu nebo pomocí následujícího fragmentu kódu Azure CLI:

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

Ověřování pomocí přístupových klíčů k tématu

Jakmile budete mít přístupový klíč a koncový bod tématu, můžete klienta vydavatele vytvořit následujícím způsobem:

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

Ověřování pomocí sdíleného přístupových podpisů

Event Grid také podporuje ověřování pomocí sdíleného přístupového podpisu, který umožňuje poskytnout přístup k prostředku, jehož platnost do určité doby vyprší, aniž byste museli sdílet přístupový klíč. Obecně by pracovní postup byl takový, že jedna aplikace by vygenerovala řetězec SAS a předala řetězec jiné aplikaci, která by tento řetězec spotřebovala. Vygenerujte SAS:

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

Tady je postup, jak by se použil z pohledu spotřebitele:

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

EventGridPublisherClient přijímá také sadu možností konfigurace prostřednictvím EventGridPublisherClientOptions. Můžete například zadat vlastní serializátor, který se použije k serializaci dat událostí do FORMÁTU JSON.

Ověření pomocí služby Azure Active Directory

Azure Event Grid poskytuje integraci s Azure Active Directory (Azure AD) pro ověřování požadavků na základě identity. S Azure AD můžete pomocí řízení přístupu na základě role (RBAC) udělit uživatelům, skupinám nebo aplikacím přístup k prostředkům Azure Event Grid. Knihovna identit Azure poskytuje snadnou podporu ověřování v Azure Active Directory.

Pokud chcete odesílat události do tématu nebo domény pomocí Azure Active Directory, musí mít ověřená identita přiřazenou roli EventGrid Data Sender.

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

Klíčové koncepty

Informace o obecných konceptech služby Event Grid najdete v tématu Koncepty v Azure Event Grid.

EventGridPublisherClient

Vydavatel odesílá události do služby Event Grid. Microsoft publikuje události pro několik služeb Azure. Události můžete publikovat z vlastní aplikace pomocí EventGridPublisherClient.

Schémata událostí

Událost je nejmenší množství informací, které plně popisují něco, co se stalo v systému. Event Grid podporuje více schémat pro kódování událostí. Při vytvoření vlastního tématu nebo domény zadáte schéma, které se použije při publikování událostí.

Schéma služby Event Grid

I když můžete téma nakonfigurovat tak, aby používalo vlastní schéma, běžnější je použít již definované schéma Event Gridu. Specifikace a požadavky najdete tady.

Schéma CloudEvents verze 1.0

Další možností je použít schéma CloudEvents verze 1.0. CloudEvents je projekt cloudových nativních výpočetních prostředků, který vytváří specifikaci pro běžné popisování dat událostí. Souhrn služby CloudEvents najdete tady.

Bez ohledu na to, jaké schéma má vaše téma nebo doména nakonfigurované, EventGridPublisherClient se použije k publikování událostí. Pro publikování použijte metodu SendEvents nebo SendEventsAsync .

Doručování událostí

Události doručované příjemcům službou Event Grid se doručují jako JSON. Služba Event Grid může v závislosti na typu příjemce doručovat jednu nebo více událostí jako součást jedné datové části. Zpracování událostí se bude lišit v závislosti na schématu, jako byla událost doručena. Obecný vzor ale zůstane stejný:

  • Parsuje události z JSON do jednotlivých událostí. Na základě schématu událostí (Event Grid nebo CloudEvents) teď máte přístup k základním informacím o události na obálce (vlastnosti, které jsou přítomné pro všechny události, například čas a typ události).
  • Deserializovat data událostí. V případě EventGridEventCloudEventnebo se uživatel může pokusit o přístup k datové části události nebo datům deserializací na konkrétní typ. V tomto okamžiku můžete zadat vlastní serializátor pro správné dekódování dat.

Bezpečnost vlákna

Zaručujeme, že všechny metody instance klienta jsou bezpečné pro přístup z více vláken a nezávislé na sobě (pokyny). Tím se zajistí, že doporučení opakovaného použití instancí klienta bude vždy bezpečné, a to i napříč vlákny.

Další koncepty

Možnosti | klienta Přístup k odpovědi | Dlouhotrvající operace | Zpracování selhání | Diagnostika | Zesměšňovat | Životnost klienta

Příklady

Publikování událostí Event Gridu do tématu Event Gridu

Publikování událostí do Event Gridu EventGridPublisherClientse provádí pomocí nástroje . K publikování jedné události do tématu použijte zadanou SendEvent/SendEventAsync metodu.

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

Pokud chcete publikovat dávku událostí, použijte metodu SendEvents/SendEventsAsync .

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

Publikování CloudEvents do tématu Event Gridu

Publikování událostí do Event Gridu EventGridPublisherClientse provádí pomocí nástroje . K publikování událostí do tématu použijte zadanou SendEvents/SendEventsAsync metodu.

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

Publikování událostí Event Gridu do domény Event Gridu

Doména událostí je nástroj pro správu velkého počtu témat Event Gridu souvisejících se stejnou aplikací. Můžete si ho představit jako metatematiku, která může obsahovat tisíce jednotlivých témat. Když vytvoříte doménu události, dostanete koncový bod publikování podobný tomu, pokud jste vytvořili téma ve službě Event Grid.

Pokud chcete publikovat události do libovolného tématu v doméně událostí, odešlete události do koncového bodu domény stejným způsobem jako u vlastního tématu. Jediným rozdílem je, že musíte zadat téma, do kterého se má událost doručovat.

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

Pro odesílání CloudEvents se jako téma domény používá zdroj CloudEvent:

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

Příjem a deserializace událostí

Existuje několik různých služeb Azure, které fungují jako obslužné rutiny událostí.

Poznámka: Pokud k doručování událostí schématu Event Gridu používáte Webhooky, vyžaduje služba Event Grid, abyste před zahájením doručování událostí do tohoto koncového bodu prokázali vlastnictví koncového bodu Webhooku. Při vytváření odběru událostí odešle Event Grid do vašeho koncového bodu událost ověření předplatného, jak je vidět níže. Další informace o dokončení metody handshake najdete tady: Doručování událostí Webhooku. V případě schématu CloudEvents služba ověří připojení pomocí metody možnosti HTTP. Další informace najdete tady: Ověřování CloudEvents.

Jakmile se události doručí do obslužné rutiny události, můžeme datovou část JSON deserializovat do seznamu událostí.

Pomocí EventGridEvent:

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

Pomocí CloudEvent:

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

Deserializace dat událostí

Odtud lze získat přístup k datům událostí deserializací na konkrétní typ voláním ToObjectFromJson<T>()Data vlastnosti . Aby bylo možné deserializovat na správný typ, EventType vlastnost (Type pro CloudEvents) pomáhá rozlišovat mezi různými událostmi. Vlastní data událostí by měla být deserializována pomocí obecné metody ToObjectFromJson<T>(). K dispozici je také rozšiřující metoda ToObject<T>() , která přijímá vlastní ObjectSerializer pro deserializaci dat události.

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

Pomocí TryGetSystemEventData():

Pokud očekáváte převážně systémové události, může být přehlednější zapnout TryGetSystemEventData() a používat porovnávání vzorů k akci s jednotlivými událostmi. Pokud událost není událostí systému, vrátí metoda hodnotu false a parametr out bude mít hodnotu null.

Upozornění platí, že pokud používáte vlastní typ události s hodnotou EventType, kterou služba a sada SDK později přidají jako systémovou událost, návratová hodnota TryGetSystemEventData by se změnila z false na true. K tomu může dojít, pokud preventivně vytváříte vlastní události pro události, které už služba odesílá, ale ještě nebyly přidány do sady SDK. V takovém případě je lepší použít u vlastnosti obecnou ToObjectFromJson<T> metodu Data , aby se tok kódu po upgradu automaticky nezměnil (samozřejmě budete chtít kód upravit tak, aby využíval nově vydaný model událostí systému, a ne vlastní 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;
        }
    }
}

Řešení potíží

Odpovědi služby

SendEvents() vrátí kód odpovědi HTTP ze služby. Jako RequestFailedException odpověď služby pro všechny neúspěšné požadavky se vyvolá hodnota . Výjimka obsahuje informace o tom, jaký kód odpovědi služba vrátila.

Deserializace dat událostí

  • Pokud data události nejsou platná ve formátu JSON, JsonException vyvolá se při volání Parse nebo ParseMany.
  • Pokud schéma události neodpovídá typu, na který je deserializován (např. volání CloudEvent.Parse události EventGridSchema), ArgumentException vyvolá se událost .
  • Pokud Parse je volána u dat, která obsahují více událostí, ArgumentException vyvolá se . ParseMany místo toho byste měli použít.

Nastavení protokolování konzoly

Protokolování konzoly můžete také snadno povolit, pokud chcete hlouběji prozkoumat požadavky, které vůči službě provádíte.

Distribuované trasování

Knihovna Event Grid podporuje distribuci trasování z krabice. Aby bylo možné dodržet pokyny specifikace CloudEvents k distribuci trasování, nastaví traceparent knihovna při povolení distribuovaného CloudEvent trasování hodnotu a tracestate na ExtensionAttributes . Další informace o povolení distribuovaného trasování ve vaší aplikaci najdete v dokumentaci k distribuovanému trasování sady Azure SDK.

Event Grid v Kubernetes

Tato knihovna byla testována a ověřena v Kubernetes pomocí Azure Arc.

Další kroky

Další informace https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples o běžných použitích klientské knihovny Event Gridu najdete tady: Ukázky Event Gridu.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete na stránce https://cla.microsoft.com.

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Imprese