biblioteka klienta Azure Event Hubs dla platformy .NET — wersja 5.8.1

Artykuł
04/03/2023

Azure Event Hubs to wysoce skalowalna usługa publikowania-subskrybowania, która może pozyskiwać miliony zdarzeń na sekundę i przesyłać je strumieniowo do wielu użytkowników. Umożliwia to przetwarzanie i analizowanie ogromnych ilości danych generowanych przez połączone urządzenia i aplikacje. Po zebraniu danych przez usługę Event Hubs można je pobrać, przekształcić i przechowywać za pomocą dowolnego dostawcy analizy w czasie rzeczywistym lub adapterów przetwarzania wsadowego/magazynu. Jeśli chcesz dowiedzieć się więcej na temat Azure Event Hubs, warto przejrzeć artykuł Co to jest usługa Event Hubs.

Biblioteka klienta usługi Azure Event Hubs umożliwia publikowanie oraz korzystanie ze zdarzeń usługi Azure Event Hubs i może być używana w następujących celach:

Emitowanie danych telemetrycznych dotyczących aplikacji na potrzeby analizy biznesowej i diagnostyki.
Publikowanie faktów dotyczących stanu aplikacji, które zainteresowane strony mogą obserwować i wykorzystywać jako wyzwalacza do podjęcia działań.
Obserwacja interesujących operacji i interakcji zachodzących w Twojej firmie lub innym ekosystemie, umożliwiając luźno powiązanym systemom interakcję bez konieczności ich powiązania.
Odbieranie zdarzeń od jednego lub większej liczby wydawców, przekształcanie ich w celu lepszego spełniania potrzeb Twojego ekosystemu, a następnie publikowanie przekształconych zdarzeń w nowym strumieniu, aby odbiorcy mogli je obserwować.

Wprowadzenie

Wymagania wstępne

Subskrypcja platformy Azure: Do korzystania z usług platformy Azure, w tym Azure Event Hubs, potrzebna jest subskrypcja. Jeśli nie masz istniejącego konta platformy Azure, możesz utworzyć konto bezpłatnej wersji próbnej lub skorzystać z korzyści z subskrypcji programu Visual Studio podczas tworzenia konta.
Przestrzeń nazw usługi Event Hubs z centrum zdarzeń: Aby korzystać z Azure Event Hubs, musisz również mieć dostępną przestrzeń nazw i centrum zdarzeń. Jeśli nie znasz tworzenia zasobów platformy Azure, możesz skorzystać z przewodnika krok po kroku dotyczącego tworzenia centrum zdarzeń przy użyciu Azure Portal. W tym miejscu można również znaleźć szczegółowe instrukcje dotyczące tworzenia centrum zdarzeń przy użyciu interfejsu wiersza polecenia platformy Azure, Azure PowerShell lub szablonów usługi Azure Resource Manager (ARM).
C# 8.0: Biblioteka klienta Azure Event Hubs korzysta z nowych funkcji, które zostały wprowadzone w języku C# 8.0. Aby korzystać ze składni języka C# 8.0, zaleca się skompilowanie przy użyciu zestawu .NET Core SDK 3.0 lub nowszego latestz wersją języka .

Użytkownicy programu Visual Studio, którzy chcą w pełni korzystać ze składni języka C# 8.0, muszą korzystać z programu Visual Studio 2019 lub nowszego. Program Visual Studio 2019, w tym bezpłatna wersja Community, można pobrać tutaj. Użytkownicy programu Visual Studio 2017 mogą korzystać ze składni języka C# 8, korzystając z pakietu NuGet Microsoft.Net.Compilers i ustawiając wersję języka, chociaż środowisko edycji może nie być idealne.

