Azure WebJobs Event Hubs-Clientbibliothek für .NET – Version 6.0.1

Artikel
10/18/2023

Diese Erweiterung bietet Funktionen für den Zugriff auf Azure Event Hubs über eine Azure-Funktion.

Erste Schritte

Installieren des Pakets

Installieren Sie die Event Hubs-Erweiterung mit NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs

Voraussetzungen

Azure-Abonnement: Für die Verwendung von Azure-Diensten, einschließlich Azure Event Hubs, benötigen Sie ein Abonnement. Wenn Sie nicht über ein vorhandenes Azure-Konto verfügen, können Sie sich für eine kostenlose Testversion registrieren oder ihre Visual Studio-Abonnementvorteile beim Erstellen eines Kontos nutzen.
Event Hubs-Namespace mit einem Event Hub: Um mit Azure Event Hubs zu interagieren, müssen Sie auch einen Namespace und Event Hub zur Verfügung haben. Wenn Sie mit dem Erstellen von Azure-Ressourcen nicht vertraut sind, sollten Sie die schrittweise Anleitung zum Erstellen eines Event Hubs mit dem Azure-Portal befolgen. Dort finden Sie auch ausführliche Anweisungen zum Verwenden von Azure CLI-, Azure PowerShell- oder Azure Resource Manager-Vorlagen (ARM) zum Erstellen eines Event Hubs.
Azure Storage-Konto mit Blobspeicher: Zum Beibehalten von Prüfpunkten als Blobs in Azure Storage benötigen Sie ein Azure Storage-Konto mit verfügbaren Blobs. Wenn Sie mit Azure Storage-Konten nicht vertraut sind, können Sie die schrittweise Anleitung zum Erstellen eines Speicherkontos mithilfe des Azure-Portal befolgen. Dort finden Sie auch ausführliche Anweisungen zum Verwenden von Azure CLI-, Azure PowerShell- oder Azure Resource Manager-Vorlagen (ARM) zum Erstellen von Speicherkonten.

Authentifizieren des Clients

Damit die Event Hubs-Clientbibliothek mit einem Event Hub interagieren kann, muss sie verstehen, wie eine Verbindung hergestellt und autorisiert werden kann. Die einfachste Möglichkeit hierfür ist die Verwendung einer Verbindungszeichenfolge, die beim Erstellen eines Event Hubs-Namespaces automatisch erstellt wird. Wenn Sie mit der Verwendung von Verbindungszeichenfolgen mit Event Hubs nicht vertraut sind, sollten Sie die schrittweise Anleitung befolgen, um eine Event Hubs-Verbindungszeichenfolge zu erhalten.

Die Connection -Eigenschaft von EventHubAttribute und EventHubTriggerAttribute wird verwendet, um die Konfigurationseigenschaft anzugeben, in der die Verbindungszeichenfolge gespeichert wird.

Die AzureWebJobsStorage Verbindungszeichenfolge wird verwendet, um die Verarbeitungsprüfpunktinformationen beizubehalten.

Verwenden Sie für die lokale Entwicklung die local.settings.json Datei, um die Verbindungszeichenfolge zu speichern:

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>": "Endpoint=sb://<event_hubs_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=Jya7Eh76HU92ibsxuk1ITN8CM8Bt76YLKf5ISjU3jZ8="
  }
}

Verwenden Sie bei der Bereitstellung die Anwendungseinstellungen, um die Verbindungszeichenfolge festzulegen.

Identitätsbasierte Authentifizierung

Wenn Für Ihre Umgebung eine verwaltete Identität aktiviert ist, können Sie sie verwenden, um die Event Hubs-Erweiterung zu authentifizieren. Zuvor müssen Sie sicherstellen, dass Berechtigungen wie im Azure Functions Entwicklerhandbuch beschrieben konfiguriert wurden.

Um die identitätsbasierte Authentifizierung zu verwenden, geben Sie die <connection_name>__fullyQualifiedNamespace Konfigurationseinstellung an.

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>__fullyQualifiedNamespace": "{event_hubs_namespace}.servicebus.windows.net"
  }
}

Oder legen Sie im Fall der bereitgestellten App die gleiche Einstellung in den Anwendungseinstellungen fest:

<connection_name>__fullyQualifiedNamespace={event_hubs_namespace}.servicebus.windows.net

Weitere Informationen zum Konfigurieren einer identitätsbasierten Verbindung finden Sie hier.

Wichtige Begriffe

Event Hub-Trigger

Mit dem Event Hub-Trigger kann eine Funktion ausgeführt werden, wenn eine Nachricht an einen Event Hub gesendet wird.

Befolgen Sie das Tutorial Azure Event Hubs Trigger, um mehr über Event Hub-Trigger zu erfahren.

Event Hub-Ausgabebindung

