Azure Cosmos DB gatilho para Azure Functions 2.x e superior

O modelo de programação Python v2 permite definir associações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor Python.

O modelo de programação Python v1 exige que você defina associações em um arquivo function.json separado na pasta de funções. Para obter mais informações, consulte o guia do desenvolvedor Python.

Uma função C# compilada da biblioteca de classes do processo de trabalho isolado é executada em um processo isolado do runtime.

Uma biblioteca de classes em processo é uma função C# compilada no mesmo processo que o runtime do Functions.

Os aplicativos que usam Azure Cosmos DB extensão versão 4.x ou superior usam propriedades de atributo diferentes. Esta seção mostra essas propriedades. O exemplo usa referências de configurações de aplicativo e inclui tratamento de erros.

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

O exemplo anterior usa referências de configurações de aplicativo (%VAR_NAME%) em vez de valores codificados.

Definições da aplicação

Defina estas configurações de aplicativo para conexões baseadas em identidade:

Desenvolvimento local

Para desenvolvimento local, crie um local.settings.json arquivo:

{
    "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/"
    }
}

Pré-requisitos para desenvolvimento local:

• CLI do Azure com az login concluído
• Emulador de armazenamento do Azurite em execução (azurite --silent)

O exemplo a seguir mostra uma função C# que é executada quando as inserções ou atualizações ocorrem no banco de dados e na coleção especificados.

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

Este exemplo usa referências de configurações de aplicativo e inclui tratamento de erros. Primeiro, defina seu tipo de modelo:

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

A função a seguir é executada quando ocorrem inserções ou atualizações no banco de dados e contêiner especificados:

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

O exemplo anterior usa referências de configurações de aplicativo (%VAR_NAME%) em vez de valores codificados. Para obter detalhes de configuração, consulte as configurações do aplicativo e as diretrizes de desenvolvimento local na guia em processo.

O seguinte código define um tipo MyDocument:

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

    public string? Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

O exemplo a seguir usa um IReadOnlyList<T> como o parâmetro de associação de gatilho 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;
}

Este exemplo requer as seguintes instruções using:

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

Devido a alterações de esquema no SDK do Azure Cosmos DB, a versão 4.x da extensão Azure Cosmos DB requer azure-functions-java-library V3.0.0 para funções 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.");
            }

O exemplo a seguir mostra uma função Azure Cosmos DB trigger TypeScript. A função grava mensagens de log quando Azure Cosmos DB registros são adicionados ou modificados.

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

As amostras de TypeScript não estão documentadas para o modelo v3.

O exemplo a seguir mostra um gatilho Azure Cosmos DB A funçãoJavaScript. A função grava mensagens de log quando Azure Cosmos DB registros são adicionados ou modificados.

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`);
    },
});

O exemplo a seguir mostra uma associação de gatilho Azure Cosmos DB em um arquivo function.json e uma função JavaScript que usa a associação. A função grava mensagens de log quando Azure Cosmos DB registros são adicionados ou modificados.

Aqui estão os dados de associação no arquivo 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
}

Observe que alguns dos nomes de atributo de associação foram alterados na versão 4.x da extensão Azure Cosmos DB.

Aqui está o código 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)

O exemplo anterior usa referências de configurações de aplicativo (%VAR_NAME%) em vez de valores codificados.

Definições da aplicação

Defina estas configurações de aplicativo para conexões baseadas em identidade:

Desenvolvimento local

Para desenvolvimento local, crie um local.settings.json arquivo:

{
    "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/"
    }
}

Pré-requisitos para desenvolvimento local:

• CLI do Azure com az login concluído
• Emulador de armazenamento do Azurite em execução (azurite --silent)

A função grava mensagens de log quando Azure Cosmos DB registros são modificados. Aqui estão os dados de associação no arquivo 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
}

Observe que alguns dos nomes de atributo de associação foram alterados na versão 4.x da extensão Azure Cosmos DB.

Este é o código 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'])

As bibliotecas em processo usam CosmosDBTriggerAttribute do namespace Microsoft.Azure.WebJobs, que define estas propriedades:

As bibliotecas em processo usam CosmosDBTriggerAttribute do namespace Microsoft.Azure.WebJobs, que define estas propriedades:

Bibliotecas de processo de trabalho isoladas usam CosmosDBTriggerAttribute do namespace Microsoft.Azure.Functions.Worker, que define estas propriedades:

Bibliotecas de processo de trabalho isoladas usam CosmosDBTriggerAttribute do namespace Microsoft.Azure.Functions.Worker, que define estas propriedades:

Devido a alterações de esquema no SDK do Azure Cosmos DB, a versão 4.x da extensão Azure Cosmos DB requer azure-functions-java-library V3.0.0 para funções Java.

Use a anotação @CosmosDBTrigger em parâmetros que leem dados de Azure Cosmos DB. Essa anotação dá suporte às seguintes propriedades:

Na biblioteca Java functions runtime, use a anotação @CosmosDBTrigger em parâmetros que leem dados de Azure Cosmos DB. Essa anotação dá suporte às seguintes propriedades:

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

A tabela a seguir explica as propriedades que você pode definir no options objeto que você passa para o app.cosmosDB() método. As propriedades type, direction e name não se aplicam ao modelo v4.

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json. Essas propriedades se diferenciam pela versão da extensão:

Consulte Tipos de associação para obter uma lista dos tipos compatíveis.

Para obter uma lista de tipos com suporte, consulte Tipos de associação.

Quando você deseja que a função processe um único documento, o gatilho do Cosmos DB pode ser associado aos seguintes tipos:

Quando você desejar que a função processe um lote de documentos, o gatilho do Cosmos DB pode ser associado aos seguintes tipos:

Para obter uma lista de tipos com suporte, consulte Tipos de associação.