Nadal można używać biblioteki z poprzednimi wersjami języka C#, ale trzeba będzie zarządzać asynchronicznymi wyliczalnymi i asynchronicznymi członkami jednorazowymi ręcznie, zamiast korzystać z nowej składni. Nadal możesz kierować dowolną wersję platformy obsługiwaną przez zestaw .NET Core SDK, w tym wcześniejsze wersje platformy .NET Core lub .NET Framework. Aby uzyskać więcej informacji, zobacz: jak określić platformy docelowe.
Ważna uwaga: Aby skompilować lub uruchomić przykłady oraz przykłady bez modyfikacji, konieczne jest użycie języka C# 11.0. Nadal możesz uruchomić przykłady, jeśli zdecydujesz się dostosować je dla innych wersji językowych. Przykład takiego działania jest dostępny w przykładzie: starsze wersje językowe.

Aby szybko utworzyć podstawowy zestaw zasobów usługi Event Hubs na platformie Azure i odebrać dla nich parametry połączenia, możesz wdrożyć nasz przykładowy szablon, klikając:

Instalowanie pakietu

Zainstaluj bibliotekę klienta Azure Event Hubs dla platformy .NET przy użyciu narzędzia NuGet:

dotnet add package Azure.Messaging.EventHubs

Uwierzytelnianie klienta

Aby biblioteka klienta usługi Event Hubs współdziałała z centrum zdarzeń, musi zrozumieć, jak nawiązać z nią połączenie i autoryzować je. Najprostszym sposobem jest użycie parametrów połączenia, które są tworzone automatycznie podczas tworzenia przestrzeni nazw usługi Event Hubs. Jeśli nie znasz parametrów połączenia z usługą Event Hubs, możesz skorzystać z przewodnika krok po kroku, aby uzyskać parametry połączenia usługi Event Hubs.

Kluczowe pojęcia

Klient centrum zdarzeń jest podstawowym interfejsem dla deweloperów korzystających z biblioteki klienta usługi Event Hubs. Istnieje kilka różnych klientów usługi Event Hub, z których każda jest przeznaczona do określonego użycia usługi Event Hubs, takich jak publikowanie lub używanie zdarzeń.
Producent centrum zdarzeń jest typem klienta, który służy jako źródło danych telemetrycznych, informacji diagnostycznych, dzienników użycia lub innych danych dziennika, w ramach rozwiązania urządzenia osadzonego, aplikacji urządzenia przenośnego, tytułu gry uruchomionego w konsoli lub innym urządzeniu, niektórych klienta lub serwera opartego na rozwiązaniu biznesowym lub witrynie internetowej.
Odbiorca centrum zdarzeń to typ klienta, który odczytuje informacje z centrum zdarzeń i umożliwia jego przetwarzanie. Przetwarzanie może obejmować agregację, złożone obliczenia i filtrowanie. Przetwarzanie może również obejmować dystrybucję lub przechowywanie informacji w sposób pierwotny lub przekształcony. Odbiorcy usługi Event Hub są często niezawodnymi i skalowalnymi składnikami infrastruktury platformy z wbudowanymi funkcjami analitycznymi, takimi jak Azure Stream Analytics, Apache Spark lub Apache Storm.
Partycja to uporządkowana sekwencja zdarzeń przechowywanych w centrum zdarzeń. Partycje to sposób organizacji danych skojarzonych z równoległością wymaganą przez odbiorców zdarzeń. Azure Event Hubs zapewnia przesyłanie strumieniowe komunikatów za pośrednictwem partycjonowanego wzorca konsumenta, w którym każdy odbiorca odczytuje tylko określony podzbiór lub partycję strumienia komunikatów. Po nadejściu nowszych zdarzeń są one dodawane na końcu sekwencji. Liczba partycji jest określana w momencie utworzenia centrum zdarzeń i nie można jej zmienić.
Grupa odbiorców jest widokiem całego centrum zdarzeń. Grupy odbiorców umożliwiają wielu aplikacjom korzystającym z każdego z nich oddzielny widok strumienia zdarzeń oraz odczytywanie strumienia niezależnie we własnym tempie i na własną rękę. W partycji na grupę odbiorców może znajdować się co najwyżej 5 jednoczesnych czytników; jednak zaleca się, aby dla danej partycji i grupy odbiorców istniał tylko jeden aktywny odbiorca. Każdy aktywny czytnik odbiera wszystkie zdarzenia z partycji; Jeśli na tej samej partycji znajduje się wiele czytników, otrzymają one zduplikowane zdarzenia.

