Panoramica dell'estensione connettore per Funzioni di Azure

Funzioni di Azure fornisce estensioni trigger e binding che si integrano con vari servizi, principalmente i servizi Azure. L'estensione Connector amplia queste integrazioni attraverso connettori gestiti nel Azure Spazio dei Connettori, permettendo alle tue funzioni di ricevere eventi da sistemi aziendali e piattaforme dati come Office 365 Outlook, SharePoint Online, Microsoft Teams e Dataverse.

Per i connettori Microsoft e gestiti da terze parti disponibili, consulta il riferimento ai connettori.

Note

I connettori gestiti supportano i piani di hosting Flex Consumption, Dedicated ed Elastic Premium per le app Linux Function in tutte le regioni. La disponibilità delle app Windows è limitata oggi.

Flex Consumption è il piano di hosting consigliato per le funzioni attivate dal connettore.

Note

Il Connector Trigger non è attualmente supportato per questo linguaggio.

Ora di fine Utilizza
Esegui una funzione in risposta a un evento in un servizio connesso Trigger del connettore, fornito dall'estensione del connettore
Esegui un'azione in un servizio connesso da un codice di funzione Azure Connectors SDK, disponibile per .NET, Node.jse Python

Puoi usare entrambi insieme: il Connector Trigger avvia la tua funzione e l'SDK esegue azioni nei servizi collegati. Se devi eseguire solo azioni, usa l'SDK senza l'estensione del connettore.

Per maggiori informazioni sui connettori gestiti, quando usarli e sulla disponibilità delle funzionalità, consulta Usa connettori gestiti in Funzioni di Azure.

Trigger del connettore in Funzioni di Azure

Una funzione attivata da connettore utilizza questi componenti:

Component Responsabilità
Spazio dei nomi del connettore Gli host gestivano le connessioni dei connettori e le configurazioni dei trigger.
Connessione del connettore gestito Si autentica al servizio esterno e gestisce la connettività specifica del servizio.
Configurazione dell'attivazione Seleziona l'evento del connettore, i parametri operativi e la modalità di consegna.
Funzioni di Azure Connector Extension Riceve eventi dal Namespace del Connettore, invoca la funzione e lega il corpo dell'evento al parametro della funzione.
Azure Connectors SDK (opzionale) Fornisce modelli opzionali di payload fortemente tipizzati e client per invocare operazioni di connettore gestito, come inviare un'email o creare un file SharePoint.

Un connettore gestito può supportare più eventi e ogni evento che vuoi monitorare necessita della propria configurazione dei trigger. Ad esempio, il connettore Office 365 Outlook supporta eventi come l'arrivo di una nuova email, la segnalazione di un'email, la creazione di un evento nel calendario o la modifica di un evento del calendario. Crea una configurazione di trigger separata per ciascun evento che desideri utilizzare per eseguire una funzione.

Per esempi di codice, vedi Esempi di trigger del connettore e Utilizzo degli SDK dei connettori nel tuo codice.

Scegli una modalità di consegna

I connettori gestiti supportano la distribuzione tramite webhook e sondaggi. Scegli una modalità in base alla latenza, capacità di elaborazione, esigenze di rete e autenticazione del tuo scenario:

Feature Sondaggio Webhook
Consegna degli eventi e latenza L'host delle funzioni recupera gli eventi tramite richieste di sondaggio in uscita. Gli eventi attendono che il conduttore non li voti. Il Connector Namespace invia gli eventi all'endpoint di callback dell'app di funzione non appena li rileva dal servizio sorgente, senza attendere che l'app effettui un interrogatorio. Questo riduce la latenza di consegna per l'elaborazione sensibile al tempo.
Capacità di elaborazione e protezione a valle L'host recupera più eventi man mano che la capacità di elaborazione diventa disponibile. Combina i limiti di scala delle app con le impostazioni di concorrenza tramite sonding per vincere l'elaborazione simultanea e proteggere database o API a valle. Gli eventi in attesa rimangono in coda nel Namespace del Connettore, soggetti ai suoi limiti di conservazione degli eventi. Gli eventi arrivano indipendentemente dalla capacità di elaborazione disponibile dell'app. I limiti di scale-out possono portare a richiami limitati o falliti quando la domanda supera la capacità; gli eventi possono andare persi se la consegna non riesce a rientrare nei limiti di ritentativo del servizio.
Reti in entrata Non è necessario un endpoint di callback in entrata. Puoi limitare l'accesso in ingresso all'app di funzione consentendo al contempo le richieste in uscita all'endpoint di sondaggio del Connector Namespace. Il Namespace del Connettore deve poter raggiungere l'endpoint di callback dell'app. Le restrizioni in entrata devono consentire tali richieste.
Autenticazione dell'identità gestita L'host delle funzioni può utilizzare l'identità gestita assegnata dal sistema o dall'utente dell'app per ricevere e confermare eventi. Concedere a tale identità una policy di accesso sulla connessione del connettore gestito. Per i callback autenticati con Microsoft Entra ID, il Connector Namespace utilizza la sua identità gestita. Configura l'autenticazione integrata del servizio App sull'app della funzione ricevente per convalidare i token. L'autenticazione webhook predefinita utilizza invece la chiave di sistema dell'estensione Connector.

