Utiliza conectores gestionados en Azure Functions

Al utilizar conectores gestionados, tus funciones pueden reaccionar a eventos y operaciones de llamada en servicios como Microsoft 365, Microsoft Teams, SharePoint y muchos sistemas de terceros sin necesidad de escribir código de configuración de webhook ni gestionar tokens OAuth. Azure Functions se integra con Azure Connector Namespace para proporcionar un desencadenador y un SDK que te permiten centrarte en la lógica de negocio, mientras que el espacio de nombres del conector se encarga de los webhooks, la autenticación y los reintentos.

Cómo los conectores mejoran las funciones

Un espacio de nombres de conectores añade dos capacidades al modelo de programación de Funciones:

• Desencadenadores de conector
  Una función se ejecuta cuando ocurre un evento en un servicio externo, como un nuevo correo electrónico en Microsoft 365, un archivo añadido a SharePoint o un mensaje publicado en Teams. El Integration Runtime expone un enlace connectorTrigger que recibe las respuestas de los webhooks procedentes del espacio de nombres del conector.
• Acciones del SDK del conector
  El código de la función invoca operaciones del conector a través de clientes del SDK. El SDK cubre conectores gestionados como Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint y OneDrive. Los conectores administrados que aún no tienen modelos de SDK se pueden invocar como puntos de conexión HTTP.

Puedes usar conectores gestionados junto con disparadores y vinculaciones clásicas de Functions como HTTP, temporizador, cola, Service Bus, Event Grid y Durable Functions.

Disponibilidad de vista previa

Cuándo usar conectores

Usa conectores cuando tus funciones necesiten interactuar principalmente con servicios externos en lugar de ejecutar lógica personalizada compleja. Considera estas formas de usar conectores gestionados en tus aplicaciones funcionales:

• Reaccionar a eventos externos
  Tu app debe gestionar eventos generados por servicios conectados externamente (correos electrónicos nuevos, invitaciones en el calendario, archivos, elementos de lista, actividad en Teams), pero no quieres gastar el esfuerzo en codificar registros de webhooks, validación de handshakes y actualizaciones de OAuth. Considera un caso en el que tu función procesa nuevos correos entregados en una carpeta Office 365 Outlook monitorizada, clasifica el mensaje, llama al Conector de Office 365 para enriquecimiento y marca o mueve el correo. Todo este trabajo distribuido lo realiza tu app sin tener que preocuparte nunca por los tokens de actualización, que se gestionan en el espacio de nombres de tu conector.

• Reemplazar clientes de servicios personalizados
  Tu código de función ya llama a Microsoft 365 o APIs de terceros usando clientes HTTP personalizados, lo que requiere que gestiones secretos, ámbitos y políticas de reintento en muchas conexiones, lo que puede convertirse rápidamente en una carga de mantenimiento. En su lugar, puedes usar los clientes tipados en los SDKs de conectores directamente en tu código de función y dejar que los conectores gestionados gestionen las conexiones por sí mismos.

• Aprovecha un despliegue de aplicación existente
  Ya has creado un proyecto de aplicación de funciones orientado a eventos con una pipeline de despliegue y herramientas de monitorización. Puedes usar conectores gestionados para añadir una nueva función externa basada en disparadores de servicio en el mismo proyecto y aprovechar la infraestructura existente. Por ejemplo, una aplicación de funciones que antes dependía de colas de mensajes o Logic Apps ahora puede reaccionar directamente a la actividad de Teams y conectarse a Office 365 para comprobaciones dentro de la organización y consultas de gestores.

• Flujos de trabajo de agentes
  Estás construyendo flujos de trabajo donde una función recibe un evento, razona con un modelo de IA y luego actúa de nuevo en un servicio externo mediante una operación de conector. Puedes aprovechar las habilidades alojadas en Azure Functions para programar tu flujo de trabajo agente, aprovechando al mismo tiempo los triggers gestionados basados en conectores y los SDKs gestionados de conectores.