Aby uzyskać więcej pojęć i głębszą dyskusję, zobacz: Event Hubs Features (Funkcje usługi Event Hubs).

Okres istnienia klienta

Każdy z typów klientów usługi Event Hubs jest bezpieczny do buforowania i używany jako pojedynczy element w okresie istnienia aplikacji, co jest najlepszym rozwiązaniem w przypadku publikowania lub regularnego odczytywania zdarzeń. Klienci są odpowiedzialni za efektywne zarządzanie siecią, procesorem i pamięcią, pracując nad utrzymaniem niskiego użycia w okresach braku aktywności. Wywołanie metody CloseAsync lub DisposeAsync na kliencie jest wymagane, aby upewnić się, że zasoby sieciowe i inne niezarządzane obiekty są prawidłowo czyszczone.

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 obsługi wystąpień klienta jest zawsze bezpieczne, nawet w wątkach.

Typy modeli danych, takie jak EventData i EventDataBatch , nie są bezpieczne wątkowo. Nie powinny być współużytkowane przez wątki ani używane współbieżnie z metodami klienta.

Dodatkowe pojęcia

Opcje | klienta Obsługa błędów | Diagnostyka | Szyderczy

Przykłady

Inspekcja centrum zdarzeń

Wiele operacji centrum zdarzeń odbywa się w zakresie określonej partycji. Ponieważ partycje są własnością centrum zdarzeń, ich nazwy są przypisywane w momencie tworzenia. Aby zrozumieć, jakie partycje są dostępne, należy wykonać zapytanie względem centrum zdarzeń przy użyciu jednego z klientów centrum zdarzeń. Na potrzeby ilustracji przedstawiono metodę w EventHubProducerClient tych przykładach, ale koncepcja i formularz są wspólne dla klientów.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    string[] partitionIds = await producer.GetPartitionIdsAsync();
}

Publikowanie zdarzeń w centrum zdarzeń

Aby publikować zdarzenia, należy utworzyć element EventHubProducerClient. Producenci publikują zdarzenia w partiach i mogą zażądać określonej partycji lub zezwolić usłudze Event Hubs na podjęcie decyzji o tym, które zdarzenia partycji mają być publikowane. Zaleca się używanie automatycznego routingu, gdy publikowanie zdarzeń musi być wysoce dostępne lub gdy dane zdarzenia powinny być dystrybuowane równomiernie między partycjami. W naszym przykładzie skorzystamy z automatycznego routingu.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

await using (var producer = new EventHubProducerClient(connectionString, eventHubName))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

Odczytywanie zdarzeń z centrum zdarzeń

Aby odczytywać zdarzenia z centrum zdarzeń, należy utworzyć dla EventHubConsumerClient danej grupy odbiorców. Po utworzeniu centrum zdarzeń udostępnia on domyślną grupę odbiorców, która może służyć do rozpoczęcia eksplorowania usługi Event Hubs. W naszym przykładzie skoncentrujemy się na odczytywaniu wszystkich zdarzeń, które zostały opublikowane w centrum zdarzeń przy użyciu iteratora.

