Resumen de la extensión de conector para Azure Functions

Azure Functions proporciona extensiones de disparador y vinculación que se integran con varios servicios, principalmente servicios de Azure. La extensión Connector amplía estas integraciones mediante conectores gestionados en Azure Espacio de Nombres de Conectores, permitiendo que tus funciones reciban eventos de sistemas empresariales y plataformas de datos como Office 365 Outlook, SharePoint Online, Microsoft Teams y Dataverse.

Para los conectores Microsoft y gestionados por terceros disponibles, consulte la referencia de conectores.

Note

Los conectores gestionados soportan los planes de alojamiento Flex Consumption, Dedicated y Elastic Premium para aplicaciones Linux Function en todas las regiones. La disponibilidad de las aplicaciones para Windows es limitada hoy en día.

Flex Consumption es el plan de alojamiento recomendado para funciones activadas por conectores.

Note

Actualmente, el Connector Trigger no está soportado para este lenguaje.

En Uso
Ejecutar una función en respuesta a un evento en un servicio conectado Disparador del conector, proporcionado por la extensión del conector
Realizar una acción en un servicio conectado a partir del código de la función Azure Connectors SDK, disponible para .NET, Node.jsy Python

Puede usar ambos a la vez: el Conector Trigger inicia su función y el SDK realiza acciones en los servicios conectados. Si solo necesitas realizar acciones, usa el SDK sin la extensión del conector.

Para más información sobre conectores gestionados, cuándo utilizarlos y disponibilidad de funciones, consulte Usar conectores gestionados en Azure Functions.

Conector Trigger en Azure Functions

Una función activada por el conector utiliza estos componentes:

Component Responsabilidad
Espacio de nombres del conector Hosts gestionaba conexiones de conectores y configuraciones de disparos.
Conexión gestionada por conector Se autentica con el servicio externo y gestiona la conectividad específica del servicio.
Configuración del desencadenador Selecciona el evento del conector, los parámetros de operación y el modo de entrega.
Azure Functions Connector Extension Recibe eventos del Espacio de Nombres del Conector, invoca la función y vincula el cuerpo del evento al parámetro de la función.
Azure Connectors SDK (opcional) Proporciona modelos opcionales de carga útil fuertemente tipada y clientes para invocar operaciones gestionadas de conectores, como enviar un correo electrónico o crear un archivo SharePoint.

Un conector gestionado puede soportar múltiples eventos, y cada evento que quieras monitorizar necesita su propia configuración de disparador. Por ejemplo, el conector Office 365 Outlook soporta eventos como la llegada de un nuevo correo electrónico, un correo que se marca, la creación de un evento en el calendario o la modificación de un evento del calendario. Crea una configuración de disparador separada para cada evento que quieras usar para ejecutar una función.

Para ejemplos de código, consulte Ejemplos de disparadores de conector y Uso de SDKs de conectores en su código.

Elige un modo de entrega

Los conectores gestionados soportan webhook y entrega de sondeos. Elija un modo basado en la latencia, capacidad de procesamiento, red y necesidades de autenticación de su escenario:

Feature Encuesta Webhook
Entrega de eventos y latencia El host de Funciones recupera eventos mediante solicitudes de sondeo salientes. Los eventos esperan hasta que el anfitrión los solicite. El Espacio de Nombres del Conector envía eventos al endpoint de callback de la aplicación de funciones tan pronto como los recoge del servicio fuente, sin esperar a que la aplicación haga una encuesta. Esto reduce la latencia de entrega para el procesamiento sensible al tiempo.
Capacidad de procesamiento y protección a la deriva El host recupera más eventos a medida que la capacidad de procesamiento está disponible. Combina los límites de escalado de aplicaciones con configuraciones de concurrencia de sondeo para enlazar el procesamiento simultáneo y proteger bases de datos o APIs posteriores. Los eventos pendientes permanecen en cola en el espacio de nombres del Conector, sujetos a sus límites de retención de eventos. Los eventos llegan independientemente de la capacidad de procesamiento disponible de la aplicación. Los límites de escala pueden provocar devoluciones de llamada limitadas o fallidas cuando la demanda supera la capacidad; los eventos pueden perderse si la entrega no tiene éxito dentro de los límites de reintento del servicio.
Redes entrantes No se requiere ningún endpoint de callback entrante. Puede restringir el acceso entrante a la aplicación de funciones permitiendo solicitudes salientes al punto final de sondeo del espacio de nombres del Connector. El espacio de nombres del conector debe poder acceder al endpoint de callback de la aplicación. Las restricciones de entrada deben permitir esas solicitudes.
Autenticación de identidad administrada El host de Funciones puede utilizar la identidad administrada asignada por el sistema o el usuario de la aplicación de funciones para recibir y reconocer eventos. Conceda a esa identidad una política de acceso en la conexión del conector gestionada. Para callbacks autenticados con Microsoft Entra ID, el Espacio de Nombres del Conector utiliza su identidad gestionada. Configura la autenticación integrada del Servicio de Aplicaciones en la aplicación de función receptora para validar los tokens. La autenticación predeterminada por webhook utiliza en su lugar la clave de sistema de extensión Connector.

