Průvodce programováním v rozhraní .NET pro Azure Event Hubs (starší balíček Microsoft. Azure. EventHubs)

Tento článek popisuje některé běžné scénáře psaní kódu pomocí Azure Event Hubs. Předpokládá se předběžná znalost služby Event Hubs. Koncepční přehled služby Event Hubs naleznete v tématu Přehled služby Event Hubs.

Upozornění

Tato příručka je určena pro starý balíček Microsoft. Azure. EventHubs . Doporučujeme, abyste při migraci kódu používali nejnovější balíček Azure. Messaging. EventHubs .

Zdroje událostí

Události se odesílají do centra událostí buď pomocí HTTP POST, nebo prostřednictvím připojení AMQP 1,0. Volba, která se má použít a která závisí na konkrétním scénáři, který se řeší. Připojení protokolu AMQP 1.0 se měří jako zprostředkovaná připojení ve službě Service Bus. Díky tomu, že poskytují trvalý kanál pro zasílání zpráv, jsou vhodnější ve scénářích, kde se počítá s častými vysokými objemy zpráv a vyžaduje se nižší latence.

Pokud používáte rozhraní API spravované pomocí .NET, budou primárními konstrukcemi pro publikování dat ve službě Event Hubs třídy EventHubClient a EventData. EventHubClient poskytuje komunikační kanál AMQP, přes který se události odesílají do centra událostí. Třída EventData představuje událost a slouží k publikování zpráv do centra událostí. Tato třída zahrnuje tělo, některá metadata (vlastnosti) a informace hlavičky (SystemProperties) o události. Do objektu EventData se přidají další vlastnosti, které procházejí centrem událostí.

Začínáme

třídy .net, které podporují Event Hubs, jsou k dispozici v balíčku Microsoft. Azure. EventHubs NuGet. instalaci můžete provést pomocí Visual Studio průzkumníku řešení nebo konzole Správce balíčků v Visual Studio. V tom případě je potřeba zadat v okně konzoly Správce balíčků následující příkaz:

Install-Package Microsoft.Azure.EventHubs

Vytvoření centra událostí

k vytvoření Event Hubs můžete použít Azure Portal, Azure PowerShell nebo rozhraní příkazového řádku Azure. Podrobnosti najdete v tématu Vytvoření oboru názvů Event Hubs a centra událostí pomocí Azure Portal.

Vytvoření klienta pro centra událostí (Event Hubs)

Primární třídou pro interakci s Event Hubs je Microsoft. Azure. EventHubs. EventHubClient. Můžete vytvořit instanci této třídy pomocí metody CreateFromConnectionString , jak je znázorněno v následujícím příkladu:

private const string EventHubConnectionString = "Event Hubs namespace connection string";
private const string EventHubName = "event hub name";

var connectionStringBuilder = new EventHubsConnectionStringBuilder(EventHubConnectionString)
{
    EntityPath = EventHubName

};
eventHubClient = EventHubClient.CreateFromConnectionString(connectionStringBuilder.ToString());

Odesílání událostí do centra událostí

Události odesíláte do centra událostí vytvořením instance EventHubClient a jejím asynchronním odesláním prostřednictvím metody SendAsync . Tato metoda přijímá jeden parametr instance EventData a asynchronně ho odesílá do centra událostí.

Serializace událostí

Třída EventDatadva přetížené konstruktory , které přijímají různé parametry, bajty nebo bajtové pole, které reprezentují datovou část dat události. Pokud při práci s třídou EventData používáte JSON, můžete načíst pole bajtů řetězce kódovaného ve formátu JSON pomocí metody Encoding.UTF8.GetBytes(). Například:

for (var i = 0; i < numMessagesToSend; i++)
{
    var message = $"Message {i}";
    Console.WriteLine($"Sending message: {message}");
    await eventHubClient.SendAsync(new EventData(Encoding.UTF8.GetBytes(message)));
}

Klíč oddílu

Poznámka

Pokud nejste obeznámeni s oddíly, přečtěte si Tento článek.

Při odesílání dat události můžete zadat hodnotu, která má hash k vytvoření přiřazení oddílu. Oddíl určíte pomocí vlastnosti PartitionSender. PartitionID . Rozhodnutí o použití oddílů ale implikuje možnost volby mezi dostupností a konzistencí. Další informace najdete v tématu dostupnost a konzistence.

Dávkové operace odesílání událostí