Uwaga: Należy pamiętać, że takie podejście do używania ma na celu poprawę środowiska eksplorowania biblioteki klienta usługi Event Hubs i tworzenia prototypów. Zaleca się, aby nie były używane w scenariuszach produkcyjnych. Do użytku produkcyjnego zalecamy użycie klienta procesora zdarzeń, ponieważ zapewnia bardziej niezawodne i wydajne środowisko.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsAsync(cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the Event Hub.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Odczytywanie zdarzeń z partycji centrum zdarzeń

Aby odczytywać zdarzenia dla partycji centrum zdarzeń, należy utworzyć dla EventHubConsumerClient danej grupy odbiorców. Po utworzeniu centrum zdarzeń udostępnia on domyślną grupę odbiorców, która może służyć do rozpoczęcia eksplorowania usługi Event Hubs. Aby odczytać z określonej partycji, odbiorca będzie również musiał określić miejsce w strumieniu zdarzeń, aby rozpocząć odbieranie zdarzeń; W naszym przykładzie skoncentrujemy się na odczytywaniu wszystkich opublikowanych zdarzeń dla pierwszej partycji centrum zdarzeń.

var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";

string consumerGroup = EventHubConsumerClient.DefaultConsumerGroupName;

await using (var consumer = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName))
{
    EventPosition startingPosition = EventPosition.Earliest;
    string partitionId = (await consumer.GetPartitionIdsAsync()).First();

    using var cancellationSource = new CancellationTokenSource();
    cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

    await foreach (PartitionEvent receivedEvent in consumer.ReadEventsFromPartitionAsync(partitionId, startingPosition, cancellationSource.Token))
    {
        // At this point, the loop will wait for events to be available in the partition.  When an event
        // is available, the loop will iterate with the event that was received.  Because we did not
        // specify a maximum wait time, the loop will wait forever unless cancellation is requested using
        // the cancellation token.
    }
}

Przetwarzanie zdarzeń przy użyciu klienta procesora zdarzeń

W większości scenariuszy produkcyjnych zaleca się użycie klienta procesora zdarzeń do odczytywania i przetwarzania zdarzeń. Procesor ma zapewnić niezawodne środowisko przetwarzania zdarzeń we wszystkich partycjach centrum zdarzeń w wydajny i odporny na uszkodzenia sposób, zapewniając jednocześnie sposób utrwalania stanu. Klienci procesora zdarzeń mogą również współpracować w kontekście grupy odbiorców dla danego centrum zdarzeń, gdzie będą automatycznie zarządzać dystrybucją i równoważeniem pracy, ponieważ wystąpienia staną się dostępne lub niedostępne dla grupy.

EventProcessorClient Ponieważ obiekt ma zależność od obiektów blob usługi Azure Storage na potrzeby trwałości jego stanu, należy podać BlobContainerClient dla procesora, który został skonfigurowany dla konta magazynu i kontenera, który powinien być używany.

var cancellationSource = new CancellationTokenSource();
cancellationSource.CancelAfter(TimeSpan.FromSeconds(45));

var storageConnectionString = "<< CONNECTION STRING FOR THE STORAGE ACCOUNT >>";
var blobContainerName = "<< NAME OF THE BLOB CONTAINER >>";

var eventHubsConnectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>";

Task processEventHandler(ProcessEventArgs eventArgs) => Task.CompletedTask;
Task processErrorHandler(ProcessErrorEventArgs eventArgs) => Task.CompletedTask;

var storageClient = new BlobContainerClient(storageConnectionString, blobContainerName);
var processor = new EventProcessorClient(storageClient, consumerGroup, eventHubsConnectionString, eventHubName);

processor.ProcessEventAsync += processEventHandler;
processor.ProcessErrorAsync += processErrorHandler;

await processor.StartProcessingAsync();

try
{
    // The processor performs its work in the background; block until cancellation
    // to allow processing to take place.

    await Task.Delay(Timeout.Infinite, cancellationSource.Token);
}
catch (TaskCanceledException)
{
    // This is expected when the delay is canceled.
}

try
{
    await processor.StopProcessingAsync();
}
finally
{
    // To prevent leaks, the handlers should be removed when processing is complete.

    processor.ProcessEventAsync -= processEventHandler;
    processor.ProcessErrorAsync -= processErrorHandler;
}

Więcej szczegółów można znaleźć w pliku README klienta procesora zdarzeń i towarzyszących przykładach.

