Biblioteca cliente de Event Hubs de Azure WebJobs para .NET: versión 6.0.1
Esta extensión proporciona funcionalidad para acceder a Azure Event Hubs desde una función de Azure.
Introducción
Instalar el paquete
Instale la extensión de Event Hubs con NuGet:
dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs
Requisitos previos
Suscripción de Azure: Para usar los servicios de Azure, incluida Azure Event Hubs, necesitará una suscripción. Si no tiene una cuenta de Azure existente, puede registrarse para obtener una evaluación gratuita o usar las ventajas de la suscripción de Visual Studio al crear una cuenta.
Espacio de nombres de Event Hubs con un centro de eventos: Para interactuar con Azure Event Hubs, también deberá tener un espacio de nombres y un centro de eventos disponibles. Si no está familiarizado con la creación de recursos de Azure, puede seguir la guía paso a paso para crear un centro de eventos mediante el Azure Portal. Allí también puede encontrar instrucciones detalladas para usar la CLI de Azure, Azure PowerShell o plantillas de Azure Resource Manager (ARM) para crear un centro de eventos.
Cuenta de Azure Storage con Blob Storage: Para conservar los puntos de control como blobs en Azure Storage, deberá tener una cuenta de Azure Storage con blobs disponibles. Si no está familiarizado con las cuentas de Azure Storage, puede seguir la guía paso a paso para crear una cuenta de almacenamiento mediante el Azure Portal. Allí también puede encontrar instrucciones detalladas para usar la CLI de Azure, Azure PowerShell o plantillas de Azure Resource Manager (ARM) para crear cuentas de almacenamiento.
Autenticar el cliente
Para que la biblioteca cliente de Event Hubs interactúe con un centro de eventos, deberá comprender cómo conectarse y autorizarla. Los medios más fáciles para hacerlo es usar un cadena de conexión, que se crea automáticamente al crear un espacio de nombres de Event Hubs. Si no está familiarizado con el uso de cadenas de conexión con Event Hubs, puede seguir la guía paso a paso para obtener un cadena de conexión de Event Hubs.
La Connection propiedad de y EventHubTriggerAttribute se usa para especificar la propiedad de EventHubAttribute configuración que almacena el cadena de conexión.
El AzureWebJobsStorage cadena de conexión se usa para conservar la información del punto de control de procesamiento.
Para el desarrollo local, use el local.settings.json archivo para almacenar el cadena de conexión:
{
"Values": {
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
"<connection_name>": "Endpoint=sb://<event_hubs_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=Jya7Eh76HU92ibsxuk1ITN8CM8Bt76YLKf5ISjU3jZ8="
}
}
Cuando se implementa, use la configuración de la aplicación para establecer el cadena de conexión.
Habilitación basada en identidad
Si el entorno tiene habilitada la identidad administrada , puede usarla para autenticar la extensión de Event Hubs. Antes de hacerlo, deberá asegurarse de que los permisos se han configurado como se describe en la guía para desarrolladores de Azure Functions.
Para usar la autenticación basada en identidades, proporcione la <connection_name>__fullyQualifiedNamespace configuración.
{
"Values": {
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
"<connection_name>__fullyQualifiedNamespace": "{event_hubs_namespace}.servicebus.windows.net"
}
}
O bien, en el caso de la aplicación implementada, establezca la misma configuración en la configuración de la aplicación:
<connection_name>__fullyQualifiedNamespace={event_hubs_namespace}.servicebus.windows.net
Puede encontrar más detalles sobre cómo configurar una conexión basada en identidades aquí.
Conceptos clave
Desencadenador de centro de eventos
El desencadenador del centro de eventos permite ejecutar una función cuando se envía un mensaje a un centro de eventos.
Siga el tutorial del desencadenador de Azure Event Hubs para obtener más información sobre los desencadenadores del centro de eventos.
Enlace de salida del centro de eventos
El enlace de salida del centro de eventos permite que una función envíe eventos del centro de eventos.
Siga el enlace de salida de Azure Event Hubs para obtener más información sobre los enlaces de Event Hubs.
Tipos admitidos
Se admiten los siguientes tipos para enlaces de desencadenador y salida:
EventDatastring: el valor se codificaría mediante codificación UTF8.BinaryDatabyte[]- Los tipos de modelo personalizados se serializarán mediante Newtonsoft.Json
IAsyncCollector<T>de cualquiera de los tipos anteriores para los desencadenadores por lotesEventHubProducerClientpara enlaces de salida
Ejemplos
Envío de eventos individuales
Puede enviar eventos individuales a un centro de eventos aplicando el valor devuelto de la EventHubAttribute función. El valor devuelto puede ser de string o EventData tipo. Es posible que no se especifiquen claves de partición al usar un valor devuelto; para ello, deberá enlazar a , IAsyncCollector<EventData>como se muestra en Envío de varios eventos.
[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}";
}
Envío de varios eventos
Para enviar varios eventos desde una única invocación de función de Azure, puede aplicar al EventHubAttributeIAsyncCollector<string> parámetro o IAsyncCollector<EventData> . Las claves de partición solo se pueden usar al enlazar a 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");
}
Uso del enlace a modelos fuertemente tipados
Para usar clases de modelo fuertemente tipadas con el enlace de EventHub, aplique al EventHubAttribute parámetro del modelo.
[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!");
}
Envío de varios eventos mediante EventHubProducerClient
También puede enlazar directamente EventHubProducerClient para tener el mayor control sobre el envío de eventos.
[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}")
});
}
Desencadenadores por evento
Para ejecutar una función cada vez que se envía un evento al centro de eventos, aplique a EventHubTriggerAttribute un string parámetro o 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}");
}
Desencadenadores de Batch
Para ejecutar una función para un lote de eventos recibidos, aplique a EventHubTriggerAttribute un string[] parámetro o 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}");
}
}
Solución de problemas
Consulte Monitor Azure Functions para obtener instrucciones de solución de problemas.
Pasos siguientes
Lea la introducción a Azure Functions o cree una guía de funciones de Azure.
Contribuciones
Consulte nuestra CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.
Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.
Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de