Azure Event Grid biblioteka klienta dla platformy .NET — wersja 4.14.1

  • Artykuł

Usługa Azure Event Grid umożliwia łatwe tworzenie aplikacji za pomocą architektur opartych na zdarzeniach. Usługa Event Grid w pełni zarządza wszystkimi routingiem zdarzeń z dowolnego źródła do dowolnego miejsca docelowego dla dowolnej aplikacji. Zdarzenia usługi platformy Azure i zdarzenia niestandardowe można publikować bezpośrednio w usłudze, gdzie zdarzenia można następnie filtrować i wysyłać do różnych adresatów, takich jak wbudowane programy obsługi lub niestandardowe elementy webhook. Aby dowiedzieć się więcej o Azure Event Grid: Co to jest usługa Event Grid?

Użyj biblioteki klienta, aby Azure Event Grid:

  • Publikowanie zdarzeń w usłudze Event Grid przy użyciu zdarzeń usługi Event Grid, zdarzenia w chmurze 1.0 lub schematów niestandardowych

  • Korzystanie z zdarzeń dostarczonych do procedur obsługi zdarzeń

  • Generowanie tokenów sygnatury dostępu współdzielonego w celu uwierzytelniania zdarzeń publikowania klienta w celu Azure Event Grid tematów

    Kod | źródłowy Pakiet (NuGet) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Próbki | Przewodnik po migracji

Wprowadzenie

Instalowanie pakietu

Zainstaluj bibliotekę klienta z narzędzia NuGet:

dotnet add package Azure.Messaging.EventGrid

Wymagania wstępne

Musisz mieć subskrypcję platformy Azure i grupę zasobów platformy Azure z niestandardowym tematem lub domeną usługi Event Grid. Postępuj zgodnie z tym samouczkiem krok po kroku, aby zarejestrować dostawcę zasobów usługi Event Grid i utworzyć tematy usługi Event Grid przy użyciu Azure Portal. Istnieje podobny samouczek przy użyciu interfejsu wiersza polecenia platformy Azure.

Uwierzytelnianie klienta

Aby biblioteka klienta mogła wchodzić w interakcję z tematem lub domeną, potrzebny endpoint będzie temat usługi Event Grid i element credential, który można utworzyć przy użyciu klucza dostępu tematu.

Punkt końcowy tematu usługi Event Grid można znaleźć w witrynie Azure Portal lub przy użyciu poniższego fragmentu wiersza polecenia platformy Azure .

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

Klucz dostępu można również znaleźć za pośrednictwem portalu lub przy użyciu poniższego fragmentu wiersza polecenia platformy Azure:

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

Uwierzytelnianie przy użyciu klucza dostępu do tematu

Po utworzeniu klucza dostępu i punktu końcowego tematu możesz utworzyć klienta wydawcy w następujący sposób:

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

Uwierzytelnianie przy użyciu sygnatury dostępu współdzielonego

Usługa Event Grid obsługuje również uwierzytelnianie za pomocą sygnatury dostępu współdzielonego, która umożliwia zapewnienie dostępu do zasobu wygasającego przez określony czas bez udostępniania klucza dostępu. Ogólnie rzecz biorąc, przepływ pracy będzie taki, że jedna aplikacja wygeneruje ciąg SYGNATURy dostępu współdzielonego i przekaże ciąg do innej aplikacji, która będzie używać ciągu. Wygeneruj sygnaturę dostępu współdzielonego:

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

Poniżej przedstawiono sposób jego użycia z perspektywy konsumenta:

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

EventGridPublisherClient akceptuje również zestaw opcji konfigurowania za pomocą polecenia EventGridPublisherClientOptions. Można na przykład określić niestandardowy serializator, który będzie używany do serializacji danych zdarzeń do formatu JSON.

Uwierzytelnianie za pomocą usługi Azure Active Directory

Azure Event Grid zapewnia integrację z usługą Azure Active Directory (Azure AD) na potrzeby uwierzytelniania żądań opartych na tożsamościach. Za pomocą Azure AD możesz użyć kontroli dostępu opartej na rolach (RBAC), aby udzielić dostępu do zasobów Azure Event Grid użytkownikom, grupom lub aplikacjom. Biblioteka tożsamości platformy Azure zapewnia łatwą obsługę usługi Azure Active Directory na potrzeby uwierzytelniania.

Aby wysyłać zdarzenia do tematu lub domeny przy użyciu usługi Azure Active Directory, tożsamość uwierzytelniona powinna mieć przypisaną rolę "Nadawca danych usługi EventGrid".

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

Kluczowe pojęcia

Aby uzyskać informacje na temat ogólnych pojęć związanych z usługą Event Grid: Pojęcia w Azure Event Grid.

EventGridPublisherClient

