Utilisez des connecteurs gérés dans Azure Functions

En utilisant des connecteurs gérés, vos fonctions peuvent réagir aux événements et aux opérations d’appel dans des services comme Microsoft 365, Microsoft Teams, SharePoint et de nombreux systèmes tiers sans écrire de code de configuration de webhook ni gérer des jetons OAuth. Azure Functions s’intègre à Azure Connector Namespace pour fournir un déclencheur et un SDK qui vous permet de vous concentrer sur la logique métier tandis que l’espace de noms du connecteur gère les webhooks, l’authentification et les tentatives.

Comment les connecteurs améliorent les fonctions

Un espace de noms de connecteur ajoute deux capacités au modèle de programmation des fonctions :

• Déclencheurs de connecteur
  Une fonction s’exécute lorsqu’un événement se produit dans un service externe, comme un nouvel email dans Microsoft 365, un fichier ajouté à SharePoint, ou un message posté sur Teams. L’environnement d’exécution expose une connectorTrigger liaison qui reçoit les appels de webhook provenant de l’espace de noms du connecteur.
• Actions du SDK du connecteur
  Votre code de fonction appelle les opérations de connecteur via des clients SDK. Le SDK couvre les connecteurs gérés tels que Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint et OneDrive. Les connecteurs gérés qui n’ont pas encore de modèles SDK peuvent être appelés comme terminaux HTTP.

Vous pouvez utiliser des connecteurs gérés en parallèle des déclencheurs et liaisons classiques de Functions tels que HTTP, minuterie, file d’attente, Service Bus, Event Grid et Durable Functions.

Aperçu de la disponibilité

Quand utiliser des connecteurs

Utilisez des connecteurs lorsque vos fonctions doivent principalement interagir avec des services externes plutôt que d’exécuter une logique personnalisée complexe. Considérez ces façons d’utiliser les connecteurs gérés dans vos applications fonctionnelles :

• Réagir aux événements extérieurs
  Votre application doit gérer les événements générés par des services connectés à l’externe (nouveaux e-mails, invitations au calendrier, fichiers, éléments de liste, activité Teams), mais vous ne voulez pas perdre d’efforts à coder des inscriptions webhook, valider des poignées de main et actualiser OAuth. Considérons un cas où votre fonction s’exécute pour traiter les nouveaux emails livrés dans un dossier Office 365 Outlook surveillé, classifie le message, appelle le connecteur Office 365 pour enrichissement, puis signale ou déplace l’email. Tout ce travail distribué est effectué par votre application sans jamais avoir à vous soucier des tokens de rafraîchissement, qui sont gérés par votre espace de noms de connecteurs.

• Remplacer les clients de service personnalisé
  Votre code de fonction appelle déjà Microsoft 365 ou des API tierces en utilisant des clients HTTP personnalisés, ce qui vous oblige à gérer des secrets, des scopes et des politiques de réessayage sur de nombreuses connexions, ce qui peut rapidement devenir un fardeau de maintenance. Vous pouvez plutôt utiliser les clients typés dans les SDK de connecteurs directement dans votre code de fonction et laisser les connecteurs gérés gérer eux-mêmes les connexions.

• Tirez parti d’un déploiement d’application existant
  Vous avez déjà construit un projet d’application fonctionnelle axée sur les événements avec un pipeline de déploiement et des outils de surveillance. Vous pouvez utiliser des connecteurs gérés pour ajouter une nouvelle fonction de déclencheur de service externe dans le même projet et tirer parti de l’infrastructure existante. Par exemple, une application fonctionnelle qui s’appuyait auparavant sur des files de messages ou des applications logiques peut désormais réagir directement à l’activité Teams et se connecter à Office 365 pour des vérifications en interne et des recherches de gestionnaires.

• Flux de travail agentiques
  Vous construisez des flux de travail où une fonction reçoit un événement, raisonne avec un modèle d’IA, puis réagit en service externe via une opération de connecteur. Vous pouvez exploiter les compétences hébergées d’Azure Functions pour programmer votre workflow agentique tout en bénéficiant toujours des déclencheurs basés sur des connecteurs gérés et des SDK de connecteurs gérés.

