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

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.

Il modello di programmazione Python v1 richiede di definire associazioni in un file separato function.json nella cartella della funzione. Per altre informazioni, vedere la guida per sviluppatori Python.

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

Una libreria di classi in-process è una funzione C# compilata che viene eseguita nello stesso processo del runtime di Funzioni.

Le app che usano Azure Cosmos DB estensione versione 4.x o successive usano proprietà di attributo diverse. In questa sezione vengono illustrate le proprietà. L'esempio usa i riferimenti alle impostazioni dell'app e include la gestione degli errori.

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

using System;
using System.Collections.Generic;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "%COSMOS_DATABASE_NAME%",
            containerName: "%COSMOS_CONTAINER_NAME%",
            Connection = "COSMOS_CONNECTION",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> documents, ILogger log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.LogInformation("Documents modified: {count}", documents.Count);
                foreach (var doc in documents)
                {
                    try
                    {
                        log.LogInformation("Processing document Id: {id}", doc.id);
                        // Add your business logic here
                    }
                    catch (Exception ex)
                    {
                        log.LogError(ex, "Error processing document {id}", doc.id);
                        // Continue processing remaining documents
                    }
                }
            }
        }

        [FunctionName("health")]
        public static IActionResult HealthCheck(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "health")] HttpRequest req)
        {
            return new OkResult();
        }
    }
}

L'esempio precedente usa riferimenti alle impostazioni dell'app (%VAR_NAME%) anziché valori hardcoded.

Impostazioni dell'app

Configurare queste impostazioni dell'applicazione per le connessioni basate su identità:

Sviluppo locale

Per lo sviluppo locale, creare un local.settings.json file:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "COSMOS_DATABASE_NAME": "my-database",
        "COSMOS_CONTAINER_NAME": "my-container",
        "COSMOS_CONNECTION__accountEndpoint": "https://mycosmosdb.documents.azure.com:443/"
    }
}

Prerequisiti per lo sviluppo locale:

• interfaccia della riga di comando di Azure con az login completata
• Emulatore di archiviazione Azurite in esecuzione (azurite --silent)

L'esempio seguente illustra una funzione C# che viene eseguita quando si verificano inserimenti o aggiornamenti nel database e nella raccolta specificati.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            ILogger log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.LogInformation($"Documents modified: {documents.Count}");
                log.LogInformation($"First document Id: {documents[0].Id}");
            }
        }
    }
}

Questo esempio usa i riferimenti alle impostazioni dell'app e include la gestione degli errori. Prima di tutto, definire il tipo di modello:

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

La funzione seguente viene eseguita quando si verificano inserimenti o aggiornamenti nel database e nel contenitore specificati:

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "%COSMOS_DATABASE_NAME%",
    containerName: "%COSMOS_CONTAINER_NAME%",
    Connection = "COSMOS_CONNECTION",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> documents,
    FunctionContext context)
{
    if (documents is not null && documents.Any())
    {
        _logger.LogInformation("Documents modified: {count}", documents.Count);
        foreach (var doc in documents)
        {
            try
            {
                _logger.LogInformation("Processing document Id: {id}", doc.Id);
                // Add your business logic here
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error processing document {id}", doc.Id);
                // Continue processing remaining documents
            }
        }
    }
}

[Function("health")]
public IActionResult HealthCheck([HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "health")] HttpRequest req)
{
    return new OkResult();
}

L'esempio precedente usa riferimenti alle impostazioni dell'app (%VAR_NAME%) anziché valori hardcoded. Per informazioni dettagliate sulla configurazione, vedi le impostazioni dell'app e le linee guida per lo sviluppo locale nella scheda in-process.

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; }
}

L'esempio seguente usa un IReadOnlyList<T> come parametro di associazione trigger Azure Cosmos DB:

[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;
}

Questo esempio richiede le istruzioni seguenti using :

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

A causa delle modifiche dello schema nell'SDK di Azure Cosmos DB, la versione 4.x dell'estensione Azure Cosmos DB richiede azure-functions-java-library V3.0.0 per le funzioni di 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());
    }

    @FunctionName("cosmosDBMonitor")
    public void cosmosDbProcessor(
        @CosmosDBTrigger(name = "items",
            databaseName = "ToDoList",
            collectionName = "Items",
            leaseCollectionName = "leases",
            createLeaseCollectionIfNotExists = true,
            connectionStringSetting = "AzureCosmosDBConnection") String[] items,
            final ExecutionContext context ) {
                context.getLogger().info(items.length + "item(s) is/are changed.");
            }

