Bibliothèque de client Azure WebJobs Event Hubs pour .NET - version 6.0.1

Article
10/18/2023

Cette extension fournit des fonctionnalités permettant d’accéder à Azure Event Hubs à partir d’une fonction Azure.

Prise en main

Installer le package

Installez l’extension Event Hubs avec NuGet :

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

Prérequis

Abonnement Azure : Pour utiliser les services Azure, y compris Azure Event Hubs, vous avez besoin d’un abonnement. Si vous n’avez pas de compte Azure existant, vous pouvez vous inscrire à un essai gratuit ou utiliser les avantages de votre abonnement Visual Studio lorsque vous créez un compte.
Espace de noms Event Hubs avec un hub d’événements : Pour interagir avec Azure Event Hubs, vous devez également disposer d’un espace de noms et d’Un hub d’événements. Si vous n’êtes pas familiarisé avec la création de ressources Azure, vous pouvez suivre le guide pas à pas pour créer un Event Hub à l’aide de l’Portail Azure. Vous y trouverez également des instructions détaillées sur l’utilisation des modèles Azure CLI, Azure PowerShell ou Azure Resource Manager (ARM) pour créer un hub d’événements.
Compte de stockage Azure avec stockage d’objets blob : Pour conserver les points de contrôle en tant qu’objets blob dans stockage Azure, vous devez disposer d’un compte stockage Azure avec des objets blob disponibles. Si vous n’êtes pas familiarisé avec les comptes de stockage Azure, vous pouvez suivre le guide pas à pas pour créer un compte de stockage à l’aide de la Portail Azure. Vous y trouverez également des instructions détaillées sur l’utilisation des modèles Azure CLI, Azure PowerShell ou Azure Resource Manager (ARM) pour créer des comptes de stockage.

Authentifier le client

Pour que la bibliothèque cliente Event Hubs interagisse avec un hub d’événements, elle doit comprendre comment se connecter et autoriser avec elle. Le moyen le plus simple consiste à utiliser un chaîne de connexion, qui est créé automatiquement lors de la création d’un espace de noms Event Hubs. Si vous n’êtes pas familiarisé avec l’utilisation de chaînes de connexion avec Event Hubs, vous pouvez suivre le guide pas à pas pour obtenir un chaîne de connexion Event Hubs.

La Connection propriété de EventHubAttribute et EventHubTriggerAttribute est utilisée pour spécifier la propriété de configuration qui stocke le chaîne de connexion.

Le AzureWebJobsStorage chaîne de connexion est utilisé pour conserver les informations de point de contrôle de traitement.

Pour le développement local, utilisez le local.settings.json fichier pour stocker les chaîne de connexion :

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

Lors du déploiement, utilisez les paramètres de l’application pour définir le chaîne de connexion.

Authentification basée sur l’identité

Si l’identité managée est activée dans votre environnement, vous pouvez l’utiliser pour authentifier l’extension Event Hubs. Avant cela, vous devez vous assurer que les autorisations ont été configurées comme décrit dans le guide du développeur Azure Functions.

Pour utiliser l’authentification basée sur l’identité, fournissez le paramètre de <connection_name>__fullyQualifiedNamespace configuration.

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

Ou, dans le cas d’une application déployée, définissez le même paramètre dans les paramètres de l’application :

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

Vous trouverez plus d’informations sur la configuration d’une connexion basée sur l’identité ici.

Concepts clés

Déclencheur Event Hub

Le déclencheur Event Hub permet d’exécuter une fonction lorsqu’un message est envoyé à un Event Hub.

Suivez le didacticiel sur les déclencheurs Azure Event Hubs pour en savoir plus sur les déclencheurs Event Hub.

Liaison de sortie Event Hub

La liaison de sortie event hub permet à une fonction d’envoyer des événements Event Hub.

Suivez la liaison de sortie Azure Event Hubs pour en savoir plus sur les liaisons Event Hub.

Types pris en charge

Les types suivants sont pris en charge pour les liaisons de déclencheur et de sortie :

EventData
string - valeur encodée à l’aide de l’encodage UTF8
BinaryData
byte[]
Les types de modèles personnalisés seront sérialisés au format JSON à l’aide de Newtonsoft.Json
IAsyncCollector<T> de l’un des types ci-dessus pour les déclencheurs de lot
EventHubProducerClient pour les liaisons de sortie

Exemples

Envoi d’un événement individuel

Vous pouvez envoyer des événements individuels à un Event Hub en appliquant la EventHubAttribute valeur de retour de la fonction. La valeur de retour peut être de ou EventData de string type . Une clé de partition ne peut pas être spécifiée lors de l’utilisation d’une valeur de retour ; Pour ce faire, vous devez établir une liaison à , IAsyncCollector<EventData>comme indiqué dans Envoi de plusieurs événements.

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

Envoi de plusieurs événements

Pour envoyer plusieurs événements à partir d’un seul appel de fonction Azure, vous pouvez appliquer le EventHubAttribute au IAsyncCollector<string> paramètre ou IAsyncCollector<EventData> . Les clés de partition ne peuvent être utilisées que lors de la liaison à IAsyncCollector<EventData>.

[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");
}

Utilisation de la liaison à des modèles fortement typés

Pour utiliser des classes de modèle fortement typées avec la liaison EventHub, appliquez au EventHubAttribute paramètre de modèle.

[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!");
}

Envoi de plusieurs événements à l’aide d’EventHubProducerClient

Vous pouvez également effectuer une liaison directe à pour EventHubProducerClient avoir le plus de contrôle sur l’envoi de l’événement.

[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}")
    });
}

Déclencheurs par événement

Pour exécuter une fonction chaque fois qu’un événement est envoyé à Event Hub, appliquez le EventHubTriggerAttribute à un string paramètre ou EventData .

[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}");
}

Déclencheurs batch

Pour exécuter une fonction pour un lot d’événements reçus, appliquez le EventHubTriggerAttribute à un string[] paramètre ou EventData[] .

[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}");
    }
}

Dépannage

Pour obtenir des conseils de dépannage, reportez-vous à Monitor Azure Functions.

Étapes suivantes

Lisez l’introduction à Azure Functions ou à la création d’un guide de fonction Azure.

Contribution

Consultez notre CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions

Partager via