• Control de código primero con integración gestionada
  Quieres conectores gestionados para simplificar la comunicación entrante y saliente con servicios externos, pero prefieres un modelo de programación centrado en el código y control total sobre la orquestación, incluyendo ramificaciones, gestión de la autenticación entre pasos y reutilización de tus bibliotecas existentes.

  Tip

  Cuando la carga de trabajo es pura orquestación entre conectores sin código personalizado, Logic Apps Standard sigue siendo la opción más sencilla. Para más información, consulta Relación con otras opciones de integración de Azure.

Relación con otras opciones de integración de Azure

Los conectores gestionados en Azure Functions son aditivos. La elección correcta depende de cuánto código personalizado necesite la carga de trabajo y si el equipo prefiere un diseñador visual o un código.

Una sola aplicación de funciones puede combinar los tres patrones. Puede agregar un desencadenador de conector a una aplicación con desencadenador HTTP existente y adoptar los clientes del SDK de forma incremental.

Paquetes y requisitos previos

Cada idioma compatible cuenta con un pequeño conjunto de paquetes que incluyen el enlace de activador y los clientes del SDK del conector.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector --prerelease
dotnet add package Azure.Connectors.Sdk --prerelease

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

pip install "azure-functions>=2.2.0b4"
pip install azurefunctions-extensions-connectors

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

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

Desencadenadores basados en conectores

Un disparador basado en conector gestionado ejecuta tu función cuando ocurre un evento en el servicio conectado. El espacio de nombres del conector envía el evento a su aplicación de funciones a través de HTTPS utilizando el punto de conexión webhook de la extensión del conector:

POST /runtime/webhooks/connector?functionName={FunctionName}&code={connector_extension_key}

az functionapp keys list \
    --resource-group <resource-group> \
    --name <function-app> \
    --query "systemKeys.connector_extension" \
    --output tsv

La configuración del desencadenador en su espacio de nombres del conector almacena esa URL de devolución de llamada y presenta la clave del sistema en cada devolución de llamada. El runtime de Functions valida la clave antes de ejecutar tu función. Para una configuración sin secretos compartidos, puedes poner la autenticación integrada de App Service delante de la app de funciones y validar un token de identidad gestionado desde el espacio de nombres del conector. Ver ejemplo .NET: autenticación integrada con identidad gestionada para el patrón completo.

Las cargas útiles de solicitud incluyen el cuerpo del evento, además de un conjunto de encabezados x-ms-* que identifican la configuración del disparador, la conexión, el tipo de evento y un identificador de correlación. Cuando el conector gestionado tiene un modelo SDK, el tiempo de ejecución deserializa la carga útil directamente en ese modelo. Para conectores gestionados sin SDKs de cliente, tu función recibe el cuerpo JSON en bruto.

En el ejemplo siguiente se muestra una función que se desencadena cuando llega un nuevo correo electrónico a un buzón de Office 365 Outlook. El registro del disparador es por idioma; La configuración del disparador en el espacio de nombres del conector es la misma en todos los casos.

using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Azure.Connectors.Sdk.Office365.Models;
using Microsoft.Extensions.Logging;

public class OnNewEmail
{
    private readonly ILogger<OnNewEmail> _logger;

    public OnNewEmail(ILogger<OnNewEmail> logger) => _logger = logger;

    [Function("OnNewEmail")]
    public IActionResult Run(
        [ConnectorTrigger()] Office365OnNewEmailTriggerPayload payload)
    {
        var emails = payload?.Body?.Value ?? [];
        foreach (var email in emails)
        {
            _logger.LogInformation(
                "Received email from {From} with subject '{Subject}'.",
                email.From, email.Subject);
        }

        return new OkResult();
    }
}

import azure.functions as func
import json
import logging

app = func.FunctionApp()

@app.function_name(name="OnNewEmail")
@app.connector_trigger(arg_name="payload")
def on_new_email(payload: str) -> None:
    data = json.loads(payload)
    emails = data.get("body", {}).get("value", [])
    for email in emails:
        logging.info(
            "Received email from %s with subject '%s'.",
            email.get("from"), email.get("subject"))

import azure.functions as func
import azurefunctions.extensions.connectors.office365 as office365
import logging

app = func.FunctionApp()

