Gebruik beheerde connectoren in Azure Functions

Door managed connectors te gebruiken, kunnen je functies reageren op gebeurtenissen en oproepoperaties in diensten zoals Microsoft 365, Microsoft Teams, SharePoint en veel derdepartijsystemen zonder webhook-setupcode te schrijven of OAuth-tokens te beheren. Azure Functions integreert met de Azure Connector Namespace om een trigger en een SDK te bieden waarmee je je kunt richten op bedrijfslogica, terwijl de connector-naamruimte webhooks, authenticatie en herpogingen afhandelt.

Hoe connectoren functies verbeteren

Een connectornaamruimte voegt twee mogelijkheden toe aan het Functions-programmeermodel:

• Connectortriggers
  Een functie draait wanneer een gebeurtenis plaatsvindt in een externe dienst, zoals een nieuwe e-mail in Microsoft 365, een bestand toegevoegd aan SharePoint, of een bericht dat in Teams wordt geplaatst. De runtime maakt een connectorTrigger binding bloot die webhook-callbacks ontvangt vanuit de connectornaamruimte.
• Connector SDK-acties
  Je functiecode roept connectoroperaties aan via SDK-clients. De SDK omvat beheerde connectors zoals Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint en OneDrive. Beheerde connectors die nog geen SDK-modellen hebben, zijn aanroepbaar als HTTP-eindpunten.

Je kunt managed connectors gebruiken naast klassieke Functions-triggers en bindings zoals HTTP, timer, queue, Service Bus, Event Grid en Durable Functions.

Beschikbaarheid van de preview

Wanneer connectors gebruiken

Gebruik connectors wanneer je functies vooral moeten interageren met externe diensten in plaats van complexe, aangepaste logica. Overweeg deze manieren om managed connectors in je functie-apps te gebruiken:

• Reageer op externe gebeurtenissen
  Je app moet gebeurtenissen verwerken die worden gegenereerd door extern verbonden diensten (nieuwe e-mails, agenda-uitnodigingen, bestanden, lijstitems, Teams-activiteit), maar je wilt geen moeite steken in het coderen van webhook-registraties, handshake-validatie en OAuth-verversingen. Stel je een situatie voor waarin je functie nieuwe e-mails verwerkt die in een gemonitorde Office 365 Outlook worden geleverd, het bericht classificeert, de Office 365-connector oproept voor verrijking, en de e-mail markeert of verplaatst. Al dit gedistribueerde werk wordt door je app gedaan zonder je ooit zorgen te hoeven maken over vernieuwingstokens, want die worden afgehandeld door je connectornaamruimte.

• Vervang aangepaste serviceclients
  Je functiecode roept al Microsoft 365 of externe API's aan met behulp van aangepaste HTTP-clients, wat vereist dat je secrets, scopes en retry-policies beheert over veel verbindingen, wat snel een onderhoudslast kan worden. Je kunt in plaats daarvan de getypeerde clients in connector-SDK's direct in je functiecode gebruiken en beheerde connectoren de verbindingen zelf laten afhandelen.

• Maak gebruik van een bestaande app-implementatie
  Je hebt al een event-driven function app-project gebouwd met een deployment-pijplijn en monitoringtools. Je kunt managed connectors gebruiken om een nieuwe externe service-triggerfunctie in hetzelfde project toe te voegen en zo gebruik te maken van de bestaande infrastructuur. Een functie-app die vroeger vertrouwde op berichtwachtrijen of Logic Apps kan nu direct reageren op Teams-activiteit en verbinding maken met Office 365 voor interne controles en manager-opzoekingen.

• Agentische werkstromen
  Je bouwt workflows waarbij een functie een gebeurtenis ontvangt, redeneert met een AI-model, en vervolgens via een connectoroperatie terugwerkt naar een externe service. Je kunt gebruikmaken van de door Azure Functions gehoste vaardigheden om je agentische workflow te programmeren, terwijl je toch gebruikmaakt van managed connector-gebaseerde triggers en managed connector SDK's.