A seconda del tuo piano hosting, puoi limitare l'accesso in ingresso all'app di funzione utilizzando endpoint privati o restrizioni di accesso in entrata, incluse restrizioni basate su IP o endpoint di servizio, senza impedire il sondaggio. L'app deve comunque essere in grado di effettuare richieste HTTPS in uscita all'endpoint di polling del Connector Namespace. Separatamente, l'identità gestita configurata dell'app di funzione deve avere una policy di accesso sulla connessione del connettore gestito.

La modalità di consegna degli eventi controlla come gli eventi raggiungono l'host delle funzioni dal namespace del connettore, non come il connettore gestito rileva i cambiamenti nel servizio sorgente.

La consegna Webhook scala come trigger HTTP, mentre la consegna tramite sondaggio utilizza la scalabilità basata su target. L'obiettivo di scalabilità del sondaggio è indipendente dalla concorrenza degli ascoltatori e dalla dimensione del batch. Per dettagli su entrambe le modalità, vedi Scaling e concorrenza del Connector Trigger. Per l'equazione di scala del polling e le impostazioni di ottimizzazione, vedi Scaling basato su target dei connettori gestiti.

Entrambe le modalità utilizzano [ConnectorTrigger] il parametro di funzione che riceve il corpo dell'evento e possono utilizzare gli stessi modelli di payload. Per esempi di entrambe le modalità di distribuzione, consulta gli esempi del Connector Trigger.

Installare i pacchetti

Prolunga del connettore

Il Connector Trigger supporta il modello worker isolato .NET. Per informazioni sulle versioni supportate di .NET nelle versioni runtime di Funzioni di Azure, vedi Linguaggi per versione runtime.

Aggiungi la versione 1.0.0 o successiva del pacchetto di estensione Connector al tuo progetto.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector

SDK Azure Connectors

Se la tua funzione deve eseguire solo azioni su servizi esterni e non deve essere attivata da eventi, usa solo l'SDK Azure Connectors. Non hai bisogno del pacchetto di estensione Connector.

Aggiungi l'SDK Azure Connectors:

dotnet add package Azure.Connectors.Sdk

Per i connettori più popolari, l'SDK fornisce client fortemente tipizzati per invocare azioni sui connettori dalle tue funzioni; consulta l'SDK Azure Connectors per .NET riferimento API.

Installare l'estensione

Usa Node.js 24 o successiva. Entrambe le modalità di consegna utilizzano gli aiutanti di registrazione dei trigger con nome o generici.

Installa i pacchetti usati dal trigger Connector:

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

Questi pacchetti offrono le seguenti funzionalità:

Configura il pacchetto di estensioni nel file host.json . Il bundle fornisce l'estensione host del Connettore per entrambe le modalità di consegna:

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

Azure Connectors SDK

Se la tua funzione deve eseguire solo azioni su servizi esterni e non deve essere attivata da eventi, installa solo l'SDK Azure Connectors per Node.js. Non ti servono i pacchetti di trigger Connector.

npm install "@azure/connectors@latest"

L'SDK fornisce client fortemente tipizzati per invocare azioni di connettore dalle tue funzioni.

Per le versioni attuali dei pacchetti e i progetti completi, consulta i modelli di connettore Funzioni di Azure per TypeScript.

Entrambe le modalità di consegna utilizzano il @app.connector_trigger decoratore. Per esempi, vedi Esempi di Trigger del Connettore.

