Trigger e associazioni di Azure Cosmos DB per Funzioni di Azure 2.x e una panoramica successiva
Questo set di articoli illustra come usare le associazioni di Azure Cosmos DB in Funzioni di Azure 2.x e versioni successive. Funzioni di Azure supporta i trigger e le associazioni di input e output per Azure Cosmos DB.
Azione | Type |
---|---|
Eseguire una funzione quando viene creato o modificato un documento di Azure Cosmos DB | Trigger |
Leggere un documento di Azure Cosmos DB | Associazione di input |
Salvare le modifiche apportate a un documento di Azure Cosmos DB | Associazione di output |
Nota
Questo riferimento è per Funzioni di Azure versione 2.x e successive. Per informazioni su come usare le associazioni in Funzioni 1.x, vedere Associazioni di Azure Cosmos DB per Funzioni di Azure 1.x.
Questa associazione è stata originariamente denominata DocumentDB. In Funzioni di Azure versione 2.x e successive, il trigger, le associazioni e il pacchetto sono tutti denominati Azure Cosmos DB.
API supportate
Le associazioni di Azure Cosmos DB sono supportate solo per l'uso con Azure Cosmos DB per NoSQL. Il supporto per Azure Cosmos DB per la tabella viene fornito usando le associazioni di archiviazione tabelle, a partire dall'estensione 5.x. Per tutte le altre API di Azure Cosmos DB, è necessario accedere al database dalla funzione usando il client statico per l'API, incluso Azure Cosmos DB per MongoDB, Azure Cosmos DB per Cassandrae Azure Cosmos DB per Apache Gremlin.
Installare l'estensione
Il pacchetto NuGet di estensione installato dipende dalla modalità C# usata nell'app per le funzioni:
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 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à.
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
L'estensione delle associazioni di Azure Cosmos DB fa parte di un bundle di estensione, specificato nel file di progetto host.json . Potrebbe essere necessario modificare questo bundle per modificare la versione dell'associazione o se i bundle non sono già installati. Per altre informazioni, vedere bundle di estensioni.
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.
Questa versione del bundle contiene la versione 4.x dell'estensione binding di Azure Cosmos DB che 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à.
È possibile aggiungere questa versione dell'estensione dal bundle dell'estensione di anteprima v4 aggiungendo o sostituendo il codice seguente nel host.json
file:
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
"version": "[4.0.0, 5.0.0)"
}
}
Per altre informazioni, vedere Aggiornare le estensioni.
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:
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.
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. |
CosmosClient1 | Un client connesso all'account Cosmos DB. |
Database1 | Un client connesso al database Cosmos DB. |
Contenitore1 | Un client connesso al contenitore Cosmos DB. |
1 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.
Eccezioni e codici restituiti
Binding | Riferimento |
---|---|
Azure Cosmos DB | Codici di stato HTTP per Azure Cosmos DB |
impostazioni host.json
Questa sezione descrive le impostazioni di configurazione disponibili per questa associazione nelle versioni 2.x e successive. Le impostazioni nel file host.json si applicano a tutte le funzioni in un'istanza dell'app per le funzioni. L'esempio host.json file seguente contiene solo le impostazioni della versione 2.x+ per questa associazione. Per altre informazioni sulle impostazioni di configurazione delle app per le funzioni nelle versioni 2.x e successive, vedere informazioni di riferimento host.json per Funzioni di Azure.
{
"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. Le opzioni sono Direct e Gateway |
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 . |