Enlace de salida de Azure Event Hubs para Azure Functions

  • Artículo

En este artículo se explica cómo usar enlaces de Azure Event Hubs para Azure Functions. Azure Functions admite enlaces de desencadenador y salida para Event Hubs.

Para obtener información sobre los detalles de instalación y configuración, vea la información general.

Use el enlace de salida de Event Hubs para escribir eventos en una secuencia. Debe tener permiso de envío a un centro de eventos para escribir eventos en él.

Asegúrese de que las referencias de paquete necesarias están implementadas antes de tratar de implementar un enlace de salida.

Importante

En este artículo se usan pestañas para admitir varias versiones del modelo de programación de Node.js. El modelo v4 está disponible de forma general y está diseñado para que los desarrolladores de JavaScript y TypeScript tengan una experiencia más flexible e intuitiva. Para más detalles acerca de cómo funciona el modelo v4, consulte la Guía para desarrolladores de Node.js de Azure Functions. Para más información sobre las diferencias entre v3 y v4, consulte la Guía de migración.

Azure Functions admite dos modelos de programación para Python. La forma en que defina los enlaces depende del modelo de programación seleccionado.

El modelo de programación de Python v2 permite definir enlaces mediante decoradores directamente en el código de función de Python. Para más información, consulte la Guía para desarrolladores de Python.

En este artículo se admiten los modelos de programación.

Ejemplo

En el ejemplo siguiente se muestra una función de C# que escribe una cadena de mensaje en un centro de eventos usando el valor devuelto del método como resultado:

[Function(nameof(EventHubFunction))]
[FixedDelayRetry(5, "00:00:10")]
[EventHubOutput("dest", Connection = "EventHubConnection")]
public string EventHubFunction(
    [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
    FunctionContext context)
{
    _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

    var message = $"Output message created at {DateTime.Now}";
    return message;
}

En el ejemplo siguiente se muestra un temporizador desencadenado Función TypeScript que envía un único mensaje a un centro de eventos:

import { app, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventHub({
        eventHubName: 'myeventhub',
        connection: 'MyEventHubSendAppSetting',
    }),
    handler: timerTrigger1,
});

Para generar varios mensajes, devuelva una matriz en lugar de un solo objeto. Por ejemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

En el ejemplo siguiente se muestra un temporizador desencadenado Función de JavaScript que envía un único mensaje a un centro de eventos:

const { app, output } = require('@azure/functions');