Dependiendo de tu plan de alojamiento, puedes restringir el acceso entrante a la aplicación de funciones usando endpoints privados o restricciones de acceso de entrada, incluidas restricciones basadas en IP o restricciones de endpoint de servicio, sin impedir la sondeación. La aplicación debe seguir siendo capaz de realizar solicitudes HTTPS salientes al punto final de sondeo del Conector Namespace. Por separado, la identidad administrada configurada de la aplicación de funciones debe tener una política de acceso en la conexión del conector gestionado.

El modo de entrega de eventos controla cómo llegan los eventos al host de Funciones desde el espacio de nombres del Conector, no cómo detecta cambios en el servicio de origen el conector gestionado.

La entrega por Webhook escala como los disparadores HTTP, mientras que la entrega mediante sondeo utiliza escalado basado en objetivos. El objetivo de escalado de sondeo es independiente de la concurrencia de los oyentes y del tamaño del lote. Para detalles sobre ambos modos, consulte Escalado y concorrencia del Conector Trigger. Para la ecuación de escalado de sondeo y la configuración de ajuste, consulte Escalado basado en objetivos de conectores gestionados.

Ambos modos utilizan [ConnectorTrigger] el parámetro de función que recibe el cuerpo del evento y pueden utilizar los mismos modelos de carga útil. Para ejemplos de ambos modos de entrega, consulte los ejemplos del Disparador de Conectores.

Instalación de paquetes

Extensión de conector

El Conector Trigger es compatible con el modelo de worker aislado .NET. Para información sobre las versiones compatibles de .NET en las versiones de Azure Functions en tiempo de ejecución, véase Lenguajes por versión de ejecución.

Añade la versión 1.0.0 o posterior del paquete de extensión Connector a tu proyecto.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector

SDKs de Azure Connectors

Si tu función solo necesita realizar acciones en servicios externos y no necesita ser activada por eventos, usa únicamente el SDK de Azure Connectors. No necesitas el paquete de extensión Connector.

Agregue el SDK de Azure Connectors:

dotnet add package Azure.Connectors.Sdk

Para conectores populares, el SDK proporciona clientes con tipificación fuerte para invocar acciones de conectores desde tus funciones; consulta la referencia de la API Azure Connectors SDK para .NET.

Instalación de la extensión

Usa Node.js 24 o posterior. Ambos modos de entrega utilizan los ayudantes de registro de disparadores con el mismo nombre o genéricos.

Instala los paquetes usados por el disparador Connector:

npm install "@azure/functions@latest" "@azure/functions-extensions-connectors@latest" "@azure/connectors@latest"

Estos paquetes ofrecen la siguiente funcionalidad:

Configura el paquete de extensiones en el archivohost.json . El paquete suministra la extensión host del Conector para ambos modos de entrega:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Azure Connectors SDK

Si tu función solo necesita realizar acciones en servicios externos y no necesita ser activada por eventos, instala solo el SDK de Azure Connectors para Node.js. No necesitas los paquetes de disparadores Connector.

npm install "@azure/connectors@latest"

El SDK proporciona clientes con tipes fuertes para invocar acciones de conector desde tus funciones.

Para las versiones actuales de paquetes y proyectos completos, consulta los ejemplos de conectores de Azure Functions para TypeScript.

Ambos modos de entrega utilizan el @app.connector_trigger decorador. Para ejemplos, consulte Ejemplos de disparadores de conectores.

Instalación de la extensión

Añade los siguientes paquetes a requirements.txt:

azure-functions>=2.4.0
azurefunctions-extensions-connectors>=1.0.0

Note

