Panoramica dei trigger e delle associazioni di Azure Cosmos DB per Funzioni di Azure

Questo set di articoli illustra come usare le associazioni di Azure Cosmos DB in Funzioni di Azure. Funzioni di Azure supporta i trigger e le associazioni di input e output per Azure Cosmos DB.

Azione	TIPO
Eseguire una funzione quando viene creato o modificato un documento di Azure Cosmos DB	Attivazione
Leggere un documento di Azure Cosmos DB	Associazione di input
Salvare le modifiche apportate a un documento di Azure Cosmos DB	Associazione di output

Importante

Questa versione dell'estensione di associazione di Azure Cosmos DB supporta Funzioni di Azure versione 4.x. Se l'app usa ancora la versione 1.x del runtime di Funzioni, vedere associazioni di Azure Cosmos DB per Funzioni di Azure 1.x. Nel runtime di Funzioni v1.x questa associazione è stata originariamente denominata DocumentDB.

API supportate

Questa tabella indica come connettersi alle varie API di Azure Cosmos DB dal codice della funzione:

API	Raccomandazione
Azure Cosmos DB per NoSQL	Usare l'estensione di associazione di Azure Cosmos DB
Azure Cosmos DB per MongoDB	Usare un SDK client nativo.
Azure Cosmos DB per tabella	Usare la versione 5.x o successiva dell'estensione di associazione tabelle di Azure.
Azure Cosmos DB per Apache Cassandra	Usare un SDK client nativo.
Azure Cosmos DB per Apache Gremlin (API Graph)	Usare un SDK client nativo
Azure Cosmos DB con PostgreSQL	Usare un SDK client nativo.

Installare l'estensione

Il pacchetto NuGet di estensione installato dipende dalla modalità C# usata nell'app per le funzioni:

Modello di lavoro isolato
Modello di processo

Le funzioni sono eseguite in un processo di lavoro C# isolato. Per altre informazioni, vedere Guida per l'esecuzione di Funzioni di Azure C# in un processo di lavoro isolato.

Il processo di installazione dell'estensione varia a seconda della versione dell'estensione:

Questa sezione descrive l'uso di una libreria di classi. Per gli script C#, è necessario installare invece il bundle di estensione, versione 4.x.

Questa versione dell'estensione binding di Azure Cosmos DB introduce la possibilità di connettersi usando un'identità anziché un segreto. Per un'esercitazione sulla configurazione delle app per le funzioni con identità gestite, vedere l'esercitazione Creazione di un'app per le funzioni con connessioni basate sull'identità.

Questa versione modifica anche i tipi a cui è possibile eseguire il binding, sostituendo i tipi dell'SDK Microsoft.Azure.DocumentDB v2 con i tipi più recenti di Microsoft.Azure.Cosmos sdk v3. Altre informazioni su come questi nuovi tipi sono diversi e su come eseguirne la migrazione dalla guida alla migrazione dell'SDK, sul trigger, sull'associazione di input e sugli esempi di associazione di output.

Questa versione dell'estensione è disponibile come pacchetto NuGet versione 4.x.

Aggiungere l'estensione al progetto installando il pacchetto NuGet versione 4.x.

Se si scrive l'applicazione usando F#, è necessario configurare questa estensione anche come parte della configurazione di avvio dell'app. Nella chiamata a ConfigureFunctionsWorkerDefaults() o ConfigureFunctionsWebApplication()aggiungere un delegato che accetta un IFunctionsWorkerApplication parametro. Quindi, all'interno del corpo del delegato, chiamare ConfigureCosmosDBExtension() sull'oggetto :

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Installare il bundle

Per poter usare questa estensione di associazione nell'app, assicurarsi che il file host.json nella radice del progetto contenga questo extensionBundle riferimento:

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

In questo esempio, il version valore di indica all'host di Funzioni di [4.0.0, 5.0.0) usare una versione del bundle che è almeno 4.0.0 ma minore di 5.0.0, che include tutte le versioni potenziali di 4.x. Questa notazione mantiene l'app nella versione secondaria più recente disponibile del bundle di estensione v4.x.

Quando possibile, è consigliabile usare la versione principale del bundle di estensione più recente e consentire al runtime di mantenere automaticamente la versione secondaria più recente. È possibile visualizzare il contenuto del bundle più recente nella pagina di rilascio dei bundle di estensioni. Per altre informazioni, vedere Bundle di estensioni di Funzioni di Azure.

A causa delle modifiche dello schema in Azure Cosmos DB SDK, la versione 4.x dell'estensione Azure Cosmos DB richiede azure-functions-java-library V3.0.0 per le funzioni Java.

Tipi di associazioni

I tipi di associazione supportati per .NET dipendono sia dalla versione dell'estensione che dalla modalità di esecuzione di C#, che può essere una delle seguenti:

Modello di lavoro isolato
Modello di processo

Una funzione C# compilata di libreria di classi di processo di lavoro viene eseguita in un processo isolato dal runtime.

Scegliere una versione per visualizzare i dettagli del tipo di associazione per la modalità e la versione.

L'estensione Azure Cosmos DB supporta i tipi di parametri in base alla tabella seguente.

Scenario di associazione	Tipi di parametro
Trigger cosmos DB (singolo documento)	Tipi^{serializzabili JSON 1}
Trigger cosmos DB (batch di documenti)	`IEnumerable<T>`dove `T` è un tipo^{serializzabile JSON 1}
Input di Cosmos DB (singolo documento)	Tipi^{serializzabili JSON 1}
Input di Cosmos DB (query che restituisce più documenti)	CosmosClient `IEnumerable<T>` dove `T` è un tipo^{serializzabile JSON 1}
Output di Cosmos DB (singolo documento)	Tipi^{serializzabili JSON 1}
Output di Cosmos DB (più documenti)	`ICollector<T>` o `IAsyncCollector<T>` dove `T` è un tipo^{serializzabile JSON 1}

¹ I documenti contenenti dati JSON possono essere deserializzati in tipi poco (Plain-Old CLR Object) noti.

Il processo di lavoro isolato supporta i tipi di parametro in base alle tabelle seguenti. Il supporto per l'associazione ai tipi da Microsoft.Azure.Cosmosè disponibile in anteprima.

Trigger di Cosmos DB

Quando si vuole che la funzione elabori un singolo documento, il trigger di Cosmos DB può essere associato ai tipi seguenti:

TIPO	Descrizione
Tipi serializzabili JSON	Funzioni tenta di deserializzare i dati JSON del documento dal feed di modifiche di Cosmos DB in un tipo POCO (Plain-Old CLR Object).

Quando si vuole che la funzione elabori un batch di documenti, il trigger di Cosmos DB può essere associato ai tipi seguenti:

TIPO	Descrizione
`IEnumerable<T>`dove `T` è un tipo serializzabile JSON	Enumerazione delle entità incluse nel batch. Ogni voce rappresenta un documento dal feed di modifiche di Cosmos DB.

Associazione di input di Cosmos DB

Quando si vuole che la funzione elabori un singolo documento, l'associazione di input di Cosmos DB può essere associata ai tipi seguenti:

TIPO	Descrizione
Tipi serializzabili JSON	Funzioni tenta di deserializzare i dati JSON del documento in un tipo POCO (Plain-Old CLR Object).

Quando si vuole che la funzione elabori più documenti da una query, l'associazione di input di Cosmos DB può essere associata ai tipi seguenti:

TIPO	Descrizione
`IEnumerable<T>`dove `T` è un tipo serializzabile JSON	Enumerazione delle entità restituite dalla query. Ogni voce rappresenta un documento.
CosmosClient¹	Un client connesso all'account Cosmos DB.
Database¹	Un client connesso al database Cosmos DB.
Contenitore¹	Un client connesso al contenitore Cosmos DB.