• Contrôle orienté code avec intégration managée
  Vous voulez des connecteurs gérés pour simplifier la communication entrante et sortante avec un service externe, mais vous préférez un modèle de programmation axé sur le code et un contrôle total de l’orchestration, y compris le branchement, la gestion de l’authentification entre les étapes et la réutilisation de vos bibliothèques existantes.

  Tip

  Lorsque la charge de travail est une orchestration pure entre connecteurs sans code personnalisé, Logic Apps Standard reste le choix le plus simple. Pour plus d’informations, voir Relation avec d’autres options d’intégration Azure.

Relation avec d’autres options d’intégration Azure

Les connecteurs gérés dans Azure Functions sont additifs. Le bon choix dépend de la quantité de code personnalisé dont la charge de travail a besoin et si l’équipe préfère un designer visuel ou du code.

Une application de fonction unique peut combiner les trois modèles. Vous pouvez ajouter un déclencheur de connecteur à une application existante avec déclencheur HTTP et adopter progressivement des clients SDK.

Packages et prérequis

Chaque langage pris en charge dispose d’un petit nombre de packages qui incluent la liaison de déclenchement et les clients connecteurs typés.

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

Déclencheurs basés sur le connecteur

Un déclencheur géré basé sur un connecteur exécute votre fonction lorsqu’un événement se produit dans le service connecté. L’espace de noms du connecteur transmet l’événement à votre application de fonction via le point de terminaison webhook de l’extension du connecteur :

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 configuration des déclencheurs dans votre espace de noms de connecteur stocke cette URL de rappel et présente la clé système à chaque rappel. L’exécution des fonctions valide la clé avant d’exécuter votre fonction. Pour une configuration sans secrets partagés, vous pouvez placer l’authentification intégrée des services App devant l’application fonctionnelle et valider un jeton d’identité géré depuis l’espace de noms du connecteur. Voir exemple .NET : authentification intégrée avec identité gérée pour le motif complet.

Les charges utiles de requête portent le corps de l’événement ainsi qu’un ensemble d’en-têtes x-ms-* qui identifient la configuration du déclencheur, la connexion, le type d’événement et un ID de corrélation. Lorsque le connecteur géré possède un modèle SDK, l’exécution désérialise directement la charge utile dans ce modèle. Pour les connecteurs gérés sans SDK client, votre fonction reçoit le corps JSON brut.

