Verwenden Sie verwaltete Connectors in Azure Functions

Durch die Verwendung von verwalteten Connectors können Ihre Funktionen auf Ereignisse und Anrufoperationen in Diensten wie Microsoft 365, Microsoft Teams, SharePoint und vielen Drittanbietersystemen reagieren, ohne Webhook-Setup-Code schreiben oder OAuth-Tokens verwalten zu müssen. Azure Functions integriert sich mit dem Azure Connector Namespace, um einen Trigger und ein SDK bereitzustellen, das es ermöglicht, sich auf die Geschäftslogik zu konzentrieren, während der Connector-Namensraum Webhooks, Authentifizierung und Retries übernimmt.

Wie Verbinder Funktionen verbessern

Ein Connector-Namensraum fügt dem Functions-Programmiermodell zwei Funktionen hinzu:

• Konnektor-Auslöser
  Eine Funktion wird ausgeführt, wenn ein Ereignis in einem externen Dienst auftritt, wie etwa eine neue E-Mail in Microsoft 365, eine zu SharePoint hinzugefügte Datei oder eine in Teams gepostete Nachricht. Die Laufzeit stellt eine connectorTrigger-Bindung bereit, die Webhook-Rückrufe aus dem Namensbereich des Connectors empfängt.
• Connector-SDK-Aktionen
  Dein Funktionscode ruft Connector-Operationen über SDK-Clients auf. Das SDK deckt verwaltete Connectoren wie Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint und OneDrive ab. Managed Connectors, die noch keine SDK-Modelle besitzen, können als HTTP-Endpunkte aufgerufen werden.

Sie können verwaltete Connectors neben klassischen Functions-Triggern und -Bindungen wie HTTP, Timer, Warteschlange, Service Bus, Event Grid und Durable Functions verwenden.

Verfügbarkeit der Vorschau

Wann Connectors verwendet werden sollten

Verwende Connectors, wenn deine Funktionen hauptsächlich mit externen Diensten interagieren müssen, anstatt komplexe, benutzerdefinierte Logik auszuführen. Betrachten Sie folgende Möglichkeiten, Managed Connectors in Ihren Funktions-Apps zu verwenden:

• Reaktion auf äußere Ereignisse
  Ihre App muss Ereignisse verarbeiten, die von extern verbundenen Diensten ausgelöst werden (neue E-Mails, Kalendereinladungen, Dateien, Listeneinträge, Teams-Aktivitäten), aber Sie möchten keinen Aufwand für Webhook-Registrierungen, Handshake-Validierung und OAuth-Aktualisierungen investieren. Betrachten Sie einen Fall, in dem Ihre Funktion neue E-Mails verarbeitet, die in einem überwachten Office 365 Outlook-Ordner geliefert werden, die Nachricht klassifiziert, die Office 365-Connector zur Anreicherung aufruft und die E-Mail markiert oder verschiebt. All diese verteilte Arbeit wird von Ihrer App erledigt, ohne sich jemals um Refresh-Tokens kümmern zu müssen, die von Ihrem Connector-Namensraum übernommen werden.

• Ersetzen von benutzerdefinierten Service-Clients
  Ihr Funktionscode ruft bereits Microsoft 365 oder Drittanbieter-APIs mit benutzerdefinierten HTTP-Clients auf, was bedeutet, dass Sie Geheimnisse, Scopes und Retry-Richtlinien über viele Verbindungen hinweg verwalten müssen, was schnell zu einer Wartungslast werden kann. Stattdessen können Sie die getypten Clients in Connector-SDKs direkt in Ihrem Funktionscode verwenden und verwaltete Connectors die Verbindungen selbst verwalten lassen.

• Nutzen Sie eine bestehende App-Bereitstellung
  Du hast bereits ein ereignisgesteuertes Funktions-App-Projekt mit einer Deployment-Pipeline und Monitoring-Tools entwickelt. Sie können verwaltete Connectors verwenden, um eine neue externe Service-Trigger-basierte Funktion im selben Projekt hinzuzufügen und die bestehende Infrastruktur zu nutzen. Zum Beispiel kann eine Funktions-App, die früher auf Nachrichtenwarteschlangen oder Logic Apps angewiesen war, jetzt direkt auf Teams-Aktivitäten reagieren und sich mit Office 365 verbinden, um interne Kontrolle und Manager-Abfragen durchzuführen.

• Agentische Arbeitsabläufe
  Man baut Workflows, bei denen eine Funktion ein Ereignis empfängt, mit einem KI-Modell argumentiert und dann über eine Connector-Operation in einen externen Dienst zurückreagiert. Du kannst die von Azure Functions gehosteten Fähigkeiten nutzen, um deinen agentischen Workflow zu programmieren und dabei weiterhin von Managed Connector-basierten Triggern und Managed Connector SDKs zu profitieren.

• Code-First-Steuerung mit verwalteter Integration
  Sie möchten verwaltete Connectors, um die eingehende und ausgehende Kommunikation mit externen Diensten zu vereinfachen, bevorzugen aber ein code-basiertes Programmiermodell und volle Kontrolle über die Orchestrierung, einschließlich Verzweigungen, Authentifizierung zwischen Schritten und Wiederverwendung Ihrer bestehenden Bibliotheken.

  Tip

  Wenn die Arbeitslast reine Orchestrierung über Connectors hinweg ohne benutzerdefinierten Code ist, bleibt Logic Apps Standard die einfachste Wahl. Weitere Informationen finden Sie unter Beziehung zu anderen Azure-Integrationsoptionen.

Beziehung zu anderen Azure Integrationsoptionen

Verwaltete Konnektoren in Azure Functions sind zusätzlich verfügbar. Die richtige Wahl hängt davon ab, wie viel individueller Code die Arbeitslast benötigt und ob das Team einen Visual Designer oder Code bevorzugt.

Eine einzelne Funktions-App kann alle drei Muster kombinieren. Sie können einer vorhandenen App mit HTTP-Auslöser einen Connectorauslöser hinzufügen und SDK-Clients schrittweise einführen.

Pakete und Voraussetzungen

Jede unterstützte Sprache hat eine kleine Menge von Paketen, die die Trigger-Bindung und die Connector-SDK-Clients einführen.

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

Connectorbasierte Auslöser

Ein gesteuerter Connector-basierter Trigger führt Ihre Funktion aus, wenn ein Ereignis im verbundenen Dienst auftritt. Der Connector-Namensraum liefert das Ereignis über HTTPS an Ihre Funktions-App, indem er den Webhook-Endpunkt der Connector-Erweiterung verwendet:

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

Die Trigger-Konfiguration in deinem Connector-Namensraum speichert diese Callback-URL und präsentiert den Systemschlüssel bei jedem Callback. Die Functions-Laufzeit validiert den Schlüssel, bevor sie deine Funktion ausführt. Für ein Setup ohne geteilte Geheimnisse kann man die integrierte App Service-Authentifizierung vor die Funktions-App legen und ein verwaltetes Identitätstoken aus dem Connector-Namensraum validieren. Siehe .NET-Beispiel: integrierte Authentifizierung mit verwalteter Identität für das vollständige Muster.

Anforderungsnutzlasten tragen den Ereignistext sowie eine Reihe von x-ms-* Headern, die die Triggerkonfiguration, die Verbindung, den Ereignistyp und eine Korrelations-ID identifizieren. Wenn der verwaltete Connector über ein SDK-Modell verfügt, deserialisiert die Laufzeit die Payload direkt in dieses Modell. Bei verwalteten Connectors ohne Client-SDKs erhält Ihre Funktion den rohen JSON-Körper.

Das folgende Beispiel zeigt eine Funktion, die ausgelöst wird, wenn eine neue E-Mail in einem Office 365 Outlook Postfach eintrifft. Die Trigger-Registrierung erfolgt pro Sprache; Die Trigger-Konfiguration im Connector-Namensraum ist in allen Fällen gleich.

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

Du erstellst die Trigger-Konfiguration im Connector-Namensraum mit der Azure CLI, ARM oder Bicep. Dieser Schritt ist Teil der Connector-Plattform und ist in der Inhaltssammlung zu den Connectors dokumentiert. Funktionen liefern keine eigenen Konfigurationsbefehle für die Triggerregistrierung.

Authentifizieren Sie Ihre Funktionen in einem Connector-Namensraum

Das Standard-Authentifizierungsmodell verwendet einen gemeinsamen Systemschlüssel (connector_extension), den der Connector-Namensraum bei jedem Rückruf präsentiert. Allerdings können gemeinsam genutzte Schlüssel nicht auf einzelne Trigger eingegrenzt werden und erfordern eine koordinierte Rotation zwischen der Funktions-App und dem Namespace des Connectors. Für Produktionsworkloads verwenden Sie stattdessen die integrierte App Service-Authentifizierung (auch Easy Auth genannt) mit einer verwalteten Identität.

In diesem Muster verwendet der Connector-Namensraum seine eigene systemzugeordnete oder benutzerzugewiesene verwaltete Identität, um für jeden Rückruf ein Entra ID-Token anzufordern. Die Function App überprüft dieses Token einschließlich seiner Zielgruppe, seines Ausstellers und der Objekt-ID des Aufrufers, bevor eine Anforderung den Functions-Host erreicht. Keine freigegebenen Schlüssel, keine geheimen Clientschlüssel, überall.

Ein End-to-End-Arbeitsbeispiel finden Sie in diesem Repository: functions-connectors-net-builtinauth.

Konfiguration von Funktions-Apps