Nell'esempio seguente viene illustrato un trigger Azure Cosmos DB TypeScript. La funzione scrive messaggi di log quando Azure Cosmos DB record 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,
});

Gli esempi typeScript non sono documentati per il modello v3.

L'esempio seguente mostra una funzione trigger Azure Cosmos DB JavaScript. La funzione scrive messaggi di log quando Azure Cosmos DB record 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 un'associazione di trigger Azure Cosmos DB in un file function.json e una funzione JavaScript che usa l'associazione. La funzione scrive messaggi di log quando Azure Cosmos DB record vengono aggiunti o modificati.

Ecco i dati di associazione nel file function.json:

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

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

Ecco il codice JavaScript:

    module.exports = async function (context, documents) {
      context.log('First document Id modified : ', documents[0].id);
    }

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(arg_name="documents", 
                       database_name="%COSMOS_DATABASE_NAME%", 
                       container_name="%COSMOS_CONTAINER_NAME%",
                       connection="COSMOS_CONNECTION",
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def cosmos_trigger(documents: func.DocumentList) -> str:
    if documents:
        for doc in documents:
            try:
                logging.info('Processing document id: %s', doc['id'])
                # Add your business logic here
            except Exception as e:
                logging.error('Error processing document %s: %s', doc.get('id', 'unknown'), str(e))
                # Continue processing remaining documents

@app.function_name(name="health")
@app.route(route="health", methods=["GET"])
def health_check(req: func.HttpRequest) -> func.HttpResponse:
    """Health check endpoint for monitoring."""
    return func.HttpResponse("OK", status_code=200)

L'esempio precedente usa riferimenti alle impostazioni dell'app (%VAR_NAME%) anziché valori hardcoded.

Impostazioni dell'app

Configurare queste impostazioni dell'applicazione per le connessioni basate su identità:

Sviluppo locale

Per lo sviluppo locale, creare un local.settings.json file:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "python",
        "COSMOS_DATABASE_NAME": "my-database",
        "COSMOS_CONTAINER_NAME": "my-container",
        "COSMOS_CONNECTION__accountEndpoint": "https://mycosmosdb.documents.azure.com:443/"
    }
}

Prerequisiti per lo sviluppo locale:

• interfaccia della riga di comando di Azure con az login completata
• Emulatore di archiviazione Azurite in esecuzione (azurite --silent)

La funzione scrive messaggi di log quando vengono modificati i record Azure Cosmos DB. Ecco i dati di associazione nel file function.json:

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

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

Ecco il codice Python:

    import logging
    import azure.functions as func


    def main(documents: func.DocumentList) -> str:
        if documents:
            logging.info('First document Id modified: %s', documents[0]['id'])

Le librerie in-process usano CosmosDBTriggerAttribute dallo spazio dei nomi Microsoft.Azure.WebJobs, che definisce queste proprietà:

Le librerie in-process usano CosmosDBTriggerAttribute dallo spazio dei nomi Microsoft.Azure.WebJobs, che definisce queste proprietà:

Le librerie di processi di lavoro isolate usano CosmosDBTriggerAttribute dallo spazio dei nomi Microsoft.Azure.Functions.Worker, che definisce queste proprietà:

Le librerie di processi di lavoro isolate usano CosmosDBTriggerAttribute dallo spazio dei nomi Microsoft.Azure.Functions.Worker, che definisce queste proprietà:

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

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

Dalla libreria di runtime delle funzioni Java usare l'annotazione @CosmosDBTrigger sui parametri che leggono i dati da Azure Cosmos DB. L'annotazione supporta le proprietà seguenti:

• name
• connectionStringSetting
• databaseName
• collectionName
• leaseConnectionStringSetting
• leaseDatabaseName
• leaseCollectionName
• createLeaseCollectionIfNotExists
• leasesCollectionThroughput
• leaseCollectionPrefix
• feedPollDelay
• leaseAcquireInterval
• leaseExpirationInterval
• leaseRenewInterval
• checkpointInterval
• checkpointDocumentCount
• maxItemsPerInvocation
• startFromBeginning
• preferredLocations

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:

Per un elenco dei tipi supportati, vedere Tipi di binding.

Per un elenco dei tipi supportati, vedere Tipi di binding.

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

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

Per un elenco dei tipi supportati, vedere Tipi di binding.