const eventHubOutput = output.eventHub({
    eventHubName: 'myeventhub',
    connection: 'MyEventHubSendAppSetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventHubOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Para generar varios mensajes, devuelva una matriz en lugar de un solo objeto. Por ejemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Los ejemplos completos de PowerShell están pendientes.

En el ejemplo siguiente se muestra un enlace de desencadenador de Event Hubs y una función de Python que usa el enlace. La función escribe un mensaje a un centro de eventos. El ejemplo depende de si usa el modelo de programación de Python v1 o v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
    body = req.get_body()
    if body is not None:
        event.set(body.decode('utf-8'))
    else:    
        logging.info('req body is none')
    return 'ok'

Este es el código de Python que envía varios mensajes:

import logging
import azure.functions as func
from typing import List

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")

def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
    my_messages=["message1", "message2","message3"]
    event.set(my_messages)
    return func.HttpResponse(f"Messages sent")

El ejemplo siguiente muestra una función de Java que escribe un mensaje que contiene la hora actual en un centro de eventos.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @EventHubOutput en los parámetros cuyo valor se publicaría en Event Hubs. El parámetro debe ser de tipo OutputBinding<T>, donde T es un tipo POJO o cualquier tipo nativo de Java.

Atributos

Las bibliotecas de C# en proceso y de procesos de trabajo aislados usan un atributo para configurar el enlace. En su lugar, el script de C# usa un archivo de configuración function.json como se describe en la Guía de scripting de C#.

Use [EventHubOutputAttribute] para definir un enlace de salida a un centro de eventos, que admite las siguientes propiedades.

Parámetros Descripción
EventHubName El nombre del centro de eventos. Cuando el nombre del centro de eventos también está presente en la cadena de conexión, ese valor reemplaza esta propiedad en tiempo de ejecución.
Connection Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a Event Hubs. Para más información, consulte Conexiones.

Elementos Decorator

Solo se aplica al modelo de programación de Python v2.

Para las funciones de Python v2 definidas mediante un decorador, se aplican las siguientes propiedades en cosmos_db_trigger:

Propiedad Descripción
arg_name Nombre de la variable que se usa en el código de la función que representa el evento.
event_hub_name El nombre del centro de eventos. Cuando el nombre del centro de eventos también está presente en la cadena de conexión, ese valor reemplaza esta propiedad en tiempo de ejecución.
connection Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a Event Hubs. Para más información, consulte Conexiones.

Para las funciones de Python definidas mediante function.json, consulte la sección Configuración.

anotaciones

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación EventHubOutput en los parámetros cuyo valor se publicaría en Event Hubs. En la anotación se admiten los siguientes valores:

Configuración

Solo se aplica al modelo de programación de Python v1.

En la tabla siguiente se explican las propiedades que puede establecer en el objeto options que se pasa al métodooutput.eventHub().

Propiedad Descripción
eventHubName El nombre del centro de eventos. Cuando el nombre del centro de eventos también está presente en la cadena de conexión, ese valor reemplaza esta propiedad en tiempo de ejecución.
connection Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a Event Hubs. Para más información, consulte Conexiones.

En la siguiente tabla se explican las propiedades de configuración de enlace que definió en el archivo function.json, que difiere según la versión de tiempo de ejecución.

Propiedad de function.json Descripción
type Se debe establecer en eventHub.
direction Se debe establecer en out. Este parámetro se establece automáticamente cuando se crea el enlace en Azure Portal.
name Nombre de la variable que se usa en el código de la función que representa el evento.
eventHubName Functions 2.x y versiones posteriores. El nombre del centro de eventos. Cuando el nombre del centro de eventos también está presente en la cadena de conexión, ese valor reemplaza esta propiedad en tiempo de ejecución.
connection Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a Event Hubs. Para más información, consulte Conexiones.

Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.

Uso

El tipo de parámetro admitido por el enlace de salida de Event Hubs depende de la versión del tiempo de ejecución de Functions, la versión del paquete de extensión y la modalidad de C# utilizada.

Cuando quiera que la función escriba un único evento, el enlace de salida de Event Hubs puede enlazarse a los siguientes tipos:

Tipo Descripción
string El evento como una cadena. Se usa cuando el evento es de texto simple.
byte[] Bytes del evento.
Tipos serializables con JSON Un objeto que representa el evento. Functions intenta serializar un tipo de objeto CLR convencional (POCO) en datos JSON.

Cuando quiera que la función escriba varios eventos, el enlace de salida de Event Hubs puede enlazarse a los siguientes tipos:

Tipo Descripción
T[] donde T es uno de los tipos de eventos únicos Matriz que contiene varios eventos. Cada entrada representa un evento.

Para otros escenarios de salida, cree y use tipos de Microsoft.Azure.EventHubs directamente.

Hay dos opciones para la generación de un mensaje de Event Hubs desde una función mediante la anotación EventHubOutput:

  • Valor devuelto: Al aplicar la anotación a la propia función, el valor devuelto de la función se conserva como un mensaje de Event Hubs.

  • Imperativo: Para establecer explícitamente el valor del mensaje, aplique la anotación a un parámetro específico del tipo OutputBinding<T>, donde T es un POJO o cualquier tipo de Java nativo. Con esta configuración, pasar un valor al método setValue conserva el valor como un mensaje del Event Hubs.

Los ejemplos completos de PowerShell están pendientes.

Acceda al mensaje de salida devolviendo el valor directamente o mediante context.extraOutputs.set().

Hay dos opciones para la generación de un mensaje de Event Hubs desde una función:

  • Valor devuelto: Establezca la propiedad name de function.json en $return. Con esta configuración, el valor devuelto de la función se conserva como mensaje de Event Hubs.

  • Imperativa: Pase un valor al método set del parámetro declarado como tipo Out. El valor pasado a set se conserva como mensaje de Event Hubs.

Conexiones

La propiedad connection es una referencia a la configuración del entorno que especifica cómo se debe conectar la aplicación a Event Hubs. Puede especificar lo siguiente:

Si el valor configurado es tanto una coincidencia exacta de una única configuración como una coincidencia de prefijo de otras configuraciones, se usa la coincidencia exacta.

Cadena de conexión

Para obtener esta cadena de conexión, haga clic en el botón Información de conexión del espacio de nombres, no del propio centro de eventos. La cadena de conexión debe ser para un espacio de nombres de Event Hubs, no para el propio centro de eventos.

Cuando se usa para desencadenadores, la cadena de conexión debe tener al menos permisos de "lectura" para activar la función. Cuando se usa para los enlaces de salida, la cadena de conexión debe tener permisos de "envío" para enviar mensajes al flujo de eventos.

La cadena de conexión debe almacenarse en una configuración de la aplicación con un nombre que coincida con el valor especificado por la propiedad connection de la configuración de enlace.

Conexiones basadas en identidades

Si usa versión 5.x o posterior de la extensión, en lugar de usar una cadena de conexión con un secreto, puede hacer que la aplicación use una Identidad de Microsoft Entra. Para ello, definiría la configuración con un prefijo común que se asigne a la propiedad connection en la configuración de desencadenador y enlace.

En este modo, la extensión requiere las siguientes propiedades:

Propiedad Plantilla de variable de entorno Descripción Valor de ejemplo
Espacio de nombres completo <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Espacio de nombres completo de Event Hubs. myeventhubns.servicebus.windows.net

Se pueden establecer propiedades adicionales para personalizar la conexión. Consulte Propiedades comunes para conexiones basadas en identidades.

Nota

Al usar Azure App Configuration o Key Vault para proporcionar la configuración de las conexiones de identidad administrada, los nombres de configuración deben usar un separador de clave válido, como : o / en lugar de __ para asegurarse de que los nombres se resuelven correctamente.

Por ejemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Cuando se hospeda en el servicio de Azure Functions, las conexiones basadas en identidades usan una identidad administrada. La identidad asignada por el sistema se usa de manera predeterminada, aunque se puede especificar una identidad asignada por el usuario con las propiedades credential y clientID. Tenga en cuenta que no se admite la configuración de una identidad asignada por el usuario con un identificador de recurso. Cuando se ejecuta en otros contextos, como el de desarrollo local, se usa en su lugar la identidad del desarrollador, aunque se puede personalizar. Consulte Desarrollo local con conexiones basadas en identidades.

Concesión de permiso a la identidad

Cualquier identidad que se utilice debe tener permisos para realizar las acciones previstas. Para la mayoría de los servicios de Azure, esto significa que debe asignar un rol en Azure RBAC mediante roles integrados o personalizados que proporcionen esos permisos.

Importante

Es posible que el servicio de destino muestre algunos permisos que no son necesarios para todos los contextos. Siempre que sea posible, respete el principio de privilegios mínimos y conceda solo los privilegios necesarios a la identidad. Por ejemplo, si la aplicación solo necesita poder leer desde un origen de datos, use un rol que solo tenga permiso de lectura. Sería inadecuado asignar un rol que también permita escribir en ese servicio, ya que sería un permiso excesivo para una operación de lectura. De forma similar, le interesa asegurarse de que la asignación de roles esté limitada solo a los recursos que se deben leer.

Deberá crear una asignación de roles que proporcione acceso al centro de eventos en tiempo de ejecución. El ámbito de la asignación de roles puede ser para un espacio de nombres de Event Hubs o para el propio centro de eventos. Los roles de administración, como Propietario, no son suficientes. En la tabla siguiente se muestran los roles integrados que se recomiendan al usar la extensión de Event Hubs con un funcionamiento normal. Puede que la aplicación precise permisos adicionales en función del código que escriba.

Tipo de enlace Roles integrados de ejemplo
Desencadenador Receptor de los datos de Azure Event Hubs, Propietario de los datos de Azure Event Hubs
Enlace de salida Emisor de datos de Azure Event Hubs

Excepciones y códigos de retorno

Enlace Referencia
Event Hubs Guía de operaciones

Pasos siguientes