Trigger di Azure Cosmos DB per Funzioni di Azure 2.x e versioni successive

Il trigger di Azure Cosmos DB usa il feed di modifiche di Azure Cosmos DB per ascoltare inserimenti e aggiornamenti tra partizioni. Il feed di modifiche pubblica elementi nuovi e aggiornati, non inclusi gli aggiornamenti dalle eliminazioni.

Per informazioni sui dettagli di impostazione e configurazione, vedere la panoramica.

Le decisioni di ridimensionamento di Cosmos DB per i piani a consumo e Premium vengono eseguite tramite il ridimensionamento basato su destinazione. Per altre informazioni, vedere Scalabilità basata su destinazione.

Importante

Questo articolo usa schede per supportare le versioni diverse del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per gli sviluppatori di Node.js per Funzioni di Azure. Altre informazioni sulle differenze tra i modelli v3 e v4 sono disponibili nella guida alla migrazione.

Funzioni di Azure supporta due modelli di programmazione per Python. Il modo in cui si definiscono le associazioni dipende dal modello di programmazione scelto.

Il modello di programmazione Python v2 consente di definire associazioni usando elementi Decorator direttamente nel codice della funzione Python. Per altre informazioni, vedere la Guida per sviluppatori Python.

Questo articolo supporta entrambi i modelli di programmazione.

Esempio

L'utilizzo del trigger dipende dalla versione del pacchetto di estensione e dalla modalità C# usata nell'app per le funzioni, 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.

Gli esempi seguenti dipendono dalla versione dell'estensione per la modalità C# specificata.

Questo esempio si riferisce a un tipo ToDoItem semplice:

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

La funzione seguente viene richiamata quando sono presenti inserimenti o aggiornamenti nel database e nella raccolta specificati.

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "ToDoItems",
    containerName:"TriggerItems",
    Connection = "CosmosDBConnection",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> todoItems,
    FunctionContext context)
{
    if (todoItems is not null && todoItems.Any())
    {
        foreach (var doc in todoItems)
        {
            _logger.LogInformation("ToDoItem: {desc}", doc.Description);
        }
    }
}

Questa funzione viene richiamata quando sono presenti inserimenti o aggiornamenti nel database e nel contenitore specificati.

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.

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

Nella libreria di runtime delle funzioni Java usare l'annotazione @CosmosDBTrigger sui parametri il cui valore proviene da Azure Cosmos DB. Questa annotazione è utilizzabile con i tipi Java nativi, con oggetti POJO o con valori nullable tramite Optional<T>.

L'esempio seguente illustra una funzione TypeScript trigger di Azure Cosmos DB. La funzione scrive messaggi di log quando i record di Azure Cosmos DB vengono aggiunti o modificati.

import { app, InvocationContext } from '@azure/functions';

export async function cosmosDBTrigger1(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);
}

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: cosmosDBTrigger1,
});

L'esempio seguente illustra una funzione JavaScript trigger di Azure Cosmos DB. La funzione scrive messaggi di log quando i record di Azure Cosmos DB vengono aggiunti o modificati.

const { app } = require('@azure/functions');

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        context.log(`Cosmos DB function processed ${documents.length} documents`);
    },
});

L'esempio seguente illustra come eseguire una funzione come modifiche ai dati in Azure Cosmos DB.

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Si noti che alcuni nomi degli attributi di associazione sono stati modificati nella versione 4.x dell'estensione Azure Cosmos DB.

Nel file run.ps1 è possibile accedere al documento che attiva la funzione tramite il $Documents parametro .

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