¹ Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 o versione successiva e alle dipendenze comuni per le associazioni di tipi SDK.

Associazione di output di Cosmos DB

Quando si vuole che la funzione scriva in un singolo documento, l'associazione di output di Cosmos DB può essere associata ai tipi seguenti:

TIPO	Descrizione
Tipi serializzabili JSON	Oggetto che rappresenta il contenuto JSON di un documento. Funzioni tenta di serializzare un tipo di oggetto CLR (POCO) normale in dati JSON.

Quando si vuole che la funzione scriva in più documenti, l'associazione di output di Cosmos DB può essere associata ai tipi seguenti:

TIPO	Descrizione
`T[]` dove `T` è un tipo serializzabile JSON	Matrice contenente più documenti. Ogni voce rappresenta un documento.

Per altri scenari di output, creare e usare un cosmosClient con altri tipi direttamente da Microsoft.Azure.Cosmos . Vedere Registrare i client di Azure per un esempio di uso dell'inserimento delle dipendenze per creare un tipo di client da Azure SDK.

Tipi di associazione SDK

Il supporto del tipo di SDK per Azure Cosmos è disponibile in anteprima. Per iniziare a usare i tipi di SDK per Cosmos IN Python, seguire l'esempio Python SDK Bindings for Cosmos per Cosmos .

Importante

L'uso delle associazioni dei tipi di SDK richiede il modello di programmazione Python v2.

Vincolo	Tipi di parametro	Esempi
Input di CosmosDB	ContainerProxy, CosmosClient, DatabaseProxy	`ContainerProxy`, `CosmosClient`, `DatabaseProxy`

Eccezioni e codici restituiti

Vincolo	Riferimento
Azure Cosmos DB, un servizio di database distribuito globale di Microsoft	Codici di stato HTTP per Azure Cosmos DB

impostazioni host.json

Questa sezione descrive le impostazioni di configurazione disponibili per questa associazione nella versione 2.x e successive. Le impostazioni nel file host.json si applicano a tutte le funzioni in un'istanza dell'app per le funzioni. Per altre informazioni sulle impostazioni di configurazione dell'app per le funzioni, vedere informazioni di riferimentohost.json per Funzioni di Azure.

Estensione 4.x+
Funzioni 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Proprietà	Predefinito	Descrizione
connectionMode	`Gateway`	La modalità di connessione usata dalla funzione durante la connessione al servizio di Azure Cosmos DB. Opzioni: `Direct` si connette direttamente alle repliche back-end tramite TCP e può fornire una latenza inferiore e `Gateway` instrada le richieste tramite un gateway front-end tramite HTTPS. Per altre informazioni, vedere Modalità di connessione di Azure Cosmos DB SDK.
userAgentSuffix	n/d	Aggiunge il valore stringa specificato a tutte le richieste effettuate dal trigger o dall'associazione al servizio. In questo modo è più semplice tenere traccia dell'attività in Monitoraggio di Azure, in base a un'app per le funzioni specifica e al filtro in `User Agent`base a .

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Proprietà	Predefinito	Descrizione
connectionMode	`Gateway`	La modalità di connessione usata dalla funzione durante la connessione al servizio di Azure Cosmos DB. Opzioni: `Direct` si connette direttamente alle repliche back-end tramite TCP e può fornire una latenza inferiore e `Gateway` instrada le richieste tramite un gateway front-end tramite HTTPS. Per altre informazioni, vedere Modalità di connessione di Azure Cosmos DB SDK.
protocollo	`Https`	Il protocollo di connessione usato dalla funzione durante la connessione al servizio di Azure Cosmos DB. Leggere qui per una spiegazione di entrambe le modalità.
leasePrefix	n/d	Prefisso di lease da usare in tutte le funzioni in un'app.

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-09-22