Azure Cosmos DB trigger para Funções do Azure 2.x e superiores

O modelo de programação Python v2 permite-te definir bindings usando decoradores diretamente no teu código de função Python. Para mais informações, consulte o guia para desenvolvedores Python.

O modelo de programação Python v1 exige que definas bindings num ficheiro separado function.json na pasta de funções. Para mais informações, consulte o guia para desenvolvedores Python.

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

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

Aplicações que usam a extensão Azure Cosmos DB versão 4.x ou superior usam propriedades de atributos diferentes. Esta secção mostra essas propriedades. O exemplo usa referências nas definições da aplicação e inclui o 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 definições da aplicação (%VAR_NAME%) em vez de valores codificados fixamente.

Definições da aplicação

Configure estas definições de aplicação para ligações baseadas em identidade:

Desenvolvimento local

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

{
    "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 o desenvolvimento local:

• CLI do Azure com az login concluído
• Emulador de armazenamento Azurite a correr (azurite --silent)

O exemplo seguinte mostra uma função C# que é executada quando ocorrem inserções ou atualizações na base de dados e coleção especificadas.

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 utiliza referências nas definições da aplicação e inclui o tratamento de erros. Primeiro, defina o seu tipo de modelo:

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

A seguinte função executa-se quando ocorrem inserções ou atualizações na base de dados e contentor 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 definições da aplicação (%VAR_NAME%) em vez de valores codificados fixamente. Para detalhes de configuração, consulte as definições da aplicação e orientações de desenvolvimento local no separador em processo.

O código a seguir define um 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; }
}

O exemplo seguinte utiliza um IReadOnlyList<T> como parâmetro de ligaçã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 using instruções:

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

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

    @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 seguinte mostra um trigger Azure Cosmos DB TypeScript. A função escreve mensagens de registo quando registos do Azure Cosmos DB 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,
});

Os exemplos do TypeScript não estão documentados para o modelo v3.

O exemplo seguinte mostra um gatilho Azure Cosmos DB JavaScript. A função escreve mensagens de registo quando registos do Azure Cosmos DB 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 seguinte mostra uma ligação de gatilho Azure Cosmos DB num ficheiro function.json e uma função JavaScript que utiliza essa ligação. A função escreve mensagens de registo quando registos do Azure Cosmos DB são adicionados ou modificados.

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

Note que alguns dos nomes dos atributos de ligação mudaram 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 definições da aplicação (%VAR_NAME%) em vez de valores codificados fixamente.

Definições da aplicação

Configure estas definições de aplicação para ligações baseadas em identidade:

Desenvolvimento local

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

{
    "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 o desenvolvimento local:

• CLI do Azure com az login concluído
• Emulador de armazenamento Azurite a correr (azurite --silent)

A função escreve mensagens de log quando os registos do Azure Cosmos DB são modificados. Aqui estão os dados de ligaçã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
}

Note que alguns dos nomes dos atributos de ligação mudaram na versão 4.x da extensão Azure Cosmos DB.

Aqui está o código em 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 utilizam CosmosDBTriggerAttribute do espaço de nomes Microsoft.Azure.WebJobs, que define estas propriedades:

As bibliotecas em processo utilizam CosmosDBTriggerAttribute do espaço de nomes Microsoft.Azure.WebJobs, que define estas propriedades:

Bibliotecas de processos trabalhadores isolados usam CosmosDBTriggerAttribute do espaço de nomes Microsoft.Azure.Functions.Worker, que define estas propriedades:

Bibliotecas de processos trabalhadores isolados usam CosmosDBTriggerAttribute do espaço de nomes Microsoft.Azure.Functions.Worker, que define estas propriedades:

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

Use a anotação @CosmosDBTrigger em parâmetros que leem dados de Azure Cosmos DB. A anotação suporta as seguintes propriedades:

A partir da biblioteca de runtime de funções Java, use a anotação @CosmosDBTrigger nos parâmetros que leem dados de Azure Cosmos DB. A anotação suporta as seguintes propriedades:

• Designação
• connectionStringSetting
• Nome do banco de dados
• collectionName
• leaseConnectionStringSetting
• leaseDatabaseName
• leaseCollectionName
• createLeaseCollectionIfNotExists
• leasesCollectionThroughput
• leaseCollectionPrefix
• feedPollDelay
• leaseAcquireInterval
• leaseExpirationInterval
• leaseRenewInterval
• checkpointInterval
• ponto de verificaçãoDocumentCount
• maxItemsPerInvocation
• startFromBeginning
• preferredLocations

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

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json, onde as propriedades diferem de acordo com a versão da extensão:

Consulte Tipos de vinculação para obter uma lista de tipos suportados.

Para uma lista de tipos suportados, veja Tipos de ligação.

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

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

Para uma lista de tipos suportados, veja Tipos de ligação.