@app.function_name(name="OnNewEmail")
@app.connector_trigger(arg_name="email")
def on_new_email(email: office365.ClientReceiveMessage) -> None:
    logging.info(
        "Received email from %s with subject '%s'.",
        email.from_, email.subject)

import { InvocationContext } from '@azure/functions';
import {
    connectors,
    EmailTriggerContext,
} from '@azure/functions-extensions-connectors';

connectors.office365.onNewEmail('OnNewEmail', {
    handler: async (
        context: EmailTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        for (const email of context.emails) {
            invocationContext.log(
                `Received email from '${email.from}' with subject '${email.subject}'.`,
            );
        }
    },
});

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

app.connectorTrigger('OnNewItem', {
    handler: async (payload: unknown, context: InvocationContext) => {
        const data = typeof payload === 'string' ? JSON.parse(payload) : payload;
        const items: Record<string, unknown>[] = (data as any)?.body?.value ?? [];
        for (const item of items) {
            context.log(`Item ID: ${item.Id}`);
        }
    },
});

Creas la configuración del disparador en el espacio de nombres del conector usando la CLI de Azure, ARM o Bicep. Ese paso forma parte de la plataforma del conector y está documentado en el conjunto de contenidos del conector. Functions no envía sus propios comandos de configuración para el registro del desencadenador.

Autentique sus funciones en un espacio de nombres del conector

El modelo de autenticación por defecto utiliza una clave de sistema compartida (connector_extension) que el espacio de nombres del conector presenta en cada callback. Sin embargo, las claves compartidas no pueden tener un ámbito específico por desencadenador y requieren una rotación coordinada entre la aplicación de funciones y el espacio de nombres del conector. Para cargas de producción, en su lugar se utiliza la autenticación integrada de App Service (también llamada Easy Auth) con una identidad gestionada.

En este patrón, el espacio de nombres del conector utiliza su propia identidad administrada asignada por el sistema o asignada por el usuario para solicitar un token de Entra ID en cada devolución de llamada. La aplicación de función valida ese token, incluida su audiencia, el emisor y el identificador de objeto del autor de la llamada, antes de que ninguna solicitud llegue al host de Functions. Sin claves compartidas, sin secretos de cliente, en ningún lugar.

Para un ejemplo de funcionamiento de extremo a extremo, véase este repositorio: functions-connectors-net-builtinauth.

Configuración de la aplicación de funciones

La autenticación integrada se ejecuta en el límite del trabajador de App Service, antes de que el tiempo de ejecución de Functions reciba la solicitud. Se configura a través de la authsettingsV2 propiedad ARM o su equivalente en Bicep.

La aplicación de funciones también necesita una identidad administrada asignada por el usuario federada al registro de aplicaciones de Entra. La autenticación integrada usa esa credencial de identidad federada (FIC) para generar aserciones de cliente para la aplicación Entra sin almacenar un secreto del cliente. El patrón de bicep establece clientSecretSettingName en una configuración de aplicación que contiene el identificador de cliente de la MI asignada por el usuario, lo que indica a la autenticación integrada que use FIC en lugar de un secreto.

Dado que la autenticación integrada ya valida cada solicitud, puedes desactivar la comprobación redundante de clave de sistema , host.jsonque se parecería a este fragmento JSON:

{
    ...
    "extensions": {
        "connector": {
            "system": {
                "webhookAuthorizationLevel": "Anonymous"
            }
        }
    }
}

Configuración del espacio de nombres del conector

El espacio de nombres de su conector debe tener habilitada y asociada una identidad administrada asignada por el sistema o por el usuario. Cuando crees la configuración del trigger, especifica authentication.type = ManagedServiceIdentity y authentication.identity = <resource-id-of-managed-identity> para una identidad asignada por el usuario o omite identity una identidad asignada por el sistema. Especifique también authentication.audience = <entra-app-client-id> para que el tiempo de ejecución del conector sepa qué audiencia debe solicitar en el token.

El tiempo de ejecución del conector utiliza esa identidad administrada para generar un token de Entra ID en cada llamada de retorno. En este token, iss (emisor) es tu inquilino, aud (audiencia) es el ID de cliente de la app Entra, y oid (ID de objeto) es el ID principal de la identidad. La autenticación integrada valida los tres.