Die Event Hub-Ausgabebindung ermöglicht es einer Funktion, Event Hub-Ereignisse zu senden.

Folgen Sie der Azure Event Hubs Ausgabebindung, um mehr über Event Hub-Bindungen zu erfahren.

Unterstützte Typen

Die folgenden Typen werden für Trigger- und Ausgabebindungen unterstützt:

EventData
string - Wert wird mit UTF8-Codierung codiert
BinaryData
byte[]
Benutzerdefinierte Modelltypen werden mithilfe von Newtonsoft.Json JSON serialisiert.
IAsyncCollector<T> eines der oben genannten Typen für Batchtrigger
EventHubProducerClient für Ausgabebindungen

Beispiele

Senden eines einzelnen Ereignisses

Sie können einzelne Ereignisse an einen Event Hub senden, indem Sie den EventHubAttribute Funktionsrückgabewert anwenden. Der Rückgabewert kann vom string Typ oder EventData sein. Bei Verwendung eines Rückgabewerts werden möglicherweise keine Partitionsschlüssel angegeben. Dazu müssen Sie eine Bindung an das IAsyncCollector<EventData>herstellen, wie unter Senden mehrerer Ereignisse gezeigt.

[FunctionName("BindingToReturnValue")]
[return: EventHub("<event_hub_name>", Connection = "<connection_name>")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer)
{
    // This value would get stored in EventHub event body.
    // The string would be UTF8 encoded
    return $"C# Timer trigger function executed at: {DateTime.Now}";
}

Senden mehrerer Ereignisse

Um mehrere Ereignisse von einem einzelnen Azure-Funktionsaufruf zu senden, können Sie die auf den EventHubAttributeIAsyncCollector<string> - oder IAsyncCollector<EventData> -Parameter anwenden. Partitionsschlüssel dürfen nur bei der Bindung an IAsyncCollector<EventData>verwendet werden.

[FunctionName("BindingToCollector")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [EventHub("<event_hub_name>", Connection = "<connection_name>")] IAsyncCollector<EventData> collector)
{
    // When no partition key is used, partitions will be assigned per-batch via round-robin.
    await collector.AddAsync(new EventData($"Event 1 added at: {DateTime.Now}"));
    await collector.AddAsync(new EventData($"Event 2 added at: {DateTime.Now}"));

    // Using a partition key will help group events together; events with the same key
    // will always be assigned to the same partition.
    await collector.AddAsync(new EventData($"Event 3 added at: {DateTime.Now}"), "sample-key");
    await collector.AddAsync(new EventData($"Event 4 added at: {DateTime.Now}"), "sample-key");
}

Verwenden der Bindung an stark typisierte Modelle

Um stark typisierte Modellklassen mit der EventHub-Bindung zu verwenden, wenden Sie den EventHubAttribute auf den Modellparameter an.

[FunctionName("TriggerSingleModel")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] Dog dog,
    ILogger logger)
{
    logger.LogInformation($"Who's a good dog? {dog.Name} is!");
}

Senden mehrerer Ereignisse mithilfe von EventHubProducerClient

Sie können auch direkt an das EventHubProducerClient binden, um die meiste Kontrolle über das sendende Ereignis zu haben.

[FunctionName("BindingToProducerClient")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [EventHub("<event_hub_name>", Connection = "<connection_name>")] EventHubProducerClient eventHubProducerClient)
{
    // IAsyncCollector allows sending multiple events in a single function invocation
    await eventHubProducerClient.SendAsync(new[]
    {
        new EventData($"Event 1 added at: {DateTime.Now}"),
        new EventData($"Event 2 added at: {DateTime.Now}")
    });
}

Trigger pro Ereignis

Wenn Sie eine Funktion jedes Mal ausführen möchten, wenn ein Ereignis an Event Hub gesendet wird, wenden Sie die EventHubTriggerAttribute auf einen oder EventData -Parameter anstring.

[FunctionName("TriggerSingle")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] string eventBodyAsString,
    ILogger logger)
{
    logger.LogInformation($"C# function triggered to process a message: {eventBodyAsString}");
}

Batchtrigger

Um eine Funktion für einen Batch empfangener Ereignisse auszuführen, wenden Sie das EventHubTriggerAttribute auf einen string[] - oder EventData[] -Parameter an.

[FunctionName("TriggerBatch")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] EventData[] events,
    ILogger logger)
{
    foreach (var e in events)
    {
        logger.LogInformation($"C# function triggered to process a message: {e.EventBody}");
        logger.LogInformation($"EnqueuedTime={e.EnqueuedTime}");
    }
}

Problembehandlung

Anleitungen zur Problembehandlung finden Sie unter Überwachen Azure Functions.

Nächste Schritte

Lesen Sie die Einführung in Azure Functions oder erstellen sie eine Azure Function-Anleitung.

Mitwirken

Weitere Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie in unserem CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Freigeben über