• Code-eerst besturing met beheerde integratie
  Je wilt beheerde connectoren om inkomende en uitgaande communicatie met externe diensten te vereenvoudigen, maar je geeft de voorkeur aan een code-first programmeermodel en volledige controle over de orkestratie, inclusief vertakkingen, het beheren van authenticatie tussen stappen en het hergebruiken van je bestaande bibliotheken.

  Tip

  Wanneer de werklast pure orkestratie is over connectors zonder aangepaste code, blijft Logic Apps Standard de eenvoudigste keuze. Voor meer informatie, zie Relatie tot andere Azure-integratieopties.

Relatie met andere Azure-integratieopties

Beheerde connectors in Azure Functions zijn additief. De juiste keuze hangt af van hoeveel custom code de workload nodig heeft en of het team liever een visual designer of code heeft.

Eén functie-app kan alle drie de patronen combineren. U kunt een connectortrigger toevoegen aan een bestaande HTTP-trigger-app en SDK-clients incrementeel implementeren.

Pakketten en vereisten

Elke ondersteunde taal heeft een kleine set pakketten die de triggerbinding en de connector SDK-clients binnenbrengen.

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

Connectorgebaseerde triggers

Een beheerde connector-gebaseerde trigger voert uw functie uit wanneer er een gebeurtenis plaatsvindt in de verbonden dienst. De naamruimte van de connector levert de gebeurtenis via HTTPS aan je functie-app met behulp van het webhook-eindpunt van de connector-extensie:

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

De triggerconfiguratie in je connector-naamruimte slaat die callback-URL op en presenteert de systeemsleutel bij elke callback. De Functions-runtime valideert de sleutel voordat je functie wordt uitgevoerd. Voor een configuratie zonder gedeelde geheimen kun je de ingebouwde verificatie van App Service vóór de functie-app plaatsen en een token van een beheerde identiteit uit de naamruimte van de connector valideren. Zie .NET-voorbeeld: ingebouwde authenticatie met beheerde identiteit voor het volledige patroon.

Payloads van aanvragen bevatten de hoofdtekst van de gebeurtenis plus een reeks x-ms-* headers die de triggerconfiguratie, de verbinding, het gebeurtenistype en een correlatie-id identificeren. Wanneer de managed connector een SDK-model heeft, deserialiseert de runtime de payload direct in dat model. Voor beheerde connectors zonder client SDK's ontvangt je functie de ruwe JSON-body.

In het volgende voorbeeld ziet u een functie die wordt geactiveerd wanneer een nieuwe e-mail binnenkomt in een Office 365 Outlook postvak. De triggerregistratie is per taal; De triggerconfiguratie in de connectornaamruimte is in alle gevallen hetzelfde.

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

Je maakt de triggerconfiguratie aan in de connectornaamruimte door gebruik te maken van de Azure CLI, ARM of Bicep. Die stap maakt deel uit van het connectorplatform en wordt vastgelegd in de contentset van de connector. Functions verzendt geen eigen configuratieopdrachten voor triggerregistratie.

Authenticeer je functies in een connectornaamruimte

Het standaardauthenticatiemodel gebruikt een gedeelde systeemsleutel (connector_extension) die de naamruimte van de connector bij elke callback presenteert. Gedeelde sleutels kunnen echter niet per trigger worden beperkt en vereisen gecoördineerde rotatie tussen de functie-app en de naamruimte van de connector. Voor productieworkloads gebruik je in plaats daarvan App Service ingebouwde authenticatie (ook wel Easy Auth genoemd) met een beheerde identiteit.

In dit patroon gebruikt de connectornaamruimte zijn eigen systeem- of door de gebruiker toegewezen beheerde identiteit om voor elke callback een Entra ID-token aan te vragen. De functie-app valideert het token, inclusief de audience, issuer en de object-id van de aanroeper, voordat een verzoek de Functions-host bereikt. Geen gedeelde sleutels, geen clientgeheimen, overal.

Bekijk deze repository voor een volledig werkend voorbeeld: functions-connectors-net-builtinauth.

Configuratie van functie-app

Ingebouwde verificatie vindt plaats op de grens van de App Service-worker, voordat de Functions-runtime het verzoek ontvangt. Je configureert het via de authsettingsV2 ARM-eigenschap of het equivalent daarvan in Bicep.