Używanie jednostki usługi Active Directory z klientami centrum zdarzeń

Biblioteka tożsamości platformy Azure zapewnia obsługę uwierzytelniania usługi Azure Active Directory, która może być używana dla bibliotek klienta platformy Azure, w tym usługi Event Hubs.

Aby korzystać z jednostki usługi Active Directory, podczas tworzenia klienta usługi Event Hubs jest określane jedno z dostępnych poświadczeń z Azure.Identity biblioteki. Ponadto w pełni kwalifikowana przestrzeń nazw usługi Event Hubs i nazwa żądanego centrum zdarzeń są dostarczane zamiast parametrów połączenia usługi Event Hubs. Na ilustracji pokazano w EventHubProducerClient tych przykładach, ale koncepcja i forma są wspólne dla klientów.

var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net) >>";
var eventHubName = "<< NAME OF THE EVENT HUB >>";
var credential = new DefaultAzureCredential();

await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential))
{
    using EventDataBatch eventBatch = await producer.CreateBatchAsync();
    eventBatch.TryAdd(new EventData(new BinaryData("First")));
    eventBatch.TryAdd(new EventData(new BinaryData("Second")));

    await producer.SendAsync(eventBatch);
}

W przypadku korzystania z usługi Azure Active Directory podmiot zabezpieczeń musi mieć przypisaną rolę, która umożliwia dostęp do usługi Event Hubs, takiej jak Azure Event Hubs Data Owner rola. Aby uzyskać więcej informacji na temat używania autoryzacji usługi Azure Active Directory z usługą Event Hubs, zapoznaj się z skojarzona dokumentacja.

Rozwiązywanie problemów

Aby uzyskać szczegółowe informacje dotyczące rozwiązywania problemów, zapoznaj się z przewodnikiem rozwiązywania problemów z usługą Event Hubs.

Rejestrowanie i diagnostyka

Biblioteka klienta usługi Event Hubs jest w pełni instrumentowana do rejestrowania informacji na różnych poziomach szczegółów przy użyciu platformy .NET EventSource do emitowania informacji. Rejestrowanie jest wykonywane dla każdej operacji i jest zgodne ze wzorcem oznaczania punktu początkowego operacji, ukończenia i napotkanych wyjątków. Dodatkowe informacje, które mogą oferować szczegółowe informacje, są również rejestrowane w kontekście skojarzonej operacji.

Dzienniki klienta usługi Event Hubs są dostępne dla każdego EventListener , decydując się na źródło o nazwie "Azure-Messaging-EventHubs" lub decydując się na wszystkie źródła, które mają cechę "AzureEventSource". Aby ułatwić przechwytywanie dzienników z bibliotek klienckich platformy Azure, Azure.Core biblioteka używana przez usługę Event Hubs oferuje element AzureEventSourceListener. Więcej informacji można znaleźć w temacie Przechwytywanie dzienników usługi Event Hubs przy użyciu elementu AzureEventSourceListener.

Biblioteka klienta usługi Event Hubs jest również instrumentowana do śledzenia rozproszonego przy użyciu usługi Application Insights lub OpenTelemetry. Więcej informacji można znaleźć w przykładzie Diagnostyka Azure.Core.

Następne kroki

Poza omówionymi scenariuszami wprowadzającymi biblioteka klienta Azure Event Hubs oferuje obsługę dodatkowych scenariuszy, które ułatwiają korzystanie z pełnego zestawu funkcji usługi Azure Event Hubs. Aby ułatwić zapoznanie się z niektórymi z tych scenariuszy, biblioteka klienta usługi Event Hubs oferuje projekt przykładów, który służy jako ilustracja dla typowych scenariuszy. Aby uzyskać szczegółowe informacje, zobacz przykłady README .

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.

Aby uzyskać więcej informacji, zobacz nasz przewodnik dotyczący współtworzenia .

Wrażenia

Udostępnij za pośrednictwem