Para versiones de Python anteriores a la 3.13, usa azure-functions>=1.27.0b1 en su lugar.

  • La biblioteca núcleo de Azure-functions de Python proporciona el decorador y puede vincular eventos únicos en bruto a str o bytes, o lotes de sondeo a typing.List[str] o typing.List[bytes].
  • El paquete azurefunctions-extensions-connectors integra el SDK Azure Connectors para Python y registra convertidores para anotaciones específicas de SDK de operación compatibles. Por ejemplo, emails: list[office365.GraphClientReceiveMessage], donde office365 se importa desde azurefunctions.extensions.connectors, recibe objetos de modelo de correo electrónico para la operación Office 365 OutlookOnNewEmailV3.

Configura el paquete de extensiones en el archivohost.json . El paquete suministra la extensión host del Conector para ambos modos de entrega:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Azure Connectors SDK

Si tu función solo necesita realizar acciones en servicios externos y no necesita ser activada por eventos, instala únicamente el SDK de Azure Connectors para Python. No necesitas los paquetes de disparadores Connector.

python -m pip install "azure-connectors>=1.0.0"

El SDK proporciona clientes con tipes fuertes para invocar acciones de conector desde tus funciones.

Para las versiones actuales de paquetes y proyectos completos, consulta los ejemplos de conectores de Azure Functions para Python.

configuración de host.json

La extensión Connector no requiere ajustes específicos de cada conector en el archivo host.json cuando usas los valores predeterminados.

Las siguientes secciones muestran los ajustes opcionales para cada modo de entrega.

Modo de encuesta

Configura los ajustes opcionales de sondeo en extensions.connector el archivo host.json . Por ejemplo, la siguiente configuración limita el retraso entre encuestas cuando no hay eventos disponibles a un segundo:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "maxPollingInterval": "00:00:01"
    }
  }
}
Property Default Description
defaultMaxBatchSize 1 Eventos máximos por invocación cuando la función no especifica una sobreescritura positiva del tamaño del lote. Los valores válidos son del 1 al 32. Los valores superiores a 1 requieren habilitar el procesamiento por lotes.
defaultMaxConcurrentCalls 16 Máximo de tareas simultáneas de procesamiento de evento único por oyente en una instancia, incluyendo preparación, invocación y acuse de reconocimiento. Debe ser positivo. No se aplica a invocaciones por lotes.
defaultTargetPendingEventThreshold 16 Segmenta eventos pendientes por instancia para escalar basado en objetivo cuando el entorno de ejecución no proporciona un destino de concurrencia. Debe ser positivo. Independiente del tamaño del lote y de la concurrencia de invocaciones.
maxPollingInterval "00:00:30" Retraso máximo entre encuestas cuando no hay eventos disponibles. Debe ser al menos un segundo. No controla con qué frecuencia el conector comprueba el servicio de origen.
maxLinkedOutputSizeInBytes 104857600 (100 MiB) Bytes máximos descargados por salida de evento vinculado. Debe ser positivo. No se aplica a las respuestas de encuestas en línea. Esto es una barrera de seguridad para descargar, no una garantía soportada de tamaño de carga útil.

Las sobrescrituras positivas por función tienen prioridad sobre los valores predeterminados correspondientes del host. El tiempo de ejecución puede anular el objetivo de escalado sin cambiar el tamaño del lote ni la concurrencia del listener. Los lotes se procesan uno a uno por oyente. Para las opciones específicas del idioma, consulta Modo de sondeo.

Los eventos de salida vinculada son descargados por el host y normalizados a la forma ordinaria de la carga útil. Se invocan un evento a la vez detrás de un limitador de host general, incluso cuando la vinculación permite la agrupación por lotes.

Aumentar maxLinkedOutputSizeInBytes puede agotar la memoria del huésped o del trabajador. Valida la carga de trabajo en el tamaño de tu hosting antes de aumentarla; el valor predeterminado no establece un límite de tamaño de carga útil soportado.

Modo webhook

La autenticación predeterminada por clave de sistema no requiere configuraciones específicas de conector en host.json. Si la autenticación integrada del servicio de aplicación valida las devoluciones de llamada, puedes configurar extensions.connector.system.webhookAuthorizationLevel para Anonymous desactivar la comprobación redundante de clave del sistema.

Úsalo Anonymous solo cuando otra capa de autenticación valida las solicitudes antes de que lleguen al host de Funciones. Para detalles de configuración y un ejemplo completo, consulte Autenticación integrada.

Uso de SDKs de conectores en tu código

