Déclencheur Azure Cosmos DB pour Azure Functions 2.x et supérieur

Le modèle de programmation Python v2 vous permet de définir des liaisons à l'aide d’éléments décoratifs directement dans le code de votre fonction Python. Pour plus d’informations, consultez le guide des développeurs Python.

Le modèle de programmation Python v1 vous oblige à définir des liaisons dans un fichier function.json distinct dans le dossier de fonction. Pour plus d’informations, consultez le guide des développeurs Python.

Une bibliothèque de classes de processus Worker isolé est une fonction C# compilée exécutée dans un processus Worker isolé du runtime.

Une bibliothèque de classes in-process est une fonction C# compilée exécutée dans le même processus que le runtime Functions.

Les applications utilisant l’extension Azure Cosmos DB version 4.x ou ultérieure ont des propriétés d’attribut différentes, qui sont affichées ici. Cet exemple fait référence à un type simple ToDoItem.

namespace CosmosDBSamplesV2
{
    // Customize the model with your own desired properties
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

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: "databaseName",
            containerName: "containerName",
            Connection = "CosmosDBConnectionSetting",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> input, ILogger log)
        {
            if (input != null && input.Count > 0)
            {
                log.LogInformation("Documents modified " + input.Count);
                log.LogInformation("First document Id " + input[0].id);
            }
        }
    }
}

L’exemple suivant montre une fonction C# qui est invoquée lorsqu’il y a des insertions ou mises à jour dans la base de données et la collection spécifiées.

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

Cet exemple fait référence à un type simple ToDoItem :

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

La fonction suivante est appelée quand des insertions ou des mises à jour figurent dans la base de données et la collection spécifiées.

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

Le code suivant définit un type MyDocument :

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

    public string? Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

Un IReadOnlyList<T> utilisé comme paramètre de liaison du déclencheur Azure Cosmos DB dans l’exemple suivant :

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

Cet exemple nécessite les instructions using suivantes :

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

En raison de modifications de schéma dans le kit de développement logiciel (SDK) Azure Cosmos DB, la version 4.x de l’extension Azure Cosmos DB requiert azure-functions-java-library V3.0.0 pour les fonctions 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.");
            }

L’exemple suivant montre une fonction TypeScript de déclencheur Azure Cosmos DB. La fonction écrit des messages de journal quand des enregistrements Azure Cosmos DB sont ajoutés ou modifiés.

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

Les échantillons TypeScript ne sont pas consignés pour le modèle v3.

L’exemple suivant montre une fonction JavaScript de déclencheur Azure Cosmos DB. La fonction écrit des messages de journal quand des enregistrements Azure Cosmos DB sont ajoutés ou modifiés.

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’exemple suivant montre une liaison de déclencheur Azure Cosmos DB dans un fichier function.json et une fonction JavaScript qui utilise la liaison. La fonction écrit des messages de journal quand des enregistrements Azure Cosmos DB sont ajoutés ou modifiés.

Voici les données de liaison dans le fichier 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
}

Notez que certains noms d’attributs de liaison ont été modifiés dans la version 4.x de l’extension Azure Cosmos DB.

Voici le code 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(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'])

La fonction écrit des messages de journal quand des enregistrements Azure Cosmos DB sont modifiés. Voici les données de liaison dans le fichier 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
}

Notez que certains noms d’attributs de liaison ont été modifiés dans la version 4.x de l’extension Azure Cosmos DB.

Voici le code 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'])

En raison de modifications de schéma dans le kit de développement logiciel (SDK) Azure Cosmos DB, la version 4.x de l’extension Azure Cosmos DB requiert azure-functions-java-library V3.0.0 pour les fonctions Java.

Utilisez l’annotation @CosmosDBTrigger sur les paramètres qui lisent les données d’Azure Cosmos DB. L’annotation prend en charge les propriétés suivantes :

À partir de la bibliothèque du runtime des fonctions Java, utilisez l’annotation @CosmosDBTrigger sur les paramètres qui lisent des données à partir d’Azure Cosmos DB. L’annotation prend en charge les propriétés suivantes :

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

Le tableau suivant explique les propriétés que vous pouvez définir pour l’objet options passé à la méthode app.cosmosDB(). Les propriétés type, direction et name ne s’appliquent pas au modèle v4.

Le tableau suivant décrit les propriétés de configuration de la liaison que vous définissez dans le fichier function.json, où les propriétés diffèrent selon la version de l’extension :

Voir Types de liaison pour obtenir une liste des types supportés.

Pour obtenir la liste des types pris en charge, consultez la section Types de liaison.

Quand vous souhaitez que la fonction traite un seul document, le déclencheur Cosmos DB peut se lier aux types suivants :

Quand vous souhaitez que la fonction traite un lot de documents, le déclencheur Cosmos DB peut se lier aux types suivants :

Pour obtenir la liste des types pris en charge, consultez la section Types de liaison.