Wydawca wysyła zdarzenia do usługi Event Grid. Firma Microsoft publikuje zdarzenia dla kilku usług platformy Azure. Zdarzenia można publikować z własnej aplikacji przy użyciu polecenia EventGridPublisherClient.

Schematy zdarzeń

Zdarzenie to najmniejsza ilość informacji, które w pełni opisują coś, co wydarzyło się w systemie. Usługa Event Grid obsługuje wiele schematów dla zdarzeń kodowania. Po utworzeniu tematu niestandardowego lub domeny należy określić schemat, który będzie używany podczas publikowania zdarzeń.

Schemat usługi Event Grid

Chociaż można skonfigurować temat do używania schematu niestandardowego, częściej używa się już zdefiniowanego schematu usługi Event Grid. Zobacz specyfikacje i wymagania tutaj.

Schemat cloudEvents w wersji 1.0

Inną opcją jest użycie schematu CloudEvents w wersji 1.0. CloudEvents to projekt Cloud Native Computing Foundation, który tworzy specyfikację opisującą dane zdarzeń w typowy sposób. Podsumowanie usługi CloudEvents można znaleźć tutaj.

Niezależnie od schematu skonfigurowanego do użycia EventGridPublisherClient tematu lub domeny będzie używany do publikowania zdarzeń. Użyj metody or SendEventsAsync do publikowaniaSendEvents.

Dostarczanie zdarzeń

Zdarzenia dostarczane użytkownikom przez usługę Event Grid są dostarczane jako dane JSON. W zależności od typu dostarczanego odbiorcy usługa Event Grid może dostarczać co najmniej jedno zdarzenie w ramach jednego ładunku. Obsługa zdarzeń będzie inna w zależności od schematu, w którym zostało dostarczone zdarzenie. Jednak ogólny wzorzec pozostanie taki sam:

  • Analizowanie zdarzeń z formatu JSON do poszczególnych zdarzeń. Na podstawie schematu zdarzeń (Event Grid lub CloudEvents) możesz teraz uzyskać dostęp do podstawowych informacji o zdarzeniu na kopercie (właściwości, które są obecne dla wszystkich zdarzeń, takich jak czas zdarzenia i typ).
  • Deserializuj dane zdarzenia. Biorąc pod uwagę element EventGridEvent lub CloudEvent, użytkownik może próbować uzyskać dostęp do ładunku zdarzenia lub danych, deserializacji do określonego typu. W tym momencie można podać niestandardowy serializator, aby poprawnie zdekodować dane.

Bezpieczeństwo wątkowe

Gwarantujemy, że wszystkie metody wystąpienia klienta są bezpieczne wątkowo i niezależne od siebie (wytyczne). Dzięki temu zalecenie ponownego instalowania wystąpień klienta jest zawsze bezpieczne, nawet w wątkach.

Dodatkowe pojęcia

Opcje | klienta Uzyskiwanie dostępu do odpowiedzi | Długotrwałe operacje | Obsługa błędów | Diagnostyka | Szyderczy | Okres istnienia klienta

Przykłady

Publikowanie zdarzeń usługi Event Grid w temacie usługi Event Grid

Publikowanie zdarzeń w usłudze Event Grid jest wykonywane przy użyciu polecenia EventGridPublisherClient. Użyj podanej SendEvent/SendEventAsync metody, aby opublikować pojedyncze zdarzenie w temacie.

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

Aby opublikować partię zdarzeń, użyj SendEvents/SendEventsAsync metody .

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

Publikowanie rozwiązania CloudEvents w temacie usługi Event Grid

Publikowanie zdarzeń w usłudze Event Grid jest wykonywane przy użyciu polecenia EventGridPublisherClient. Użyj podanej SendEvents/SendEventsAsync metody, aby opublikować zdarzenia w temacie.

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

Publikowanie zdarzeń usługi Event Grid w domenie usługi Event Grid

Domena zdarzeń to narzędzie do zarządzania dla dużej liczby tematów usługi Event Grid związanych z tą samą aplikacją. Można o tym myśleć jako meta-temat, który może zawierać tysiące poszczególnych tematów. Podczas tworzenia domeny zdarzeń otrzymujesz punkt końcowy publikowania podobny do utworzonego tematu w usłudze Event Grid.

Aby opublikować zdarzenia w dowolnym temacie w domenie zdarzeń, wypchnij zdarzenia do punktu końcowego domeny w taki sam sposób, jak w przypadku tematu niestandardowego. Jedyną różnicą jest to, że musisz określić temat, do którego ma zostać dostarczone zdarzenie.

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

W przypadku wysyłania rozwiązania CloudEvents źródło CloudEvent jest używane jako temat domeny:

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

Odbieranie i deserializacji zdarzeń

Istnieje kilka różnych usług platformy Azure, które działają jako programy obsługi zdarzeń.