El SDK de Conector permite que tu función llame a operaciones de conector como acciones salientes. La superficie cliente utiliza el mismo conector administrado subyacente en el Espacio de Nombres del Conector que desencadena el uso, por lo que un único conector gestionado puede alimentar tanto los disparadores entrantes como las llamadas salientes para la misma cuenta de servicio.

Autenticar callbacks de webhook entrantes no otorga permiso a la aplicación de funciones para realizar llamadas al SDK saliente. Para una función activada por webhook que también realiza llamadas al SDK, concede a la identidad administrada (desplegada) o a la identidad de desarrollador (local) de la aplicación una política de acceso para cada conexión de conector gestionada utilizada por esas llamadas.

Para el sondeo, la identidad administrada de la aplicación de función o la identidad del desarrollador ya necesita una política de acceso a conexión. Si el cliente SDK utiliza esa misma identidad y conexión, la política existente también permite llamadas SDK; no se necesita asignación adicional de directivas de acceso.

Tanto las funciones de sondeo como las de webhook deben pasar una credencial al cliente SDK, como se muestra a continuación.

En .NET, cada conector envía un cliente con tipo (por ejemplo, Office365Client, Office365UsersClient, TeamsClient) en Azure.Connectors.Sdk.{Service}. El constructor cliente toma la URL de ejecución de la conexión y una credencial.

El siguiente patrón procede del ejemplo de Teams de búsqueda de usuarios por correo electrónico de extremo a extremo:

using Azure.Core;
using Azure.Identity;
using Azure.Connectors.Sdk.Office365;
using Azure.Connectors.Sdk.Office365Users;
using Azure.Connectors.Sdk.Teams;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
{
    ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID")
});

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.AddSingleton<TokenCredential>(credential);

        services.AddSingleton(sp => new Office365Client(
            new Uri(Environment.GetEnvironmentVariable("OFFICE365_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));

        services.AddSingleton(sp => new Office365UsersClient(
            new Uri(Environment.GetEnvironmentVariable("OFFICE365USERS_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));

        services.AddSingleton(sp => new TeamsClient(
            new Uri(Environment.GetEnvironmentVariable("TEAMS_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));
    })
    .Build();

host.Run();

Este ejemplo crea un DefaultAzureCredential, lo registra como un TokenCredential, y lo pasa al constructor de cada cliente SDK a través de sp.GetRequiredService<TokenCredential>(). Localmente, la credencial puede usar tu inicio de sesión de desarrollador; en Azure, puede usar la identidad administrada de la aplicación de funciones. Establezca AZURE_CLIENT_ID el ID de cliente de una identidad administrada asignada por el usuario vinculada a la aplicación de funciones. Déjalo sin configurar para una identidad asignada por el sistema o inicio de sesión por parte del desarrollador local.

La configuración *_CONNECTION_RUNTIME_URL apunta al punto de conexión de tiempo de ejecución por conexión en el espacio de nombres del conector. Inyecte los clientes en la función y llame a métodos tipados como UserProfileAsync, GetEmailsAsync o FlagAsync. También puede invocar clientes del SDK desde desencadenadores que no son de conector (por ejemplo, un desencadenador HTTP que publica en Teams).

El siguiente extracto simplificado del ejemplo de correo electrónico a Teams utiliza el inyectado Office365Client para marcar un correo para su seguimiento. Llama a este asistente desde el código de procesamiento de tu función con el ID de mensaje del correo electrónico:

using Azure.Connectors.Sdk.Office365;
using Azure.Connectors.Sdk.Office365.Models;

public class ProcessEmail(Office365Client office365Client)
{
    public async Task FlagEmailAsync(string messageId)
    {
        await office365Client.FlagAsync(
            messageId: messageId,
            input: new UpdateEmailFlag { Flag = new { flagStatus = "flagged" } },
            originalMailboxAddress: null,
            cancellationToken: default);
    }
}

En Python, azure-connectors proporciona clientes tipados como Office365Client y TeamsClient. Pásale la URL de ejecución por conexión y una credencial al constructor cliente. Para la autenticación de Microsoft Entra ID, utilice una credencial asíncrona como azure.identity.aio.DefaultAzureCredential. Espera las operaciones del SDK.

En Node.js, @azure/connectors proporciona clientes tipados como Office365Client y TeamsClient. Pásame la URL de ejecución por conexión y una credencial, como DefaultAzureCredential from @azure/identity, al constructor del cliente. Espera las operaciones del SDK.