Enlaces de Azure IoT Hub para Azure Functions

  • Artículo

En esta serie de artículos se explica cómo usar enlaces de Azure Functions para IoT Hub. La compatibilidad de IoT Hub se basa en el enlace de Azure Event Hubs.

Importante

Aunque los ejemplos de código siguientes usan la API de Event Hubs, la sintaxis proporcionada es aplicable para las funciones de IoT Hub.

Acción Tipo
Responder a los eventos enviados a una secuencia de eventos del centro de IoT. Desencadenador

Instalación de la extensión

El paquete NuGet de la extensión que instale depende del modo de C# que esté usando en la aplicación de funciones:

Las funciones se ejecutan en el mismo proceso que el host de Functions. Para más información, consulte Desarrollo de funciones de la biblioteca de clases de C# con Azure Functions.

La funcionalidad de la extensión varía en función de la versión de la extensión:

Esta versión presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Esta versión usa el tipo de enlace de Event Hubs Azure.Messaging.EventHubs.EventData más reciente.

Esta versión de extensión está disponible instalando este paquete NuGet, versión 5.x.

Instalación del conjunto

La extensión de Event Hubs forma parte de un conjunto de extensiones, que se especifica en el archivo de proyecto host.json. Es posible que tenga que modificar este conjunto para cambiar la versión de los enlaces de Event Grid o en caso de que los conjuntos aún no estén instalados. Para obtener más información, consulte Conjuntos de extensiones.

Esta versión presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Para agregar esta versión de la extensión desde el conjunto de extensiones v3, puede agregar o reemplazar el código siguiente en el archivo host.json:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Para obtener más información, consulte Actualización de las extensiones.

configuración de host.json

El archivo host.json contiene opciones de configuración que controlan el comportamiento del desencadenador de Event Hubs. La configuración varía en función de la versión de las extensiones.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Propiedad Valor predeterminado Descripción
maxEventBatchSize 10 Número máximo de eventos que se incluirán en un lote para una sola invocación. Debe ser 1 como mínimo.
minEventBatchSize1 1 Número mínimo de eventos deseados en un lote. El número mínimo solo se aplica cuando la función recibe varios eventos y debe ser menor que maxEventBatchSize.
El tamaño mínimo no está garantizado estrictamente. Se envía un lote parcial cuando no se puede preparar un lote completo antes de que maxWaitTime haya transcurrido. Los lotes parciales también son probables para la primera invocación de la función después de que se produzca el escalado.
maxWaitTime1 00:01:00 Intervalo máximo que el desencadenador debe esperar para rellenar un lote antes de invocar la función. El tiempo de espera solo se considera cuando minEventBatchSize es mayor que 1 y, de lo contrario, se omite. Si hay menos de minEventBatchSize eventos disponibles antes de que transcurra el tiempo de espera, se invoca la función con un lote parcial. El tiempo de espera permitido más largo es de 10 minutos.

NOTA: Este intervalo no es una garantía estricta para el tiempo exacto en el que se invoca la función. Hay un pequeño margen de error debido a la precisión del temporizador. Cuando se realiza el escalado, la primera invocación con un lote parcial puede producirse más rápidamente o puede tardar hasta dos veces el tiempo de espera configurado.
batchCheckpointFrequency 1 Número de lotes que se procesarán antes de crear un punto de control para el centro de eventos.
prefetchCount 300 Número de eventos que se solicitan diligentemente desde Event Hubs y que se mantienen en una caché local para permitir que las lecturas eviten esperar en una operación de red.
transportType amqpTcp El protocolo y el transporte que se usan para comunicarse con Event Hubs. Opciones disponibles: amqpTcp, amqpWebSockets.
webProxy null Proxy que se usará para comunicarse con Event Hubs a través de sockets web. Recuerde que no se puede usar un proxy con el transporte amqpTcp.
customEndpointAddress null Dirección que se va a usar al establecer una conexión a Event Hubs, lo que permite enrutar las solicitudes de red a través de una puerta de enlace de aplicaciones u otra ruta de acceso necesaria para el entorno de host. El espacio de nombres completo para el centro de eventos sigue siendo necesario cuando se usa una dirección de punto de conexión personalizada y se debe especificar explícitamente o a través de la cadena de conexión.
targetUnprocessedEventThreshold1 null Número deseado de eventos no procesados por instancia de función. El umbral se usa en el escalado basado en el destino para invalidar el umbral de escalado predeterminado inferido de la opción maxEventBatchSize. Cuando se establezca, el recuento total de eventos no procesados se dividirá por este valor para determinar el número de instancias de función necesarias. El recuento de instancias se redondeará a un número que crea una distribución de partición equilibrada.
initialOffsetOptions/type fromStart Ubicación en el flujo de eventos desde la que se inicia el procesamiento cuando no existe un punto de control en el almacenamiento. Se aplica a todas las particiones. Para obtener más información, consulte la documentación de OffsetType. Opciones disponibles: fromStart, fromEnd, fromEnqueuedTime.
initialOffsetOptions/enqueuedTimeUtc null Especifica la hora de puesta en cola del evento en la secuencia a partir de la que se va a iniciar el procesamiento. Cuando initialOffsetOptions/type se configura como fromEnqueuedTime, este valor es obligatorio. Admite la hora en cualquier formato admitido por DateTime.Parse(), como . Para mayor claridad, también debe especificar una zona horaria. Cuando no se especifica una zona horaria, Functions asume la zona horaria local del equipo que ejecuta la aplicación de funciones, que es la hora UTC cuando se ejecuta en Azure.
clientRetryOptions/mode exponential Enfoque que se debe usar para calcular los retrasos de reintento. El modo exponencial aplica un retraso a los reintentos en función de una estrategia de interrupción, en la que cada intento aumentará la duración que espera antes de volver a intentarlo. El modo fijo reintenta la operación a intervalos fijos, donde cada retraso tiene una duración uniforme. Opciones disponibles: exponential, fixed.
clientRetryOptions/tryTimeout 00:01:00 Duración máxima para esperar a que se complete la operación de Event Hubs por intento.
clientRetryOptions/delay 00:00:00.80 Factor de retraso o de interrupción que se aplicará entre reintentos.
clientRetryOptions/maximumDelay 00:00:01 Retraso máximo que se permite entre los reintentos.
clientRetryOptions/maximumRetries 3 Número máximo de reintentos antes de considerar que hay un error en la operación asociada.

1 El uso de minEventBatchSize y maxWaitTime requiere la versión v5.3.0 del paquete Microsoft.Azure.WebJobs.Extensions.EventHubs o una versión posterior.

clientRetryOptions se usan para reintentar las operaciones entre el host de Functions y Event Hubs (como capturar eventos y enviar eventos). Consulte las instrucciones sobre el Control de errores y reintentos de Azure Functions para obtener información sobre cómo aplicar directivas de reintento a funciones individuales.

Para una referencia de host.json en Azure Functions 2.x y versiones posteriores, consulte Referencia de host.json para Azure Functions.

Pasos siguientes