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

  • Articolo

L'associazione di output di Azure Cosmos DB consente di scrivere un nuovo documento in un database di Azure Cosmos DB tramite l'API SQL.

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

Importante

Questo articolo usa schede per supportare più versioni 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 sviluppatori di Funzioni di Azure Node.js. Per altre informazioni sulle differenze tra v3 e v4, vedere la 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.

È possibile creare una funzione C# usando una delle modalità C# seguenti:

  • Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano Microsoft.Azure.Functions.Worker.Extensions.* spazi dei nomi.
  • Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano Microsoft.Azure.WebJobs.Extensions.* spazi dei nomi.

Importante

Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

Esempio

Se non diversamente specificato, gli esempi in questo articolo sono destinati alla versione 3.x dell'estensione Azure Cosmos DB. Per l'uso con l'estensione versione 4.x, è necessario sostituire la stringa collection nei nomi delle proprietà e degli attributi con e connection_string_setting con containerconnection.

Il codice seguente definisce un MyDocument tipo:

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

Nell'esempio seguente il tipo restituito è un IReadOnlyList<T>oggetto , che è un elenco modificato di documenti dal parametro di associazione trigger:

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public class CosmosDBFunction
    {
        private readonly ILogger<CosmosDBFunction> _logger;

        public CosmosDBFunction(ILogger<CosmosDBFunction> logger)
        {
            _logger = logger;
        }

        //<docsnippet_exponential_backoff_retry_example>
        [Function(nameof(CosmosDBFunction))]
        [ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
        [CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
        public object Run(
            [CosmosDBTrigger(
                "%CosmosDb%",
                "%CosmosContainerIn%",
                Connection = "CosmosDBConnection",
                LeaseContainerName = "leases",
                CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
            FunctionContext context)
        {
            if (input != null && input.Any())
            {
                foreach (var doc in input)
                {
                    _logger.LogInformation("Doc Id: {id}", doc.Id);
                }

                // Cosmos Output
                return input.Select(p => new { id = p.Id });
            }

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

Trigger della coda e salvataggio di un messaggio nel database tramite il valore restituito

L'esempio seguente mostra una funzione Java che aggiunge un documento a un database con i dati da un messaggio dall'archiviazione code.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

Trigger HTTP e salvataggio di un documento nel database tramite il valore restituito

L'esempio seguente mostra una funzione Java la cui firma viene annotata con @CosmosDBOutput e con valore restituito di tipo String. Il documento JSON restituito dalla funzione verrà scritto automaticamente nella raccolta di Azure Cosmos DB corrispondente.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

Trigger HTTP e salvataggio di un documento nel database tramite OutputBinding

L'esempio seguente illustra una funzione Java che scrive un documento in Azure Cosmos DB tramite un OutputBinding<T> parametro di output. In questo esempio, il outputItem parametro deve essere annotato con @CosmosDBOutput, non con la firma della funzione. L'uso OutputBinding<T> consente alla funzione di sfruttare l'associazione per scrivere il documento in Azure Cosmos DB, consentendo al contempo di restituire un valore diverso al chiamante di funzione, ad esempio un documento JSON o XML.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

Trigger HTTP e salvataggio di più documenti nel database tramite OutputBinding

L'esempio seguente illustra una funzione Java che scrive più documenti in Azure Cosmos DB tramite un OutputBinding<T> parametro di output. In questo esempio il outputItem parametro viene annotato con @CosmosDBOutput, non con la firma della funzione. Il parametro di output outputItem include un elenco di oggetti ToDoItem come tipo di parametro di modello. L'uso OutputBinding<T> consente alla funzione di sfruttare il binding per scrivere i documenti in Azure Cosmos DB, consentendo al contempo di restituire un valore diverso al chiamante di funzione, ad esempio un documento JSON o XML.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

Nella libreria di runtime delle funzioni Java usare l'annotazione @CosmosDBOutput sui parametri che verranno scritti in Azure Cosmos DB. Il tipo di parametro di annotazione deve essere OutputBinding<T>, dove T è un tipo Java nativo o un POJO.

L'esempio seguente mostra una funzione TypeScript attivata dalla coda di archiviazione per una coda che riceve JSON nel formato seguente:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

La funzione crea documenti di Azure Cosmos DB nel formato seguente per ogni record:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Ecco il codice TypeScript:

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

interface MyQueueItem {
    name: string;
    employeeId: string;
    address: string;
}

interface MyCosmosItem {
    id: string;
    name: string;
    employeeId: string;
    address: string;
}

export async function storageQueueTrigger1(queueItem: MyQueueItem, context: InvocationContext): Promise<MyCosmosItem> {
    return {
        id: `${queueItem.name}-${queueItem.employeeId}`,
        name: queueItem.name,
        employeeId: queueItem.employeeId,
        address: queueItem.address,
    };
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: output.cosmosDB({
        databaseName: 'MyDatabase',
        collectionName: 'MyCollection',
        createIfNotExists: true,
        connectionStringSetting: 'MyAccount_COSMOSDB',
    }),
    handler: storageQueueTrigger1,
});

Per restituire più documenti, restituire una matrice anziché un singolo oggetto. Ad esempio:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

L'esempio seguente mostra una funzione JavaScript attivata dalla coda di archiviazione per una coda che riceve JSON nel formato seguente:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

La funzione crea documenti di Azure Cosmos DB nel formato seguente per ogni record:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Ecco il codice JavaScript:

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

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: true,
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: cosmosOutput,
    handler: (queueItem, context) => {
        return {
            id: `${queueItem.name}-${queueItem.employeeId}`,
            name: queueItem.name,
            employeeId: queueItem.employeeId,
            address: queueItem.address,
        };
    },
});

Per restituire più documenti, restituire una matrice anziché un singolo oggetto. Ad esempio:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

L'esempio seguente illustra come scrivere dati in Azure Cosmos DB usando un'associazione di output. L'associazione viene dichiarata nel file di configurazione della funzione (functions.json) e accetta i dati da un messaggio di coda e scrive in un documento di Azure Cosmos DB.

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
}

Nel file run.ps1 l'oggetto restituito dalla funzione viene mappato a un EmployeeDocument oggetto , che viene salvato in modo permanente nel database.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

L'esempio seguente illustra come scrivere un documento in un database di Azure Cosmos DB come output di una funzione. 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.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

Attributi

Sia le librerie C# in-process che il processo di lavoro isolato usano attributi 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 Connessione ions.
DatabaseName Nome del database Azure Cosmos DB con il contenitore monitorato.
Containername Nome del contenitore monitorato.
CreateIfNotExists Valore booleano per indicare se il contenitore viene creato quando non esiste. Il valore predefinito è false perché vengono creati nuovi contenitori con velocità effettiva riservata, con implicazioni sui costi. Per ulteriori informazioni, vedere la pagina dei prezzi.
PartitionKey Quando CreateIfNotExists è true, definisce il percorso della chiave di partizione per il contenitore creato. Può includere i parametri di associazione.
ContainerThroughput Quando CreateIfNotExists è true, definisce la velocità effettiva del contenitore creato.
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: East US,South Central US,North Europe.

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_output:

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.
create_if_not_exists Valore booleano che indica se il database e la raccolta devono essere creati se non esistono.
connection_string_setting Il stringa di connessione di Azure Cosmos DB monitorato.

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

Annotazioni

Dalla libreria di runtime delle funzioni Java usare l'annotazione @CosmosDBOutput sui parametri che scrivono in Azure Cosmos DB. L'annotazione supporta le proprietà seguenti:

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 output.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
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 Connessione ions.
databaseName Nome del database Azure Cosmos DB con il contenitore monitorato.
containerName Nome del contenitore monitorato.
createIfNotExists Valore booleano per indicare se il contenitore viene creato quando non esiste. Il valore predefinito è false perché vengono creati nuovi contenitori con velocità effettiva riservata, con implicazioni sui costi. Per ulteriori informazioni, vedere la pagina dei prezzi.
partitionKey Quando createIfNotExists è true, definisce il percorso della chiave di partizione per il contenitore creato. Può includere i parametri di associazione.
containerThroughput Quando createIfNotExists è true, definisce la velocità effettiva del contenitore creato.
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: East US,South Central US,North Europe.

Per esempi completi, vedere la sezione Esempio.

Utilizzo

Per impostazione predefinita, quando si scrive nel parametro di output della funzione, viene creato un documento nel database. È necessario specificare l'ID documento del documento di output specificando la id proprietà nell'oggetto JSON passato al parametro di output.

Nota

Quando si specifica l'ID di un documento esistente, questo viene sovrascritto dal nuovo documento di output.

Il tipo di parametro supportato dall'associazione di output di 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 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 .

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.

Connection string

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 di controllo degli accessi in base al ruolo predefinito di Cosmos DB basato su concetti simili. Sarà necessario creare un'assegnazione di ruolo che fornisce l'accesso all'account di database in fase di esecuzione. I ruoli di gestione controllo 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 nel normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione Ruoli predefinitidi esempio 1
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 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 di contenitori 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.

Eccezioni e codici restituiti

Binding Riferimento
Azure Cosmos DB Codici di stato HTTP per Azure Cosmos DB

Passaggi successivi