El recurso del espacio de nombres del conector también necesita acceso a la conexión, como una office365 conexión. Concede este acceso mediante una política de acceso que lista el ID principal de la identidad gestionada. El archivo de ejemplo bicep muestra la configuración completa tanto de la identidad del espacio de nombres como de la directiva de acceso a la conexión.

¿Qué se aplica?

La autenticación integrada valida los tokens en orden:

1. Presencia del token - Token ausente o caducado → 401
2. Firma: verificada con los JWKS del emisor para el inquilino
3. iss (emisor): debe coincidir openIdIssuer
4. aud (audiencia) - Debe estar en allowedAudiences
5. oid (object/principal ID): debe coincidir con una de las identidades de allowedPrincipals.identities. Cualquier otra identidad → 403

Como esta comprobación se ejecuta en el borde del Servicio de Aplicaciones, tu código de función nunca detecta una petición que no provenga de la identidad gestionada del espacio de nombres del conector. No necesitas ningún código de aplicación para la comprobación de acceso.

Flujo de autenticación

┌─────────────────────────────────────────────────────────────────┐
│  Connector namespace  (westcentralus)                           │
│  • System-assigned or user-assigned managed identity enabled    │
│  • Trigger config: authentication.type = ManagedServiceIdentity │
│                    authentication.audience = <Entra app ID>     │
│                    callbackUrl = https://<func>/runtime/…       │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         │  POST callbackUrl
                         │  Authorization: Bearer <AAD token>
                         │     iss = your tenant
                         │     aud = Entra app clientId
                         │     oid = managed identity principalId
                         ▼
┌──────────────────────────────────────────────────────────────┐
│  Function App  (any region)                                  │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐   │
│   │ Built-in authentication  (App Service edge)          │   │
│   │   • Validates signature, iss, aud, exp               │   │
│   │   • Checks oid ∈ allowedPrincipals.identities        │   │
│   │   → No token  → 401                                  │   │
│   │   → Wrong oid → 403                                  │   │
│   └────────────────────┬─────────────────────────────────┘   │
│                        │ pass                                │
│                        ▼                                     │
│   ┌──────────────────────────────────────────────────────┐   │
│   │ /runtime/webhooks/connector                          │   │
│   │   (webhookAuthorizationLevel = Anonymous)            │   │
│   └────────────────────┬─────────────────────────────────┘   │
│                        ▼                                     │
│   ┌──────────────────────────────────────────────────────┐   │
│   │ Your function(payload)                               │   │
│   └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
                         ▲
                         │ FIC (federated identity credential)
         ┌───────────────┴────────────────┐
         │  Entra app registration         │
         │  (federated to function-app MI) │
         └─────────────────────────────────┘

Contenido relacionado

• Autenticación y autorización en Azure App Service y Azure Functions
• Configuración de una aplicación de App Service o Azure Functions para usar el inicio de sesión de Microsoft Entra
• Configuración basada en archivos en la autenticación de Azure App Service
• Federación de identidades de carga de trabajo en Microsoft Entra ID
• Identidades administradas para recursos de Azure

Uso de conectores en el código

El SDK del conector permite que tu función llame a las operaciones del conector como acciones externas. La superficie de cliente utiliza el mismo conector administrado subyacente en el espacio de nombres del conector que activa el uso, por lo que un único conector administrado puede administrar tanto los desencadenantes entrantes como las llamadas salientes para la misma cuenta de servicio.

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();

Artículos relacionados

• Ejemplos de conectores de Azure Functions (índice canónico)
• Ejemplo de .NET de extremo a extremo: correo electrónico → búsqueda de usuario → Teams
• .NET ejemplo: autenticación integrada con identidad administrada
• Repositorio de la extensión del conector de Azure Functions
• Operaciones para asignación de firmas de Azure Functions
• Introducción a los conectores de Azure
• ¿Qué es el espacio de nombres del conector de Azure?
• Azure Functions alojaba habilidades en Azure Functions