Installare l'estensione

Aggiungi i seguenti pacchetti a requirements.txt:

azure-functions>=2.4.0
azurefunctions-extensions-connectors>=1.0.0

Note

Per le versioni Python precedenti alla 3.13, usa azure-functions>=1.27.0b1 invece.

  • La libreria Python core azure-functions fornisce il decorator e può associare eventi singoli grezzi a str oppure bytesbatch di polling a typing.List[str] optyping.List[bytes].
  • Il pacchetto azurefunctions-extensions-connectors integra l'SDK Azure Connectors per Python e registra i convertitori per le annotazioni SDK specifiche per l'operazione supportate. Ad esempio, emails: list[office365.GraphClientReceiveMessage], dove office365 è importato da azurefunctions.extensions.connectors, riceve oggetti modello email per l'operazione Office 365 OutlookOnNewEmailV3.

Configura il pacchetto di estensioni nel file host.json . Il bundle fornisce l'estensione host del Connettore per entrambe le modalità di consegna:

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

Azure Connectors SDK

Se la tua funzione deve eseguire solo azioni su servizi esterni e non deve essere attivata da eventi, installa solo l'SDK Azure Connectors per Python. Non ti servono i pacchetti di trigger Connector.

python -m pip install "azure-connectors>=1.0.0"

L'SDK fornisce client fortemente tipizzati per invocare azioni di connettore dalle tue funzioni.

Per le versioni attuali dei pacchetti e i progetti completi, consulta i modelli di connettori Funzioni di Azure per Python.

impostazioni host.json

L'estensione Connettore non richiede impostazioni specifiche per il connettore nel file host.json quando utilizzi le impostazioni predefinite.

Le sezioni seguenti mostrano le impostazioni opzionali per ciascuna modalità di consegna.

Modalità di sondaggio

Configura le impostazioni di sondaggio opzionali nel extensions.connector file host.json . Ad esempio, la seguente configurazione limita il ritardo tra un sondaggio e l'altro quando non sono disponibili eventi a un secondo:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "maxPollingInterval": "00:00:01"
    }
  }
}
Property Predefinito Description
defaultMaxBatchSize 1 Eventi massimi per invocazione quando la funzione non specifica una sovrascrittura positiva della dimensione del batch. I valori validi vanno da 1 a 32. I valori superiori a 1 richiedono l'abilitazione del batching.
defaultMaxConcurrentCalls 16 Compiti massimi di elaborazione simultanea a singolo evento per ascoltatore su un'istanza, inclusa preparazione, invocazione e conferma. Deve essere positivo. Non si applica alle invocazioni a batch.
defaultTargetPendingEventThreshold 16 Mira gli eventi pendenti per istanza per scalare basato su target quando l'esecuzione non fornisce un target di concorrenza. Deve essere positivo. Indipendentemente dalla dimensione del batch e dalla concorrenza di invocazione.
maxPollingInterval "00:00:30" Ritardo massimo tra i sondaggi quando non sono disponibili eventi. Deve essere almeno un secondo. Non controlla quanto spesso il connettore controlla il servizio sorgente.
maxLinkedOutputSizeInBytes 104857600 (100 MiB) Byte totali scaricati per output dell'evento collegato. Deve essere positivo. Non si applica alle risposte dei sondaggi inline. Questa è una barriera di download (guardrail) per il download, non una garanzia supportata sulla dimensione del payload.

Le sovrascritture positive per funzione hanno la precedenza sulle corrispondenti impostazioni predefinite dell'host. L'esecuzione può sovrascrivere l'obiettivo di scala senza modificare la dimensione del batch o la concorrenza degli ascoltatori. I lotti vengono elaborati uno alla volta per ogni ascoltatore. Per le opzioni specifiche per lingua, vedi Modalità sondaggio.

Gli eventi a output collegato vengono scaricati dall'host e normalizzati alla forma ordinaria del payload. Vengono invocati un evento alla volta dietro un limitatore a livello host, anche quando il binding consente il batching.

L'aumento maxLinkedOutputSizeInBytes può esaurire la memoria dell'host o del lavoratore. Convalida il carico di lavoro sulla dimensione del tuo hosting prima di aumentarla; il valore predefinito non stabilisce un limite supportato per la dimensione del payload.

Modalità Webhook

L'autenticazione predefinita a chiave di sistema non richiede impostazioni specifiche per connettore in host.json. Se l'autenticazione integrata del servizio App valida i callback, puoi impostare extensions.connector.system.webhookAuthorizationLevel per Anonymous disabilitare il controllo ridondante della chiave di sistema.

Utilizzare Anonymous solo quando un altro livello di autenticazione convalida le richieste prima che raggiungano l'host delle funzioni. Per dettagli di configurazione e un esempio completo, vedi Autenticazione integrata.

Utilizzo degli SDK dei connettori nel tuo codice

L'SDK del connettore consente alla tua funzione di chiamare le operazioni del connettore come azioni in uscita. La superficie client utilizza lo stesso connettore gestito sottostante nel Namespace del Connettore che attiva l'uso, quindi un singolo connettore gestito può alimentare sia i trigger in entrata sia le chiamate in uscita per lo stesso account di servizio.

L'autenticazione dei callback webhook in entrata non concede all'app di funzione il permesso di effettuare chiamate SDK in uscita. Per una funzione attivata da webhook che effettua anche chiamate SDK, concede all'identità gestita (distribuita) o all'identità dello sviluppatore (locale) dell'app di funzione una policy di accesso a ciascuna connessione connettore gestita utilizzata da quelle chiamate.

Per il sondaggio, l'identità gestita dell'app di funzione o l'identità dello sviluppatore necessita già di una policy di accesso alla connessione. Se il client SDK utilizza la stessa identità e connessione, la policy esistente consente anche chiamate SDK; non è necessaria alcuna assegnazione aggiuntiva della policy di accesso.

Sia le funzioni di polling che quelle webhook devono trasmettere una credenziale al client SDK, come mostrato di seguito.

In .NET ogni connettore fornisce un client tipizzato (ad esempio, Office365Client, Office365UsersClient, TeamsClient) in Azure.Connectors.Sdk.{Service}. Il costruttore client prende l'URL runtime della connessione e una credenziale.

Lo schema seguente proviene dall'esempio di Teams end-to-end per la ricerca dell'utente tramite email:

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

Questo esempio crea un DefaultAzureCredential, lo registra come TokenCredential, e lo passa al costruttore di ciascun client SDK tramite sp.GetRequiredService<TokenCredential>(). Localmente, l'abilitazione può utilizzare il login dello sviluppatore; in Azure, può utilizzare l'identità gestita dell'app funzionale. Impostato AZURE_CLIENT_ID sull'ID client di un'identità gestita assegnata dall'utente all'app di funzione. Lascialo non impostato per un'identità assegnata dal sistema o per il login dello sviluppatore locale.

Le impostazioni *_CONNECTION_RUNTIME_URL puntano all'endpoint di runtime relativo a ciascuna connessione nello spazio dei nomi del connettore. Inserisci i client nella tua funzione e chiama metodi tipizzati come UserProfileAsync, GetEmailsAsync o FlagAsync. È anche possibile chiamare i client SDK da trigger che non usano connettori, ad esempio un trigger HTTP che pubblica in Teams.

Il seguente estratto semplificato dall'esempio email-to-Teams utilizza l'inietto Office365Client per segnalare un'email per il follow-up. Chiama questo helper dal codice di elaborazione della tua funzione con l'ID del messaggio dell'email:

using Azure.Connectors.Sdk.Office365;
using Azure.Connectors.Sdk.Office365.Models;

public class ProcessEmail(Office365Client office365Client)
{
    public async Task FlagEmailAsync(string messageId)
    {
        await office365Client.FlagAsync(
            messageId: messageId,
            input: new UpdateEmailFlag { Flag = new { flagStatus = "flagged" } },
            originalMailboxAddress: null,
            cancellationToken: default);
    }
}

In Python, azure-connectors fornisce client tipizzati come Office365Client e TeamsClient. Passa l'URL di runtime per connessione e un'accreditazione al costruttore del client. Per l'autenticazione Microsoft Entra ID, usa un'identità asincrona come azure.identity.aio.DefaultAzureCredential. Attendi le operazioni SDK.

In Node.js, @azure/connectors fornisce client tipizzati come Office365Client e TeamsClient. Passa l'URL runtime per connessione e un'identificativa, come DefaultAzureCredential from @azure/identity, al costruttore client. Attendi le operazioni SDK.