Rychlý start: Odesílání událostí a příjem událostí ze služby Azure Event Hubs pomocí .NET
V tomto rychlém startu se dozvíte, jak odesílat události do centra událostí a pak tyto události přijímat z centra událostí pomocí knihovny Azure.Messaging.EventHubs .NET.
Poznámka:
Rychlé starty jsou určené k rychlému zprovoznění služby. Pokud už službu znáte, možná budete chtít zobrazit ukázky .NET pro službu Event Hubs v našem úložišti sady .NET SDK na GitHubu: Ukázky služby Event Hubs na GitHubu, ukázky procesoru událostí na GitHubu.
Požadavky
Pokud se službou Azure Event Hubs teprve začínáte, podívejte se na přehled služby Event Hubs, než projdete tímto rychlým startem.
K dokončení tohoto rychlého startu potřebujete následující požadavky:
- Předplatné Microsoft Azure. Pokud chcete používat služby Azure, včetně služby Azure Event Hubs, potřebujete předplatné. Pokud nemáte existující účet Azure, můžete si zaregistrovat bezplatnou zkušební verzi nebo využít výhody předplatitele MSDN při vytváření účtu.
- Microsoft Visual Studio 2022. Klientská knihovna Azure Event Hubs využívá nové funkce, které byly zavedeny v jazyce C# 8.0. Knihovnu můžete stále používat s předchozími jazykovými verzemi jazyka C#, ale nová syntaxe není dostupná. Pokud chcete použít úplnou syntaxi, doporučujeme zkompilovat se sadou .NET Core SDK 3.0 nebo vyšší a jazykovou verzí nastavenou na
latest
. Pokud používáte Visual Studio, verze před sadou Visual Studio 2022 nejsou kompatibilní s nástroji potřebnými k sestavení projektů C# 8.0. Visual Studio 2022, včetně bezplatné edice Community, si můžete stáhnout zde. - Vytvořte obor názvů služby Event Hubs a centrum událostí. Prvním krokem je vytvoření oboru názvů služby Event Hubs a centra událostí v oboru názvů pomocí webu Azure Portal. Pak získejte přihlašovací údaje pro správu, které vaše aplikace potřebuje ke komunikaci s centrem událostí. Pokud chcete vytvořit obor názvů a centrum událostí, přečtěte si článek Rychlý start: Vytvoření centra událostí pomocí webu Azure Portal.
Ověření aplikace v Azure
Tento rychlý start ukazuje dva způsoby připojení ke službě Azure Event Hubs:
- Bez hesla (ověřování Microsoft Entra)
- Connection string
První možnost ukazuje, jak se pomocí objektu zabezpečení v Azure Active Directory a řízení přístupu na základě role (RBAC) připojit k oboru názvů služby Event Hubs. Nemusíte se starat o pevně zakódované připojovací řetězec v kódu nebo v konfiguračním souboru nebo v zabezpečeném úložišti, jako je Azure Key Vault.
Druhá možnost ukazuje, jak se pomocí připojovací řetězec připojit k oboru názvů služby Event Hubs. Pokud s Azure začínáte, můžete najít připojovací řetězec možnost, která se snadněji sleduje. Doporučujeme používat možnost bez hesla v reálných aplikacích a produkčních prostředích. Další informace najdete v tématu Ověřování a autorizace. Další informace o ověřování bez hesla najdete na stránce přehledu.
Přiřazení rolí uživateli Microsoft Entra
Při místním vývoji se ujistěte, že uživatelský účet, který se připojuje ke službě Azure Event Hubs, má správná oprávnění. K odesílání a přijímání zpráv budete potřebovat roli vlastníka dat služby Azure Event Hubs. K přiřazení této role budete potřebovat roli Správce uživatelských přístupů nebo jinou roli, která tuto Microsoft.Authorization/roleAssignments/write
akci zahrnuje. Role Azure RBAC můžete uživateli přiřadit pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu. Další informace o dostupných oborech pro přiřazení rolí najdete na stránce přehledu oboru.
Následující příklad přiřadí roli k vašemu uživatelskému Azure Event Hubs Data Owner
účtu, který poskytuje úplný přístup k prostředkům služby Azure Event Hubs. V reálném scénáři postupujte podle principu nejnižšího oprávnění , aby uživatelům poskytla pouze minimální oprávnění potřebná pro bezpečnější produkční prostředí.
Předdefinované role Azure pro Azure Event Hubs
Pro Službu Azure Event Hubs je správa oborů názvů a všech souvisejících prostředků prostřednictvím webu Azure Portal a rozhraní API pro správu prostředků Azure již chráněno pomocí modelu Azure RBAC. Azure poskytuje následující předdefinované role Azure pro autorizaci přístupu k oboru názvů služby Event Hubs:
- Vlastník dat služby Azure Event Hubs: Umožňuje přístup k datům k oboru názvů služby Event Hubs a jeho entitám (fronty, témata, odběry a filtry).
- Odesílatel dat služby Azure Event Hubs: Pomocí této role dáte odesílateli přístup k oboru názvů služby Event Hubs a jeho entitám.
- Příjemce dat služby Azure Event Hubs: Pomocí této role dejte příjemci přístup k oboru názvů služby Event Hubs a jeho entitám.
Pokud chcete vytvořit vlastní roli, přečtěte si téma Práva potřebná pro operace služby Event Hubs.
Důležité
Ve většině případů bude trvat minutu nebo dvě, než se přiřazení role rozšíří v Azure. Ve výjimečných případech může trvat až osm minut. Pokud při prvním spuštění kódu dojde k chybám ověřování, chvíli počkejte a zkuste to znovu.
Na webu Azure Portal vyhledejte obor názvů služby Event Hubs pomocí hlavního panelu hledání nebo levé navigace.
Na stránce přehledu vyberte v nabídce vlevo řízení přístupu (IAM ).
Na stránce Řízení přístupu (IAM) vyberte kartu Přiřazení rolí.
V horní nabídce vyberte + Přidat a potom přidejte přiřazení role z výsledné rozevírací nabídky.
Pomocí vyhledávacího pole vyfiltrujte výsledky podle požadované role. V tomto příkladu vyhledejte
Azure Event Hubs Data Owner
a vyberte odpovídající výsledek. Pak zvolte Další.V části Přiřadit přístup vyberte Uživatel, skupina nebo instanční objekt a pak zvolte + Vybrat členy.
V dialogovém okně vyhledejte své uživatelské jméno Microsoft Entra (obvykle vaše user@domain e-mailová adresa) a pak v dolní části dialogového okna zvolte Vybrat .
Vyberte Zkontrolovat a přiřadit přejděte na poslední stránku a pak proces dokončete opětovnou kontrolou a přiřazením .
Spuštění sady Visual Studio a přihlášení k Azure
Přístup k oboru názvů služby Service Bus můžete autorizovat pomocí následujícího postupu:
Spusťte Visual Studio. Pokud se zobrazí okno Začínáme , vyberte v pravém podokně odkaz Pokračovat bez kódu .
V pravém horním rohu sady Visual Studio vyberte tlačítko Přihlásit se.
Přihlaste se pomocí účtu Microsoft Entra, kterému jste přiřadili roli dříve.
Odesílání událostí do centra událostí
V této části se dozvíte, jak vytvořit konzolovou aplikaci .NET Core pro odesílání událostí do centra událostí, které jste vytvořili.
Vytvoření konzolové aplikace
Pokud už máte sadu Visual Studio 2022 otevřenou, v nabídce vyberte Soubor , vyberte Nový a pak vyberte Projekt. V opačném případě spusťte Visual Studio 2022 a pokud se zobrazí místní okno, vyberte Vytvořit nový projekt .
V dialogovém okně Vytvořit nový projekt proveďte následující kroky: Pokud toto dialogové okno nevidíte, vyberte v nabídce Soubor , vyberte Nový a pak vyberte Projekt.
Vyberte jazyk C# pro programovací jazyk.
Vyberte konzolu pro typ aplikace.
V seznamu výsledků vyberte konzolovou aplikaci .
Pak vyberte Další.
Jako název projektu zadejte EventHubsSender, název řešení EventHubsQuickStart a pak vyberte Další.
Na stránce Další informace vyberte Vytvořit.
Přidání balíčků NuGet do projektu
V nabídce vyberte Nástroje>NuGet Správce balíčků> Správce balíčků Konzola.
Spuštěním následujících příkazů nainstalujte balíčky NuGet Azure.Messaging.EventHubs a Azure.Identity . Stisknutím klávesy ENTER spusťte druhý příkaz.
Install-Package Azure.Messaging.EventHubs Install-Package Azure.Identity
Napsání kódu pro odesílání událostí do centra událostí
Nahraďte existující kód v
Program.cs
souboru následujícím vzorovým kódem. Potom nahraďte<EVENT_HUB_NAMESPACE>
a<HUB_NAME>
zástupné hodnotyEventHubProducerClient
parametrů názvy oboru názvů služby Event Hubs a centra událostí. Například:"spehubns0309.servicebus.windows.net"
a"spehub"
Tady jsou důležité kroky z kódu:
- Vytvoří objekt EventHubProducerClient pomocí oboru názvů a názvu centra událostí.
- Vyvolá CreateBatchAsync metoda na EventHubProducerClient objekt vytvořit EventDataBatch objektu.
- Přidejte události do dávky pomocí metody EventDataBatch.TryAdd .
- Odešle dávku zpráv do centra událostí pomocí metody EventHubProducerClient.SendAsync .
using Azure.Identity; using Azure.Messaging.EventHubs; using Azure.Messaging.EventHubs.Producer; using System.Text; // number of events to be sent to the event hub int numOfEvents = 3; // The Event Hubs client types are safe to cache and use as a singleton for the lifetime // of the application, which is best practice when events are being published or read regularly. // TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values EventHubProducerClient producerClient = new EventHubProducerClient( "<EVENT_HUB_NAMESPACE>.servicebus.windows.net", "<HUB_NAME>", new DefaultAzureCredential()); // Create a batch of events using EventDataBatch eventBatch = await producerClient.CreateBatchAsync(); for (int i = 1; i <= numOfEvents; i++) { if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}")))) { // if it is too large for the batch throw new Exception($"Event {i} is too large for the batch and cannot be sent."); } } try { // Use the producer client to send the batch of events to the event hub await producerClient.SendAsync(eventBatch); Console.WriteLine($"A batch of {numOfEvents} events has been published."); Console.ReadLine(); } finally { await producerClient.DisposeAsync(); }
Sestavte projekt a ujistěte se, že nedošlo k žádným chybám.
Spusťte program a počkejte na potvrzovací zprávu.
A batch of 3 events has been published.
Poznámka:
Pokud se při použití ověřování Microsoft Entra zobrazí chyba InvalidIssuer: Vystavitel tokenu je neplatný, může to být proto, že se používá nesprávné ID tenanta Entra. V kódu nahraďte new DefaultAzureCredential()' novým defaultAzureCredential(new DefaultAzureCredentialOptions {TenantId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"}) pro explictly zadat ID tenanta Entra.
Důležité
Pokud používáte ověřování bez hesla (řízení přístupu na základě role v Azure Active Directory), vyberte Nástroje a pak vyberte Možnosti. V okně Možnosti rozbalte ověřování služby Azure a vyberte Výběr účtu. Ověřte, že používáte účet přidaný do role Vlastník dat služby Azure Event Hubs v oboru názvů služby Event Hubs.
Na stránce Obor názvů služby Event Hubs na webu Azure Portal se v grafu Zprávy zobrazí tři příchozí zprávy. Aktualizujte stránku, aby se graf v případě potřeby aktualizoval. Může trvat několik sekund, než se zobrazí, že zprávy byly přijaty.
Poznámka:
Úplný zdrojový kód s dalšími informačními komentáři najdete v tomto souboru na GitHubu.
Příjem událostí z centra událostí
Tato část ukazuje, jak napsat konzolovou aplikaci .NET Core, která přijímá události z centra událostí pomocí procesoru událostí. Procesor událostí zjednodušuje příjem událostí z center událostí.
Vytvoření účtu úložiště Azure a kontejneru objektů blob
V tomto rychlém startu použijete Azure Storage jako úložiště kontrolních bodů. Podle těchto kroků vytvořte účet služby Azure Storage.
- Vytvoření účtu služby Azure Storage
- Vytvoření kontejneru objektů blob
- Ověřte se v kontejneru objektů blob pomocí ověřování Microsoft Entra ID (bez hesla) nebo připojovací řetězec do oboru názvů.
Při používání služby Azure Blob Storage jako úložiště kontrolních bodů postupujte podle těchto doporučení:
- Pro každou skupinu příjemců použijte samostatný kontejner. Můžete použít stejný účet úložiště, ale pro každou skupinu použít jeden kontejner.
- Nepoužívejte kontejner pro nic jiného a nepoužívejte účet úložiště pro nic jiného.
- Účet úložiště by měl být ve stejné oblasti jako nasazená aplikace. Pokud je aplikace místní, zkuste zvolit nejbližší možnou oblast.
Na stránce účtu úložiště na webu Azure Portal v části Blob Service se ujistěte, že jsou zakázaná následující nastavení.
- Hierarchický obor názvů
- Obnovitelné odstranění objektu blob
- Vytváření verzí
Při místním vývoji se ujistěte, že uživatelský účet, který přistupuje k datům objektů blob, má správná oprávnění. K čtení a zápisu dat objektů blob budete potřebovat Přispěvatel dat objektů blob služby Storage. Abyste mohli tuto roli přiřadit sami sobě, musíte mít přiřazenou roli Správce uživatelských přístupů nebo jinou roli, která zahrnuje akci Microsoft.Authorization/roleAssignments/write . Role Azure RBAC můžete uživateli přiřadit pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu. Další informace o dostupných oborech pro přiřazení rolí najdete na stránce přehledu oboru.
V tomto scénáři přiřadíte oprávnění k vašemu uživatelskému účtu s vymezeným oborem účtu úložiště, abyste postupovali podle zásady nejnižších oprávnění. Tento postup poskytuje uživatelům jenom minimální potřebná oprávnění a vytváří bezpečnější produkční prostředí.
Následující příklad přiřadí roli Přispěvatel dat v objektech blob služby Storage k vašemu uživatelskému účtu, který poskytuje přístup ke čtení i zápisu k datům objektů blob v účtu úložiště.
Důležité
Ve většině případů bude trvat minutu nebo dvě, než se přiřazení role rozšíří v Azure, ale ve výjimečných případech může trvat až osm minut. Pokud při prvním spuštění kódu dojde k chybám ověřování, chvíli počkejte a zkuste to znovu.
Na webu Azure Portal vyhledejte svůj účet úložiště pomocí hlavního panelu hledání nebo levé navigace.
Na stránce přehledu účtu úložiště v nabídce vlevo vyberte Řízení přístupu (IAM ).
Na stránce Řízení přístupu (IAM) vyberte kartu Přiřazení rolí.
V horní nabídce vyberte + Přidat a potom přidejte přiřazení role z výsledné rozevírací nabídky.
Pomocí vyhledávacího pole vyfiltrujte výsledky podle požadované role. V tomto příkladu vyhledejte Přispěvatel dat objektů blob služby Storage a vyberte odpovídající výsledek a pak zvolte Další.
V části Přiřadit přístup vyberte Uživatel, skupina nebo instanční objekt a pak zvolte + Vybrat členy.
V dialogovém okně vyhledejte své uživatelské jméno Microsoft Entra (obvykle vaše user@domain e-mailová adresa) a pak v dolní části dialogového okna zvolte Vybrat .
Vyberte Zkontrolovat a přiřadit přejděte na poslední stránku a pak proces dokončete opětovnou kontrolou a přiřazením .
Vytvoření projektu pro příjemce
- V okně Průzkumník řešení klikněte pravým tlačítkem na řešení EventHubQuickStart, přejděte na příkaz Přidat a vyberte Nový projekt.
- Vyberte Konzolová aplikace a vyberte Další.
- Jako název projektu zadejte EventHubsReceiver a vyberte Vytvořit.
- V okně Průzkumník řešení klikněte pravým tlačítkem na EventHubsReceiver a vyberte Nastavit jako spouštěný projekt.
Přidání balíčků NuGet do projektu
V nabídce vyberte Nástroje>NuGet Správce balíčků> Správce balíčků Konzola.
V okně konzoly Správce balíčků ověřte, že je pro výchozí projekt vybraná možnost EventHubsReceiver. Pokud ne, pomocí rozevíracího seznamu vyberte EventHubsReceiver.
Spuštěním následujícího příkazu nainstalujte balíčky NuGet Azure.Messaging.EventHubs a Azure.Identity . Stisknutím klávesy ENTER spusťte poslední příkaz.
Install-Package Azure.Messaging.EventHubs Install-Package Azure.Messaging.EventHubs.Processor Install-Package Azure.Identity
Aktualizace kódu
Obsah souboru Program.cs nahraďte tímto kódem:
Nahraďte existující kód v
Program.cs
souboru následujícím vzorovým kódem. Potom nahraďte<STORAGE_ACCOUNT_NAME>
a<BLOB_CONTAINER_NAME>
zástupné hodnoty identifikátoruBlobContainerClient
URI. Nahraďte také hodnoty zástupných<EVENT_HUB_NAMESPACE>
<HUB_NAME>
EventProcessorClient
symbolů.Tady jsou důležité kroky z kódu:
- Vytvoří objekt EventProcessorClient pomocí oboru názvů Event Hubs a názvu centra událostí. Musíte vytvořit objekt BlobContainerClient pro kontejner v úložišti Azure, který jste vytvořili dříve.
- Určuje obslužné rutiny pro ProcessEventAsync a ProcessErrorAsync události EventProcessorClient objektu.
- Spustí zpracování událostí vyvoláním StartProcessingAsync u objektu EventProcessorClient .
- Zastaví zpracování událostí po 30 sekundách vyvoláním StopProcessingAsync u objektu EventProcessorClient .
using Azure.Identity; using Azure.Messaging.EventHubs; using Azure.Messaging.EventHubs.Consumer; using Azure.Messaging.EventHubs.Processor; using Azure.Storage.Blobs; using System.Text; // Create a blob container client that the event processor will use // TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTAINER_NAME> with actual names BlobContainerClient storageClient = new BlobContainerClient( new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"), new DefaultAzureCredential()); // Create an event processor client to process events in the event hub // TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values var processor = new EventProcessorClient( storageClient, EventHubConsumerClient.DefaultConsumerGroupName, "<EVENT_HUB_NAMESPACE>.servicebus.windows.net", "<HUB_NAME>", new DefaultAzureCredential()); // Register handlers for processing events and handling errors processor.ProcessEventAsync += ProcessEventHandler; processor.ProcessErrorAsync += ProcessErrorHandler; // Start the processing await processor.StartProcessingAsync(); // Wait for 30 seconds for the events to be processed await Task.Delay(TimeSpan.FromSeconds(30)); // Stop the processing await processor.StopProcessingAsync(); Task ProcessEventHandler(ProcessEventArgs eventArgs) { // Write the body of the event to the console window Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray())); Console.ReadLine(); return Task.CompletedTask; } Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs) { // Write details about the error to the console window Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen."); Console.WriteLine(eventArgs.Exception.Message); Console.ReadLine(); return Task.CompletedTask; }
Sestavte projekt a ujistěte se, že nedošlo k žádným chybám.
Poznámka:
Úplný zdrojový kód s dalšími informačními komentáři najdete v tomto souboru na GitHubu.
Spusťte aplikaci příjemce.
Měla by se zobrazit zpráva, že události byly přijaty. Po zobrazení přijaté zprávy události stiskněte enter.
Received event: Event 1 Received event: Event 2 Received event: Event 3
Tyto události jsou tři události, které jste odeslali do centra událostí dříve spuštěním programu odesílatele.
Na webu Azure Portal můžete ověřit, že existují tři odchozí zprávy, které služba Event Hubs odeslala přijímající aplikaci. Aktualizujte stránku, aby se graf aktualizoval. Může trvat několik sekund, než se zobrazí, že zprávy byly přijaty.
Ověřování schématu pro aplikace založené na sadě Event Hubs SDK
Službu Azure Schema Registry můžete použít k ověření schématu při streamování dat pomocí aplikací založených na sadě Event Hubs SDK. Azure Schema Registry služby Event Hubs poskytuje centralizované úložiště pro správu schémat a můžete bez problémů připojit nové nebo existující aplikace pomocí registru schémat.
Další informace najdete v tématu Ověřování schémat pomocí sady Event Hubs SDK.
Ukázky a referenční informace
Tento rychlý start obsahuje podrobné pokyny k implementaci scénáře odeslání dávky událostí do centra událostí a jejich následnému přijetí. Pokud chcete další ukázky, vyberte následující odkazy.
- Ukázky služby Event Hubs na GitHubu
- Ukázky procesoru událostí na GitHubu
- Ukázka řízení přístupu na základě role v Azure (Azure RBAC)
Kompletní referenční informace k knihovně .NET najdete v naší dokumentaci k sadě SDK.
Vyčištění prostředků
Odstraňte skupinu prostředků, která má obor názvů služby Event Hubs, nebo odstraňte pouze obor názvů, pokud chcete skupinu prostředků zachovat.
Související obsah
Projděte si následující kurz: