Trigger e associazioni di Azure Cosmos DB per Funzioni di Azure 2.x e una panoramica successiva

Articolo
11/21/2023

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, tra cui Azure Cosmos DB per MongoDB, Azure Cosmos DB per Cassandra e 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:

Modello di lavoro isolato
Modello in-process

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 sulla creazione di un'app per le funzioni con connessioni basate su 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

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.

Bundle v4.x
Bundle v2.x e v3.x

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 sulla creazione di un'app per le funzioni con connessioni basate su 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.

È possibile installare questa versione dell'estensione nell'app per le funzioni registrando il bundle di estensione versione 2.x o 3.x.

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

Tipi di associazioni

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

Modello di lavoro isolato
Modello in-process

Una libreria di classi di processo di lavoro isolata compilata C# 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 i tipi direttamente da Microsoft.Azure.Cosmos .

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. 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.

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. 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 .

{
    "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. Le opzioni sono `Direct` e `Gateway`
protocol	`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.