Uwaga: jeśli używasz elementów webhook do dostarczania zdarzeń schematu usługi Event Grid, usługa Event Grid wymaga potwierdzenia własności punktu końcowego elementu webhook przed rozpoczęciem dostarczania zdarzeń do tego punktu końcowego. W momencie tworzenia subskrypcji zdarzeń usługa Event Grid wysyła zdarzenie weryfikacji subskrypcji do punktu końcowego, jak pokazano poniżej. Dowiedz się więcej na temat kończenia uzgadniania tutaj: dostarczanie zdarzeń elementu webhook. W przypadku schematu CloudEvents usługa weryfikuje połączenie przy użyciu metody opcji HTTP. Dowiedz się więcej tutaj: Weryfikacja rozwiązania CloudEvents.

Po dostarczeniu zdarzeń do procedury obsługi zdarzeń możemy deserializacji ładunku JSON do listy zdarzeń.

Za pomocą polecenia EventGridEvent:

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

Za pomocą polecenia CloudEvent:

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

Deserializowanie danych zdarzeń

W tym miejscu można uzyskać dostęp do danych zdarzenia przez deserializacji do określonego typu przez wywołanie ToObjectFromJson<T>()Data właściwości . W celu deserializacji do poprawnego typu EventType właściwość (Type dla cloudEvents) pomaga odróżnić różne zdarzenia. Niestandardowe dane zdarzenia powinny zostać zdeserializowane przy użyciu metody ToObjectFromJson<T>()ogólnej . Istnieje również metoda ToObject<T>() rozszerzenia, która akceptuje niestandardowe ObjectSerializer deserializowanie danych zdarzenia.

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

Przy użyciu polecenia TryGetSystemEventData():

Jeśli oczekuje się głównie zdarzeń systemowych, może być czystsze, aby włączyć i TryGetSystemEventData() użyć dopasowania wzorca do działania na poszczególnych zdarzeniach. Jeśli zdarzenie nie jest zdarzeniem systemowym, metoda zwróci wartość false, a parametr wyjściowy będzie mieć wartość null.

Jako zastrzeżenie, jeśli używasz niestandardowego typu zdarzenia z wartością EventType, która później zostanie dodana jako zdarzenie systemowe przez usługę i zestaw SDK, wartość TryGetSystemEventData zwracana przez usługę zmieni się z false na true. Może się to pojawić w przypadku wcześniejszego tworzenia własnych zdarzeń niestandardowych dla zdarzeń, które są już wysyłane przez usługę, ale nie zostały jeszcze dodane do zestawu SDK. W takim przypadku lepiej użyć metody ogólnej ToObjectFromJson<T> we Data właściwości , aby przepływ kodu nie zmieniał się automatycznie po uaktualnieniu (oczywiście nadal warto zmodyfikować kod tak, aby używał nowo wydanego modelu zdarzeń systemowych, a nie modelu niestandardowego).

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

Rozwiązywanie problemów

Odpowiedzi usługi

SendEvents() Metoda zwraca kod odpowiedzi HTTP z usługi. Element RequestFailedException jest zgłaszany jako odpowiedź usługi dla wszystkich niepomyślnych żądań. Wyjątek zawiera informacje o kodzie odpowiedzi zwróconym z usługi.

Deserializowanie danych zdarzenia

  • Jeśli dane zdarzenia nie są prawidłowe w formacie JSON, JsonException podczas wywoływania metody Parse lub ParseMany.
  • Jeśli schemat zdarzenia nie odpowiada typowi deserializacji (np. wywołaniu CloudEvent.Parse zdarzenia EventGridSchema), ArgumentException zgłaszany jest błąd .
  • Jeśli Parse metoda jest wywoływana na danych zawierających wiele zdarzeń, ArgumentException jest zgłaszana wartość . ParseMany Zamiast tego należy użyć tutaj.

Konfigurowanie rejestrowania konsoli

Możesz również łatwo włączyć rejestrowanie konsoli , jeśli chcesz zagłębić się w żądania, które podejmujesz względem usługi.

Śledzenie rozproszone

Biblioteka usługi Event Grid obsługuje dystrybucję śledzenia z pudełka. Aby stosować się do wskazówek specyfikacji CloudEvents dotyczących dystrybucji śledzenia, biblioteka ustawi traceparent elementy i tracestate na ExtensionAttributes obiekcie CloudEvent po włączeniu śledzenia rozproszonego. Aby dowiedzieć się więcej na temat włączania śledzenia rozproszonego w aplikacji, zapoznaj się z dokumentacją śledzenia rozproszonego zestawu Azure SDK.

Usługa Event Grid na platformie Kubernetes

Ta biblioteka została przetestowana i zweryfikowana na platformie Kubernetes przy użyciu usługi Azure Arc.

Następne kroki

Zobacz więcej https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples tutaj, aby zapoznać się z typowymi zastosowaniami biblioteki klienta usługi Event Grid: Przykłady usługi Event Grid.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Wrażenia