L’exemple suivant montre une fonction qui se déclenche lorsqu’un nouvel e-mail arrive dans une boîte aux lettres Office 365 Outlook. L’enregistrement des déclencheurs est par langue ; La configuration des déclencheurs dans l’espace de noms du connecteur est la même dans tous les cas.

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}`);
        }
    },
});

Vous créez la configuration du déclencheur dans l’espace de noms du connecteur en utilisant l’interface Azure CLI, ARM ou Bicep. Cette étape fait partie de la plateforme du connecteur et est documentée dans l’ensemble de contenu du connecteur. Functions n’inclut pas ses propres commandes de configuration pour l’enregistrement du déclencheur.

Authentifiez vos fonctions auprès de l’espace de noms du connecteur

Le modèle d’authentification par défaut utilise une clé système partagée (connector_extension) que l’espace de noms du connecteur présente à chaque rappel. Cependant, les clés partagées ne peuvent pas être limitées par déclencheur et nécessitent une rotation coordonnée entre l’application de fonctions et l’espace de noms du connecteur. Pour les charges de travail, utilisez plutôt l’authentification intégrée des services App (également appelée Easy Auth) avec une identité gérée.

Dans ce schéma, l’espace de noms du connecteur utilise sa propre identité managée attribuée par le système ou l’utilisateur pour demander un jeton Entra ID pour chaque rappel. L’application de fonction valide ce jeton, y compris son audience, son émetteur et l’ID d’objet de l’appelant avant qu’une requête n’atteigne l’hôte Functions. Aucune clé partagée, aucun secret client, n’importe où.

Pour un exemple fonctionnel de bout en bout, voir ce dépôt : functions-connectors-net-builtinauth.

Configuration de l’application de fonction

L’authentification intégrée s’effectue au niveau du worker App Service, avant que l’environnement d’exécution de Functions ne reçoive la requête. Vous le configurez via la authsettingsV2 propriété ARM ou son équivalent dans Bicep.

L’application de fonction a également besoin d’une identité gérée attribuée par l’utilisateur fédérée à l’enregistrement d’application Entra. L’authentification intégrée utilise cette information d’identification fédérée (FIC) pour générer des assertions client pour l’application Entra sans stocker de secret client. Le modèle Bicep définit clientSecretSettingName comme un paramètre d’application qui contient l’ID client de l’identité gérée attribuée par l’utilisateur, afin d’indiquer à l’authentification intégrée d’utiliser FIC au lieu d’un secret.

Puisque l’authentification intégrée valide déjà chaque requête, vous pouvez désactiver la vérification de clé système redondante , host.jsonqui ressemblerait à ce fragment JSON :

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

Configuration de l’espace de noms des connecteurs

Votre espace de noms du connecteur doit disposer d’une identité gérée attribuée par le système ou par l’utilisateur, activée et associée. Lorsque vous créez la configuration du déclencheur, spécifiez authentication.type = ManagedServiceIdentity et authentication.identity = <resource-id-of-managed-identity> pour une identité attribuée par l’utilisateur ou omettez identity une identité assignée par le système. Vous spécifiez également authentication.audience = <entra-app-client-id> pour que l’environnement d’exécution du connecteur sache quelle audience demander dans le jeton.

Le runtime du connecteur utilise cette identité gérée pour générer un jeton Entra ID à chaque callback. Dans ce jeton, iss (émetteur) est votre locataire, aud (audience) est l’identifiant client de l’application Entra, et oid (identifiant d’objet) est l’identifiant principal de l’identité. L’authentification intégrée valide les trois.

La ressource d’espace de noms de connecteur doit également avoir accès à la connexion, par exemple une connexion office365. Accordez cet accès via une politique d’accès qui indique l’ID principal de l’identité gérée. L’exemple de fichier bicep montre le câblage complet pour l’identité de l’espace de noms et la stratégie d’accès aux connexions.

Qu’est-ce qui est appliqué ?

L’authentification intégrée valide les jetons dans l’ordre :

1. Présence de jeton - Jeton manquant ou expiré → 401
2. Signature : vérifié par rapport au jeu de clés web de l’émetteur pour votre locataire
3. iss (émetteur) - Doit correspondre openIdIssuer
4. aud (audience)  – Doit être dans allowedAudiences
5. oid (ID d’objet/principal) : doit correspondre à l’une des identités dans allowedPrincipals.identities. Toute autre identité → 403

Comme cette vérification s’exécute à la périphérie d’App Service, votre code de fonction ne voit jamais passer de requête qui ne provienne pas de l’identité managée de l’espace de noms du connecteur. Vous n’avez pas besoin d’aucun code d’application pour le contrôle d’accès.

Flux d’authentification

┌─────────────────────────────────────────────────────────────────┐
│  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) │
         └─────────────────────────────────┘

Contenu connexe

• Authentification et autorisation dans Azure App Service et Azure Functions
• Configurer votre application App Service ou Azure Functions pour utiliser la connexion à Microsoft Entra
• Configuration basée sur des fichiers dans l’authentification Azure App Service
• Fédération des identités de charge de travail dans Microsoft Entra ID
• Identités managées pour les ressources Azure

Utilisation de connecteurs dans votre code

Le SDK du connecteur permet à votre fonction d’appeler les opérations du connecteur comme des actions sortantes. La surface client utilise le même connecteur géré sous-jacent dans l’espace de noms du connecteur qui déclenche l’utilisation, de sorte qu’un seul connecteur géré peut alimenter à la fois les déclencheurs entrants et les appels sortants pour le même compte de service.

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

Articles connexes

• Exemples de connecteurs Azure Functions (index canonique)
• Exemple .NET de bout en bout : e-mail → recherche d’utilisateur → Teams
• exemple .NET : authentification intégrée avec une identité managée
• Dépôt de l’extension de connecteur Azure Functions
• Mappage des opérations vers les signatures Azure Functions
• Vue d’ensemble des connecteurs Azure
• Qu’est-ce que l’espace de noms connecteur Azure ?
• Azure Functions hébergeait les compétences dans Azure Functions