Odesílání událostí v dávkách může přispět ke zvýšení propustnosti. Pomocí rozhraní CreateBatch API můžete vytvořit dávku, do které lze později přidat datové objekty pro volání SendAsync .

Jedna dávka nesmí překročit omezení 1 MB události. Kromě toho každá zpráva v batchi používá stejnou identitu zdroje. Dodržení maximálního limitu velikosti události u batche musí zajistit odesílatel. V případě překročení se u klienta vygeneruje chyba odeslání (Send). K zajištění, aby dávka nepřekročila 1 MB, můžete použít pomocnou metodu EventHubClient. CreateBatch . Z rozhraní CreateBatch API získáte prázdné EventDataBatch a pak pomocí TryAdd přidáte události pro vytvoření dávky.

Asynchronní odesílání a škálované odesílání

Události se odesílají do centra událostí asynchronně. Odesílání asynchronně zvyšuje rychlost, s jakou klient může odesílat události. SendAsync vrátí objekt Task . K řízení možností opakování klienta můžete použít třídu RetryPolicy na klientovi.

Příjemci událostí

Třída EventProcessorHost zpracovává data z center událostí (Event Hubs). Tuto implementaci byste měli používat při vytváření čtenářů událostí na platformě .NET. Třída EventProcessorHost poskytuje pro implementace zpracovatelů událostí bezpečné prostředí runtime, které umožňuje bezpečné použití vláken a více procesů. Taky poskytuje možnost vytváření kontrolních bodů a správy „půjčování“ oddílu.

K použití třídy EventProcessorHost může být potřeba implementovat rozhraní IEventProcessor. Toto rozhraní obsahuje čtyři metody:

Pokud chcete spustit zpracování událostí, vytvořte instanci EventProcessorHosta poskytněte příslušné parametry centra událostí. Například:

var eventProcessorHost = new EventProcessorHost(
        EventHubName,
        PartitionReceiver.DefaultConsumerGroupName,
        EventHubConnectionString,
        StorageConnectionString,
        StorageContainerName);

Pak zavolejte RegisterEventProcessorAsync k registraci vaší implementace IEventProcessor s modulem runtime:

await eventProcessorHost.RegisterEventProcessorAsync<SimpleEventProcessor>();

V tomto okamžiku se hostitel pokusí získat zapůjčení na všech oddílech v centru událostí pomocí algoritmu "hladce". Tato zapůjčení pro daný rámec uplynula a musí být obnovena. V tomto případě se instance pracovních procesů připojí jako nové uzly a umístí své rezervace zapůjčení. Každý uzel se snaží získat další zapůjčení, a tak se v průběhu času zatížení posune.

Event Processor Host

Postupem času se dosáhne rovnováhy. Tato dynamická funkce umožňuje použití automatického škálování na bázi procesoru u příjemců jak pro vertikální navýšení, tak pro vertikální snížení kapacity. Vzhledem k tomu, že Event Hubs nemá přímý koncept počtů zpráv, je průměrné využití procesoru často nejlepším mechanismem měření back-endu nebo měřítka uživatele. Když začnou zdroje publikovat více událostí, než mohou příjemci zpracovat, může být zvýšená aktivita procesoru využita k automatickému škálování počtu instancí pracovních procesů.

Třída EventProcessorHost taky implementuje mechanismus vytváření kontrolních bodů Azure na bázi úložiště. Tento mechanismus ukládá posun na bázi oddílu, každý příjemce tedy může určit poslední kontrolní bod předchozího příjemce. Vzhledem k tomu, že oddíly prostřednictvím zapůjčení přechází mezi uzly, usnadňuje tento synchronizační mechanismus přesun zátěže.

Odvolání zdroje

Kromě pokročilých běhových funkcí pro hostitele procesoru událostí umožňuje služba Event Hubs odvolání vydavatele , aby bylo možné zablokovat konkrétním vydavatelům odeslání události do centra událostí. Tyto funkce jsou užitečné, pokud dojde k ohrožení bezpečnosti tokenu vydavatele nebo aktualizace softwaru způsobuje nepatřičné chování. V těchto situacích může být pro identitu zdroje, která je součástí jeho tokenu SAS, zablokováno publikování událostí.

Poznámka

V současné době tato funkce podporuje jenom REST API (odvolání vydavatele).

Další kroky

Další informace o scénářích služby Event Hubs naleznete pod těmito odkazy: