Använd managed connectors i Azure Functions

Genom att använda hanterade kopplingar kan dina funktioner reagera på händelser och anropsoperationer i tjänster som Microsoft 365, Microsoft Teams, SharePoint och många tredjepartssystem utan att behöva skriva webhook-uppsättningskod eller hantera OAuth-tokens. Azure Functions integreras med Azure Connector Namespace för att tillhandahålla en trigger och ett SDK som låter dig fokusera på affärslogik medan connector-namnrymden hanterar webhooks, autentisering och omförsök.

Hur kontakter förbättrar funktioner

Ett connector-namnutrymme lägger till två funktioner i Functions-programmeringsmodellen:

• Kontaktutlösare
  En funktion körs när en händelse inträffar i en extern tjänst, såsom ett nytt e-postmeddelande i Microsoft 365, en fil tillagd i SharePoint eller ett meddelande som postas i Teams. Körtiden exponerar en connectorTrigger bindning som tar emot webhook-callbacks från anslutningsnamnrymden.
• Connector SDK-åtgärder
  Din funktionskod anropar anslutningsoperationer via SDK-klienter. SDK:n täcker hanterade kopplingar såsom Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint och OneDrive. Hanterade kopplingar som ännu inte har SDK-modeller kan anropas som HTTP-endpoints.

Du kan använda hanterade kopplingar tillsammans med klassiska Functions-triggers och bindningar som HTTP, timer, kö, Service Bus, Event Grid och Durable Functions.

Förhandsgranska tillgänglighet

När du ska använda anslutningar

Använd connectors när dina funktioner främst behöver interagera med externa tjänster istället för att köra komplex anpassad logik. Överväg dessa sätt att använda managed connectors i dina funktionsappar:

• Reagera på yttre händelser
  Din app måste hantera händelser som genereras av externt anslutna tjänster (nya mejl, kalenderinbjudningar, filer, listar, Teams-aktivitet), men du vill inte lägga ner tid på att koda webhook-registreringar, handshake-validering och OAuth-uppdateringar. Tänk dig ett fall där din funktion körs för att bearbeta nya mejl som levereras i en övervakad Office 365 Outlook-mapp, klassificerar meddelandet, anropar Office 365-koppling för berikning och flaggar eller flyttar mejlet. Allt detta distribuerade arbete utförs av din app utan att du någonsin behöver oroa dig för uppdateringstoken, eftersom de hanteras av din anslutningsnamnrymd.

• Byt ut klienter för anpassade tjänster
  Din funktionskod anropar redan Microsoft 365 eller tredjeparts-API:er genom att använda anpassade HTTP-klienter, vilket kräver att du hanterar hemligheter, scopes och återförsökspolicys över många anslutningar, vilket snabbt kan bli en underhållsbörda. Du kan istället använda de typade klienterna i connector-SDK:er direkt i din funktionskod och låta managed connectors hantera anslutningarna själva.

• Utnyttja en befintlig appdistribution
  Du har redan byggt ett händelsedrivet funktionsappprojekt med en distributionspipeline och övervakningsverktyg. Du kan använda hanterade kopplingar för att lägga till en ny extern tjänst som är triggerbaserad i samma projekt och dra nytta av den befintliga infrastrukturen. Till exempel kan en funktionsapp som tidigare förlitade sig på meddelandeköer eller Logic Apps nu reagera direkt på Teams-aktivitet och ansluta till Office 365 för kontroller i organisationen och chefsuppslag.

• Agentiska arbetsflöden
  Du bygger arbetsflöden där en funktion tar emot en händelse, resonerar med en AI-modell och sedan agerar tillbaka till en extern tjänst via en connector-operation. Du kan utnyttja Azure Functions-hostade funktioner för att programmera ditt agentbaserade arbetsflöde samtidigt som du fortfarande drar nytta av hanterade anslutningsbaserade utlösare och SDK:er för hanterade anslutningar.

• Kodstyrning med hanterad integration
  Du vill ha hanterade kopplingar för att förenkla inkommande och utgående kommunikation med externa tjänster, men du föredrar en kodförsta-programmeringsmodell och full kontroll över orkestreringen, inklusive förgrening, hantering av autentisering mellan steg och återanvändning av dina befintliga bibliotek.

  Tip

  När arbetsbelastningen är ren orkestrering över kopplingar utan anpassad kod förblir Logic Apps Standard det enklaste valet. För mer information, se Relation till andra Azure-integrationsalternativ.

Relation till andra Azure integrationsalternativ

Managed connectors i Azure Functions är additiva. Rätt val beror på hur mycket anpassad kod arbetsbelastningen behöver och om teamet föredrar en visuell designer eller kod.

En enskild funktionsapp kan kombinera alla tre mönstren. Du kan lägga till en anslutningsutlösare i en befintlig HTTP-utlösarapp och implementera SDK-klienter stegvis.

Paket och förutsättningar

Varje språk som stöds har en liten uppsättning paket som innehåller utlösarbindningen och klienterna i anslutnings-SDK:n.

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

Anslutningsbaserade utlösare

En hanterad anslutningsbaserad trigger kör din funktion när en händelse inträffar i den anslutna tjänsten. Connector-namnrymden levererar händelsen till din funktionsapp via HTTPS genom att använda connector-tilläggets webhook-endpoint:

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

Triggerkonfigurationen i ditt connector-namnutrymme lagrar den callback-URL:en och presenterar systemnyckeln vid varje callback. Functions-runtimen validerar nyckeln innan den kör din funktion. För en installation utan delade hemligheter kan du lägga App Service-inbygd autentisering framför funktionsappen och validera en hanterad identitetstoken från connector-namnrymden. Se .NET-exempel: inbyggd autentisering med hanterad identitet för hela mönstret.

Begärandenyttolaster bär händelsetexten plus en uppsättning x-ms-* rubriker som identifierar utlösarkonfigurationen, anslutningen, händelsetypen och ett korrelations-ID. När den hanterade connectorn har en SDK-modell, deserialiserar körtiden payloaden direkt till den modellen. För hanterade kopplingar utan klient-SDK:er får din funktion den råa JSON-kroppen.

I följande exempel visas en funktion som utlöses när ett nytt e-postmeddelande tas emot i en Office 365 Outlook postlåda. Triggerregistreringen sker per språk; Triggerkonfigurationen i kontaktnamnrymden är densamma i alla fall.

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 skapar triggerkonfigurationen i connector-namnrymden genom att använda Azure CLI, ARM eller Bicep. Det steget är en del av connector-plattformen och dokumenteras i connectors innehållsuppsättning. Functions skickar inte egna konfigurationskommandon för utlösarregistrering.

Autentisera dina funktioner för en anslutningsnamnrymd

Standardautentiseringsmodellen använder en delad systemnyckel (connector_extension) som anslutningsnamnrymden presenterar vid varje återkallelse. Delade nycklar kan dock inte avgränsas per utlösare och kräver samordnad rotation mellan funktionsappen och anslutningsnamnrymden. För produktionsarbetsbelastningar, använd istället App Service inbyggd autentisering (även kallad Easy Auth) med en hanterad identitet.

I detta mönster använder connector-namnrymden sin egen systemtilldelade eller användartilldelade hanterade identitet för att begära en Entra ID-token för varje återkallelse. Funktionsappen validerar tokenen, inklusive dess mottagare, utfärdare och anroparens objekt-ID, innan en begäran når Functions-värden. Inga delade nycklar, inga klienthemligheter, var som helst.

För ett heltäckande fungerande exempel, se den här koddatabasen: functions-connectors-net-builtinauth.

Konfiguration av funktionsapp

Inbyggd autentisering körs vid App Service-arbetarens gräns innan Functions-runtime får förfrågan. Du konfigurerar det via ARM-egenskapenauthsettingsV2 eller dess motsvarighet i Bicep.

Funktionsappen behöver också en användartilldelad hanterad identitet federerad till Entra-appregistreringen. Inbyggd autentisering använder den federerade identitetsreferensen (FIC) för att generera klientförsäkringar för Entra-appen utan att behöva lagra en klienthemlighet. Bicep-mönstret anger clientSecretSettingName som en appinställning som innehåller det användartilldelade MI:ets klient-ID, vilket gör att den inbyggda autentiseringen använder FIC i stället för en klienthemlighet.

Eftersom inbyggd autentisering redan validerar varje förfrågan kan du inaktivera den redundanta systemnyckelkontrollen i host.json, vilket skulle se ut som detta JSON-fragment:

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

Konfiguration av anslutningens namnrymd

Ditt connector-namnutrymme måste ha en systemtilldelad eller användartilldelad hanterad identitet aktiverad och kopplad. När du skapar triggerkonfigurationen, specificera authentication.type = ManagedServiceIdentity och authentication.identity = <resource-id-of-managed-identity> för en användartilldelad identitet eller utelämna identity för en system-tilldelad identitet. Ange också authentication.audience = <entra-app-client-id> så att anslutningsruntimen vet vilken målgrupp som ska begäras i tokenet.

Connector-runtimen använder den hanterade identiteten för att generera en Entra ID-token vid varje återanrop. I denna token iss är (utfärdaren) din hyresgäst, aud (audience) är Entra-appens klient-ID och oid (objekt-ID) är huvud-ID:t för identiteten. Inbyggd autentisering verifierar alla tre.

Connector-namnrymdsresursen behöver också åtkomst till anslutningen, såsom en office365 anslutning. Bevilja denna åtkomst via en åtkomstpolicy som listar den hanterade identitetens huvudsakliga ID. Exempelbicep-filen visar hela konfigurationen för både namnrymdidentiteten och anslutningsåtkomstpolicyn.

Vad som framtvingas

Inbyggd autentisering validerar token i ordning:

1. Tokennärvaro – Token saknas eller har upphört att gälla → 401
2. Signatur – Verifierad mot utfärdarens JWKS för din klientorganisation
3. iss (utfärdare) - måste stämma överens med openIdIssuer
4. aud (målgrupp) – Måste vara i allowedAudiences
5. oid (objekt/huvudnamns-ID) – Måste matcha en av identiteterna i allowedPrincipals.identities. Alla andra identiteter → 403

Eftersom denna kontroll körs vid App Service-kanten ser din funktionskod aldrig en förfrågan som inte kom från connector-namnrymdens hanterade identitet. Du behöver ingen applikationskod för åtkomstkontrollen.

Autentiseringsflöde

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

Relaterat innehåll

• Autentisering och auktorisering i Azure App Service och Azure Functions
• Konfigurera din App Service- eller Azure Functions-app så att den använder Microsoft Entra-inloggning
• Filbaserad konfiguration i Azure App Service-autentisering
• Federation av arbetsbelastningsidentiteter i Microsoft Entra ID
• hanterade identiteter för Azure-resurser

Använda anslutningar i din kod

Connector SDK:n gör det möjligt för din funktion att anropa connector-operationer som utgående åtgärder. Klientgränssnittet använder samma underliggande hanterade anslutning i namnrymden för anslutningar som används för utlösare, så en enda hanterad anslutning kan användas för både inkommande utlösare och utgående anrop för samma tjänstekonto.

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

Relaterade artiklar

• Exempel på Azure Functions-anslutningsprogram (huvudindex)
• End-to-end .NET exempel: e-post → användarsökning → Teams
• .NET exempel: inbyggd autentisering med hanterad identitet
• Azure Functions Connector Extension-lagringsplats
• Signaturmappning för åtgärder till Azure Functions
• Översikt över Azure anslutningsappar
• Vad är namnrymden för Azure Connector?
• Värdbaserade färdigheter i Azure Functions