De functie-app heeft ook een door de gebruiker toegewezen beheerde identiteit nodig die is gefedereerd aan de Entra-app-registratie. Ingebouwde authenticatie gebruikt die federatieve identiteitsreferentie (FIC) om clientverklaringen voor de Entra-app te genereren zonder een clientgeheim op te slaan. Met het Bicep-patroon wordt clientSecretSettingName ingesteld op een toepassingsinstelling die de client-id van de door de gebruiker toegewezen MI bevat, waardoor ingebouwde verificatie FIC gebruikt in plaats van een clientgeheim.

Omdat de ingebouwde authenticatie elk verzoek al valideert, kun je in host.json de redundante controle op de systeemsleutel uitschakelen; dat zou eruitzien als dit JSON-fragment:

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

Connector-naamruimteconfiguratie

De naamruimte van uw connector moet een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit ingeschakeld en gekoppeld hebben. Wanneer je de triggerconfiguratie maakt, specificeer je authentication.type = ManagedServiceIdentity en authentication.identity = <resource-id-of-managed-identity> voor een door de gebruiker toegewezen identiteit, of laat je identity weg voor een door het systeem toegewezen identiteit. Specificeer ook authentication.audience = <entra-app-client-id>, zodat de connectorruntime weet voor welke doelgroep het token moet worden aangevraagd.

De connector-runtime gebruikt die beheerde identiteit om bij elke callback een Entra ID-token te genereren. In dit token iss is (uitgever) je tenant, aud (audience) de Client-ID van de Entra-app, en oid (object-ID) de hoofd-ID van de identiteit. Ingebouwde verificatie valideert alle drie.

De connector-naamruimteresource heeft ook toegang nodig tot de verbinding, zoals een office365 verbinding. Verleen deze toegang via een toegangsbeleid dat de hoofd-ID van de beheerde identiteit vermeldt. Het voorbeeld-Bicep-bestand bevat de volledige configuratie voor zowel de identiteit van de naamruimte als het toegangsbeleid voor de verbinding.

Wat wordt afgedwongen

Ingebouwde verificatie valideert tokens in volgorde:

1. Aanwezigheid van token - Ontbrekend of verlopen token → 401
2. Handtekening - Geverifieerd aan de hand van de JWKS van de uitgever voor uw tenant
3. iss (uitgever) - Moet overeenkomen openIdIssuer
4. aud (doelgroep) - Moet in allowedAudiences
5. oid (object/principal-id): moet overeenkomen met een van de identiteiten in allowedPrincipals.identities. Elke andere identiteit → 403

Omdat deze controle aan de rand van de App Service draait, ziet je functiecode nooit een verzoek dat niet afkomstig is van de beheerde identiteit van de connectornaamruimte. Je hebt geen applicatiecode nodig voor de toegangscontrole.

Authenticatiestroom

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

Verwante inhoud

• Verificatie en autorisatie in Azure App Service en Azure Functions
• Uw App Service- of Azure Functions-app configureren voor het gebruik van Microsoft Entra-aanmelding
• Configuratie op basis van bestanden in Azure App Service-verificatie
• Federatie van workloadidentiteiten in Microsoft Entra ID
• beheerde identiteiten voor Azure-resources

Connectors in uw code gebruiken

De connector SDK stelt je functie in staat om connectorbewerkingen als uitgaande acties aan te roepen. Het clientoppervlak gebruikt dezelfde onderliggende beheerde connector in de connectornaamruimte die het gebruik triggert, zodat één beheerde connector zowel inkomende triggers als uitgaande oproepen voor hetzelfde serviceaccount kan voeden.

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

Verwante artikelen

• Azure Functions connectorvoorbeelden (canonieke index)
• End-to-end .NET voorbeeld: e-mail → gebruikerszoekactie → Teams
• .NET voorbeeld: ingebouwde verificatie met beheerde identiteit
• Opslagplaats voor Azure Functions-connector-extensie
• Bewerkingen voor Azure Functions handtekeningtoewijzing
• Overzicht van Azure-connectors
• Wat is Azure Connector-naamruimte?
• Gehoste vaardigheden in Azure Functions