Die integrierte Authentifizierung wird an der Grenze des App Service-Workers ausgeführt, bevor die Functions-Laufzeitumgebung die Anfrage empfängt. Du konfigurierst es über die authsettingsV2 ARM-Eigenschaft oder deren Äquivalent in Bicep.

Die Funktions-App benötigt auch eine vom Benutzer zugewiesene verwaltete Identität , die mit der Entra-App-Registrierung verbunden ist. Die integrierte Authentifizierung verwendet diese föderierte Identitätsnachweis (FIC), um Client-Assertions für die Entra-App zu generieren, ohne ein Client-Geheimnis zu speichern. Das Bicep-Muster setzt clientSecretSettingName auf eine App-Einstellung, die die Client-ID der dem Benutzer zugewiesenen MI enthält, wodurch die integrierte Authentifizierung angewiesen wird, FIC anstelle eines Geheimnisses zu verwenden.

Da die integrierte Authentifizierung bereits jede Anfrage überprüft, können Sie die redundante Überprüfung des Systemschlüssels in host.json deaktivieren, sodass es wie das folgende JSON-Fragment aussieht:

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

Konfiguration des Connector-Namensraums

Ihr Connector-Namespace muss über eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität verfügen, die aktiviert und angefügt ist. Wenn Sie die Triggerkonfiguration erstellen, geben Sie authentication.identity = <resource-id-of-managed-identity> und authentication.type = ManagedServiceIdentity für eine benutzerseitig zugewiesene Identität an, oder lassen Sie identity für eine systemseitig zugewiesene Identität weg. Geben Sie außerdem authentication.audience = <entra-app-client-id> an, damit die Laufzeit des Connectors weiß, welche Zielgruppe im Token angefordert werden soll.

Die Connector-Laufzeit nutzt diese verwaltete Identität, um bei jedem Rückruf ein Entra ID-Token zu generieren. In diesem Token ist iss (Aussteller) ist Ihr Mandant, aud (Zielgruppe) die Entra-App-Client-ID und oid (Objekt-ID) die Prinzipal-ID der Identität. Die integrierte Authentifizierung überprüft alle drei.

Die Connector-Namensraumressource benötigt ebenfalls Zugriff auf die Verbindung, zum Beispiel eine Verbindung office365 . Gewähren Sie diesen Zugriff über eine Zugriffsrichtlinie, die die Haupt-ID der verwalteten Identität auflistet. Die Beispiel-Bicep-Datei zeigt die vollständige Konfiguration sowohl für die Namensraum-Identität als auch für die Verbindungszugriffsrichtlinie.

Was erzwungen wird

Die integrierte Authentifizierung überprüft Token in der reihenfolge:

1. Tokenpräsenz – Fehlendes oder abgelaufenes Token → 401
2. Signatur – Überprüft anhand der JWKS des Ausstellers für Ihren Mandanten
3. iss (Aussteller) - Muss mit openIdIssuer übereinstimmen
4. aud (Zielgruppe) - Muss in allowedAudiences enthalten sein
5. oid (Objekt-/Prinzipal-ID) – Muss mit einer der Identitäten übereinstimmen in allowedPrincipals.identities. Jede andere Identität → 403

Da diese Überprüfung am App-Service-Edge ausgeführt wird, sieht Ihr Funktionscode nie eine Anfrage, die nicht aus der verwalteten Identität des Connector-Namensraums stammt. Für die Zugangsprüfung brauchst du keinen Anwendungscode.

Authentifizierungsfluss

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

Verwandte Inhalte

• Authentifizierung und Autorisierung in Azure App Service und Azure Functions
• Konfigurieren Sie Ihre App Service- oder Azure Functions-App für die Nutzung der Microsoft Entra-Anmeldung
• Dateibasierte Konfiguration in der Azure App Service-Authentifizierung
• Workload-Identitätsverbund in Microsoft Entra ID
• Verwaltete Identitäten für Azure-Ressourcen

Verwenden von Konnektoren in Ihrem Code

Das Connector-SDK ermöglicht es Ihrer Funktion, Connector-Operationen als ausgehende Aktionen aufzurufen. Die Client-Oberfläche verwendet denselben zugrundeliegenden verwalteten Connector im Connector-Namensraum, der die Nutzung auslöst, sodass ein einzelner verwalteter Connector sowohl eingehende Trigger als auch ausgehende Anrufe für dasselbe Dienstkonto versorgen kann.

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

Verwandte Artikel

• Azure Functions Verbinderbeispiele (kanonischer Index)
• End-to-End-.NET Beispiel: E-Mail-→ Benutzersuche → Teams
• .NET Beispiel: integrierte Authentifizierung mit verwalteter Identität
• Repository für die Azure Functions-Connectorerweiterung
• Zuordnung von Vorgängen zu Azure-Functions-Signaturen
• Übersicht über Azure Connectors
• Was ist Azure Connector-Namespace?
• In Azure Functions gehostete Skills