L'esempio seguente illustra un'associazione di trigger di Azure Cosmos DB. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(name="documents", 
                       connection="CONNECTION_SETTING",
                       database_name="DB_NAME", 
                       container_name="CONTAINER_NAME", 
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def test_function(documents: func.DocumentList) -> str:
    if documents:
        logging.info('Document id: %s', documents[0]['id'])

Attributi

Sia le librerie C# in-process che isolate usano CosmosDBTriggerAttribute per definire la funzione. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Proprietà dell'attributo Descrizione
Connessione Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB monitorato. Per altre informazioni, vedere Connections.
DatabaseName Nome del database Azure Cosmos DB con il contenitore monitorato.
ContainerName Nome del contenitore monitorato.
LeaseConnection (Facoltativo) Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB che contiene il contenitore di lease.

Se non impostato, viene usato il valore Connection. Questo parametro viene impostato automaticamente al momento della creazione dell'associazione nel portale. La stringa di connessione per il contenitore di lease deve disporre di autorizzazioni di scrittura.
LeaseDatabaseName (Facoltativo) Nome del database che contiene il contenitore utilizzato per archiviare i lease. Se non impostato, viene usato il valore dell'impostazione databaseName.
LeaseContainerName (Facoltativo) Nome del contenitore usato per archiviare i lease. Se non impostato, viene usato il valore leases.
CreateLeaseContainerIfNotExists (Facoltativo) Se impostato su true, il contenitore lease viene creato automaticamente se non è già esistente. Il valore predefinito è false. Quando si usano le identità di Microsoft Entra se si imposta il valore su true, la creazione di contenitori non è un'operazione consentita e la funzione non sarà in grado di avviare.
LeasesContainerThroughput (Facoltativo) Definisce il numero di unità richiesta da assegnare quando viene creato il contenitore lease. Questa impostazione viene usata solo quando CreateLeaseContainerIfNotExists è impostato su true. Questo parametro viene impostato automaticamente al momento della creazione dell'associazione tramite il portale.
LeaseContainerPrefix (Facoltativo) Se impostato, il valore viene aggiunto come prefisso ai lease creati nel contenitore Lease per questa funzione. L'uso di un prefisso consente a due funzioni di Azure diverse di condividere lo stesso contenitore lease usando prefissi diversi.
FeedPollDelay (Facoltativo) Tempo (in millisecondi) per il ritardo tra il polling di una partizione per le nuove modifiche nel feed, dopo che tutte le modifiche correnti vengono svuotate. Il valore predefinito è 5.000 millisecondi o 5 secondi.
LeaseAcquireInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo per l'avvio di un'attività che consente di calcolare se le partizioni sono distribuite equamente tra le istanze di host note. Il valore predefinito è 13000 (13 secondi).
LeaseExpirationInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo che indica la durata di un lease su un lease che rappresenta una partizione. Se il lease non viene rinnovato entro questo intervallo, ne comporterà la scadenza e la proprietà della partizione passerà a un'altra istanza. Il valore predefinito è 60000 (60 secondi).
LeaseRenewInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo di rinnovo per tutti i lease per le partizioni attualmente occupate da un'istanza. Il valore predefinito è 17000 (17 secondi).
MaxItemsPerInvocation (Facoltativo) Se impostata, questa proprietà imposta il numero massimo di elementi ricevuti per ogni chiamata di Funzione. Se le operazioni nel contenitore monitorato vengono eseguite tramite stored procedure, l'ambito della transazione viene mantenuto durante la lettura degli elementi dal feed di modifiche. Di conseguenza, il numero di elementi ricevuti potrebbe essere superiore al valore specificato in modo che gli elementi modificati dalla stessa transazione vengano restituiti come parte di un batch atomico.
StartFromBeginning (Facoltativo) Questa opzione indica al trigger di leggere le modifiche dall'inizio della cronologia delle modifiche del contenitore anziché a partire dall'ora corrente. La lettura dall'inizio funziona solo la prima volta che il trigger viene avviato, come nelle esecuzioni successive, i checkpoint sono già archiviati. L'impostazione di questa opzione su true quando sono già stati creati lease non ha alcun effetto.
StartFromTime (Facoltativo) Ottiene o imposta la data e l'ora da cui inizializzare l'operazione di lettura del feed di modifiche. Il formato consigliato è ISO 8601 con l'identificatore UTC, ad esempio 2021-02-16T14:19:29Z. Viene usato solo per impostare lo stato del trigger iniziale. Dopo che il trigger ha uno stato di lease, la modifica di questo valore non ha alcun effetto.
PreferredLocations (Facoltativo) Definisce le posizioni preferite (aree) per gli account di database con replica geografica nel servizio Azure Cosmos DB. I valori devono essere delimitati da virgole. Ad esempio, "Stati Uniti orientali, Stati Uniti centro-meridionali, Europa settentrionale".

Elementi Decorator

Si applica solo al modello di programmazione Python v2.

Per le funzioni Python v2 definite usando un elemento Decorator, le proprietà seguenti in cosmos_db_trigger:

Proprietà Descrizione
arg_name Il nome della variabile usato nel codice funzione che rappresenta l'elenco di documenti con le modifiche.
database_name Il nome del database di Azure Cosmos DB con la raccolta monitorata.
collection_name Nome della raccolta di Azure Cosmos DB monitorata.
connection Il stringa di connessione di Azure Cosmos DB monitorato.

Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione .

Annotazioni

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.

Usare l'annotazione @CosmosDBTrigger sui parametri che leggono i dati da Azure Cosmos DB. L'annotazione supporta le proprietà seguenti:

Proprietà dell'attributo Descrizione
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB monitorato. Per altre informazioni, vedere Connections.
name Nome della funzione.
databaseName Nome del database Azure Cosmos DB con il contenitore monitorato.
containerName Nome del contenitore monitorato.
leaseConnectionStringSetting (Facoltativo) Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB che contiene il contenitore di lease.

Se non impostato, viene usato il valore Connection. Questo parametro viene impostato automaticamente al momento della creazione dell'associazione nel portale. La stringa di connessione per il contenitore di lease deve disporre di autorizzazioni di scrittura.
leaseDatabaseName (Facoltativo) Nome del database che contiene il contenitore utilizzato per archiviare i lease. Se non impostato, viene usato il valore dell'impostazione databaseName.
leaseContainerName (Facoltativo) Nome del contenitore usato per archiviare i lease. Se non impostato, viene usato il valore leases.
createLeaseContainerIfNotExists (Facoltativo) Se impostato su true, il contenitore lease viene creato automaticamente se non è già esistente. Il valore predefinito è false. Quando si usano le identità di Microsoft Entra se si imposta il valore su true, la creazione di contenitori non è un'operazione consentita e la funzione non verrà avviata.
leasesContainerThroughput (Facoltativo) Definisce il numero di unità richiesta da assegnare quando viene creato il contenitore lease. Questa impostazione viene usata solo quando CreateLeaseContainerIfNotExists è impostato su true. Questo parametro viene impostato automaticamente al momento della creazione dell'associazione tramite il portale.
leaseContainerPrefix (Facoltativo) Se impostato, il valore viene aggiunto come prefisso ai lease creati nel contenitore Lease per questa funzione. L'uso di un prefisso consente a due funzioni di Azure diverse di condividere lo stesso contenitore lease usando prefissi diversi.
feedPollDelay (Facoltativo) Tempo (in millisecondi) per il ritardo tra il polling di una partizione per le nuove modifiche nel feed, dopo che tutte le modifiche correnti vengono svuotate. Il valore predefinito è 5.000 millisecondi o 5 secondi.
leaseAcquireInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo per l'avvio di un'attività che consente di calcolare se le partizioni sono distribuite equamente tra le istanze di host note. Il valore predefinito è 13000 (13 secondi).
leaseExpirationInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo che indica la durata di un lease su un lease che rappresenta una partizione. Se il lease non viene rinnovato entro questo intervallo, scadrà e la proprietà della partizione verrà spostata in un'altra istanza. Il valore predefinito è 60000 (60 secondi).
leaseRenewInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo di rinnovo per tutti i lease per le partizioni attualmente occupate da un'istanza. Il valore predefinito è 17000 (17 secondi).
maxItemsPerInvocation (Facoltativo) Se impostata, questa proprietà imposta il numero massimo di elementi ricevuti per ogni chiamata di Funzione. Se le operazioni nel contenitore monitorato vengono eseguite tramite stored procedure, l'ambito della transazione viene mantenuto durante la lettura degli elementi dal feed di modifiche. Di conseguenza, il numero di elementi ricevuti potrebbe essere superiore al valore specificato in modo che gli elementi modificati dalla stessa transazione vengano restituiti come parte di un batch atomico.
startFromBeginning (Facoltativo) Questa opzione indica al trigger di leggere le modifiche dall'inizio della cronologia delle modifiche del contenitore anziché a partire dall'ora corrente. La lettura dall'inizio funziona solo la prima volta che il trigger viene avviato, come nelle esecuzioni successive, i checkpoint sono già archiviati. L'impostazione di questa opzione su true quando sono già stati creati lease non ha alcun effetto.
preferredLocations (Facoltativo) Definisce le posizioni preferite (aree) per gli account di database con replica geografica nel servizio Azure Cosmos DB. I valori devono essere delimitati da virgole. Ad esempio, "Stati Uniti orientali, Stati Uniti centro-meridionali, Europa settentrionale".

Impostazione

Si applica solo al modello di programmazione Python v1.

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al app.cosmosDB() metodo . Le typeproprietà , directione name non si applicano al modello v4.

La tabella seguente illustra le proprietà di configurazione dell'associazione impostate nel file function.json , in cui le proprietà differiscono per la versione dell'estensione:

Proprietà di function.json Descrizione
type Deve essere impostato su cosmosDBTrigger.
direction Deve essere impostato su in. Questo parametro viene impostato automaticamente quando si crea il trigger nel portale di Azure.
name Il nome della variabile usato nel codice funzione che rappresenta l'elenco di documenti con le modifiche.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB monitorato. Per altre informazioni, vedere Connections.
databaseName Nome del database Azure Cosmos DB con il contenitore monitorato.
containerName Nome del contenitore monitorato.
leaseConnection (Facoltativo) Nome di un'impostazione o di un contenitore di impostazioni dell'app che specifica come connettersi all'account Azure Cosmos DB che contiene il contenitore di lease.

Se non impostato, viene usato il valore connection. Questo parametro viene impostato automaticamente al momento della creazione dell'associazione nel portale. La stringa di connessione per il contenitore di lease deve disporre di autorizzazioni di scrittura.
leaseDatabaseName (Facoltativo) Nome del database che contiene il contenitore utilizzato per archiviare i lease. Se non impostato, viene usato il valore dell'impostazione databaseName.
leaseContainerName (Facoltativo) Nome del contenitore usato per archiviare i lease. Se non impostato, viene usato il valore leases.
createLeaseContainerIfNotExists (Facoltativo) Se impostato su true, il contenitore lease viene creato automaticamente se non è già esistente. Il valore predefinito è false. Quando si usano le identità di Microsoft Entra se si imposta il valore su true, la creazione di contenitori non è un'operazione consentita e la funzione non sarà in grado di avviare.
leasesContainerThroughput (Facoltativo) Definisce il numero di unità richiesta da assegnare quando viene creato il contenitore lease. Questa impostazione viene usata solo quando createLeaseContainerIfNotExists è impostato su true. Questo parametro viene impostato automaticamente al momento della creazione dell'associazione tramite il portale.
leaseContainerPrefix (Facoltativo) Se impostato, il valore viene aggiunto come prefisso ai lease creati nel contenitore Lease per questa funzione. L'uso di un prefisso consente a due funzioni di Azure diverse di condividere lo stesso contenitore lease usando prefissi diversi.
feedPollDelay (Facoltativo) Tempo (in millisecondi) per il ritardo tra il polling di una partizione per le nuove modifiche nel feed, dopo che tutte le modifiche correnti vengono svuotate. Il valore predefinito è 5.000 millisecondi o 5 secondi.
leaseAcquireInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo per l'avvio di un'attività che consente di calcolare se le partizioni sono distribuite equamente tra le istanze di host note. Il valore predefinito è 13000 (13 secondi).
leaseExpirationInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo che indica la durata di un lease su un lease che rappresenta una partizione. Se il lease non viene rinnovato entro questo intervallo, ne comporterà la scadenza e la proprietà della partizione passerà a un'altra istanza. Il valore predefinito è 60000 (60 secondi).
leaseRenewInterval (Facoltativo) Se impostato, definisce, in millisecondi, l'intervallo di rinnovo per tutti i lease per le partizioni attualmente occupate da un'istanza. Il valore predefinito è 17000 (17 secondi).
maxItemsPerInvocation (Facoltativo) Se impostata, questa proprietà imposta il numero massimo di elementi ricevuti per ogni chiamata di Funzione. Se le operazioni nel contenitore monitorato vengono eseguite tramite stored procedure, l'ambito della transazione viene mantenuto durante la lettura degli elementi dal feed di modifiche. Di conseguenza, il numero di elementi ricevuti potrebbe essere superiore al valore specificato in modo che gli elementi modificati dalla stessa transazione vengano restituiti come parte di un batch atomico.
startFromBeginning (Facoltativo) Questa opzione indica al trigger di leggere le modifiche dall'inizio della cronologia delle modifiche del contenitore anziché a partire dall'ora corrente. La lettura dall'inizio funziona solo la prima volta che il trigger viene avviato, come nelle esecuzioni successive, i checkpoint sono già archiviati. L'impostazione di questa opzione su true quando sono già stati creati lease non ha alcun effetto.
startFromTime (Facoltativo) Ottiene o imposta la data e l'ora da cui inizializzare l'operazione di lettura del feed di modifiche. Il formato consigliato è ISO 8601 con l'identificatore UTC, ad esempio 2021-02-16T14:19:29Z. Viene usato solo per impostare lo stato del trigger iniziale. Dopo che il trigger ha uno stato di lease, la modifica di questo valore non ha alcun effetto.
preferredLocations (Facoltativo) Definisce le posizioni preferite (aree) per gli account di database con replica geografica nel servizio Azure Cosmos DB. I valori devono essere delimitati da virgole. Ad esempio, "Stati Uniti orientali, Stati Uniti centro-meridionali, Europa settentrionale".

Per esempi completi, vedere la sezione di esempio.

Utilizzo

Il trigger richiede una seconda raccolta usata per archiviare i lease nelle partizioni. Sia la raccolta monitorata che la raccolta che contiene i lease deve essere disponibile affinché il trigger funzioni.

Importante

Se più funzioni sono configurate per l'uso di un trigger di Azure Cosmos DB per la stessa raccolta, ognuna delle funzioni deve usare una raccolta di lease dedicata o specificare un'altra LeaseCollectionPrefix per ogni funzione. In caso contrario, viene attivata solo una delle funzioni. Per informazioni sul prefisso, vedere la sezione Attributi.

Importante

Se più funzioni sono configurate per l'uso di un trigger di Azure Cosmos DB per la stessa raccolta, ognuna delle funzioni deve usare una raccolta di lease dedicata o specificare un'altra leaseCollectionPrefix per ogni funzione. In caso contrario, viene attivata solo una delle funzioni. Per informazioni sul prefisso, vedere la sezione Annotazioni.

Importante

Se più funzioni sono configurate per l'uso di un trigger di Azure Cosmos DB per la stessa raccolta, ognuna delle funzioni deve usare una raccolta di lease dedicata o specificare un'altra leaseCollectionPrefix per ogni funzione. In caso contrario verrà attivata solo una delle funzioni. Per informazioni sul prefisso, vedere la sezione relativa alla configurazione.

Il trigger non indica se un documento è stato aggiornato o aggiunto, fornisce solo il documento stesso. Se è necessario gestire aggiornamenti e aggiunte in modo diverso, è possibile implementare campi di timestamp per le aggiunte o gli aggiornamenti.

Il tipo di parametro supportato dal trigger di Azure Cosmos DB dipende dalla versione del runtime di Funzioni, dalla versione del pacchetto di estensione e dalla modalità C# usata.

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.

Connessioni

Le connectionStringSetting/connection proprietà e leaseConnectionStringSetting/leaseConnection sono riferimenti alla configurazione dell'ambiente che specifica come l'app deve connettersi ad Azure Cosmos DB. Possono specificare:

Se il valore configurato è una corrispondenza esatta per una singola impostazione e una corrispondenza di prefisso per altre impostazioni, viene usata la corrispondenza esatta.

Stringa di connessione

Il stringa di connessione per l'account di database deve essere archiviato in un'impostazione dell'applicazione con un nome corrispondente al valore specificato dalla proprietà di connessione della configurazione dell'associazione.

Connessioni basate su identità

Se si usa la versione 4.x o successiva dell'estensione, invece di usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità Microsoft Entra. A tale scopo, è necessario definire le impostazioni in un prefisso comune che esegue il mapping alla proprietà connection nella configurazione del trigger e dell'associazione.

In questa modalità, l'estensione richiede le proprietà seguenti:

Proprietà Modello di variabile di ambiente Descrizione Valore di esempio
Account Endpoint <CONNECTION_NAME_PREFIX>__accountEndpoint URI dell'endpoint dell'account Azure Cosmos DB. <https:// database_account_name.documents.azure.com:443/>

È possibile impostare proprietà aggiuntive per personalizzare la connessione. Vedere Proprietà comuni per le connessioni basate su identità.

Quando sono ospitate nel servizio Azure Functions, le connessioni basate su identità usano una identità gestita. Per impostazione predefinita, viene usata l’identità assegnata a livello di sistema, ma è comunque possibile specificare un’identità assegnata dall’utente a cui siano associate le proprietà credential e clientID. Si noti che la configurazione di un'identità assegnata dall'utente con un ID risorsa non è supportata. Quando viene eseguita in altri contesti, ad esempio lo sviluppo locale, viene usata l'identità dello sviluppatore, anche se può essere personalizzata. Vedere Sviluppo locale con connessioni basate su identità.

Concedere l'autorizzazione all'identità

Qualsiasi identità usata deve avere le autorizzazioni necessarie per eseguire le azioni previste. Per la maggior parte dei servizi di Azure, questo significa che è necessario assegnare un ruolo nel controllo degli accessi in base al ruolo di Azure, usando ruoli predefiniti o personalizzati che forniscono tali autorizzazioni.

Importante

È possibile che alcune autorizzazioni esposte dal servizio di destinazione non siano necessarie per tutti i contesti. Laddove possibile, rispettare il principio dei privilegi minimi e concedere all’identità solo i privilegi necessari. Ad esempio, se l'app deve essere in grado di leggere solo da un'origine dati, usare un ruolo che disponga solo dell'autorizzazione per la lettura. Sarebbe inappropriato assegnare un ruolo che consenta anche la scrittura in tale servizio, in quanto sarebbe eccessiva l'autorizzazione per un'operazione di lettura. Analogamente, è consigliabile assicurarsi che l'assegnazione di ruolo sia con ambito solo sulle risorse che devono essere lette.

Cosmos DB non usa il controllo degli accessi in base al ruolo di Azure per le operazioni dei dati. Usa invece un sistema RBAC predefinito di Cosmos DB basato su concetti simili. Sarà necessario creare un'assegnazione di ruolo che fornisca l'accesso all'account di database in fase di esecuzione. I ruoli di gestione degli accessi in base al ruolo di Azure, ad esempio Proprietario, non sono sufficienti. La tabella seguente illustra i ruoli predefiniti consigliati quando si usa l'estensione Azure Cosmos DB in condizioni di normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio1
Trigger2 Collaboratore dati predefinito di Cosmos DB
Associazione di input Lettore dati predefinito di Cosmos DB
Associazione di output Collaboratore dati predefinito di Cosmos DB

1 Questi ruoli non possono essere usati in un'assegnazione di ruolo di controllo degli accessi in base al ruolo di Azure. Per informazioni dettagliate su come assegnare questi ruoli, vedere la documentazione del sistema RBAC predefinito di Cosmos DB.

2 Quando si usa l'identità, Cosmos DB considera la creazione del contenitore come operazione di gestione. Non è disponibile come operazione del piano dati per il trigger. È necessario assicurarsi di creare i contenitori necessari per il trigger (incluso il contenitore di lease) prima di configurare la funzione.

Passaggi successivi