Desencadenador de Azure Cosmos DB para Azure Functions 2.x y versiones posteriores

Artículo
01/19/2024

El desencadenador de Azure Cosmos DB utiliza la fuente de cambios de Azure Cosmos DB para escuchar las inserciones y actualizaciones de las particiones. La fuente de cambios publica elementos nuevos y actualizados, sin incluir las actualizaciones de las eliminaciones.

Para obtener información sobre los detalles de instalación y configuración, vea la información general.

Las decisiones de escalado de Cosmos DB para los planes de Consumo y Premium se realizan a través del escalado basado en el destino. Para obtener más información, consulte Escalado basado en el destino.

Importante

En este artículo se usan pestañas para admitir varias versiones del modelo de programación de Node.js. El modelo v4 está disponible de forma general y está diseñado para que los desarrolladores de JavaScript y TypeScript tengan una experiencia más flexible e intuitiva. Para más detalles acerca de cómo funciona el modelo v4, consulte la Guía para desarrolladores de Node.js de Azure Functions. Para más información sobre las diferencias entre v3 y v4, consulte la Guía de migración.

Azure Functions admite dos modelos de programación para Python. La forma en que defina los enlaces depende del modelo de programación seleccionado.

El modelo de programación de Python v2 permite definir enlaces mediante decoradores directamente en el código de función de Python. Para más información, consulte la Guía para desarrolladores de Python.

En este artículo se admiten los modelos de programación.

Ejemplo

La utilización del desencadenador depende de la versión del paquete de extensión y la modalidad de C# que se usa en la aplicación de funciones, que puede ser una de las siguientes:

Modelo de trabajo aislado
Modelo de proceso

Una función de C# compilada de la biblioteca de clases de procesos de trabajo aislados se ejecuta en un proceso aislado del entorno de ejecución.

Los ejemplos siguientes dependen de la versión de la extensión para el modo de C# determinado.

Las aplicaciones que usan la extensión de Azure Cosmos DB versión 4.x o superior tienen propiedades de atributo diferentes, que se muestran aquí. En este ejemplo se hace referencia a un tipo 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);
            }
        }
    }
}

En el ejemplo siguiente se muestra un función de C# que se invoca cuando hay inserciones y actualizaciones en la base de datos y colección 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}");
            }
        }
    }
}

En este ejemplo se hace referencia a un tipo simple ToDoItem:

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

La función siguiente invoca cuando hay inserciones y actualizaciones en la base de datos y la colección especificadas.

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

En el código siguiente se define un 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; }
}

IReadOnlyList<T> que se usa como parámetro de enlace del desencadenador de Azure Cosmos DB en el ejemplo siguiente:

[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 ejemplo requiere las siguientes instrucciones using:

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

Esta función se invoca cuando hay inserciones o actualizaciones en la base de datos y el contenedor especificados.

Extensión 4.x y posteriores
Functions 2.x+

Debido a los cambios de esquema en el SDK de Azure Cosmos DB, la versión 4.x de la extensión Azure Cosmos DB requiere azure-functions-java-library V3.0.0 para las funciones 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.");
            }

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @CosmosDBTrigger en los parámetros cuyo valor provendría de Azure Cosmos DB. Esta anotación se puede usar con tipos nativos de Java, POJO o valores que aceptan valores NULL mediante Optional<T>.

Model v4
Modelo v3

En el ejemplo siguiente se muestra una función TypeScript del desencadenador de Azure Cosmos DB. La función escribe mensajes de registro cuando se agregan o modifican los registros de Azure Cosmos DB.

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

Model v4
Modelo v3

En el ejemplo siguiente se muestra una función JavaScript del desencadenador de Azure Cosmos DB. La función escribe mensajes de registro cuando se agregan o modifican los registros de Azure Cosmos DB.

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

En el ejemplo siguiente se muestra un enlace de desencadenador de Azure Cosmos DB en un archivo function.json y una función de JavaScript que usa dicho enlace. La función escribe mensajes de registro cuando se agregan o modifican los registros de Azure Cosmos DB.

Estos son los datos de enlace del archivo function.json:

Functions 2.x+
Functions 4.x+

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

Tenga en cuenta que algunos de los nombres de atributo de enlace cambiaron en la versión 4.x de la extensión de Azure Cosmos DB.

Este es el código de JavaScript:

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

En el ejemplo siguiente se muestra cómo ejecutar una función a medida que los datos cambian en Azure Cosmos DB.

Functions 2.x+
Functions 4.x+

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

Tenga en cuenta que algunos de los nombres de atributo de enlace cambiaron en la versión 4.x de la extensión de Azure Cosmos DB.

En el archivo run.ps1, tiene acceso al documento que desencadena la función a través del parámetro $Documents.

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)"

En el ejemplo siguiente se muestra un enlace de desencadenador de Azure Cosmos DB. El ejemplo depende de si usa el modelo de programación de Python v1 o v2.

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 función escribe mensajes de registro cuando se modifican los registros de Azure Cosmos DB. Estos son los datos de enlace del archivo function.json:

Functions 2.x+
Functions 4.x+

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

Tenga en cuenta que algunos de los nombres de atributo de enlace cambiaron en la versión 4.x de la extensión de Azure Cosmos DB.

Este es el código de 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'])

Atributos

Las bibliotecas de C# de procesos aislados y en proceso usan el atributo CosmosDBTriggerAttribute para definir la función. En su lugar, el script de C# usa un archivo de configuración function.json como se describe en la Guía de scripting de C#.

Propiedad de atributo	Descripción
Connection	Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
DatabaseName	Nombre de la base de datos de Azure Cosmos DB con el contenedor que se está supervisando.
ContainerName	Nombre del contenedor que se está supervisando.
LeaseConnection	(Opcional) Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que contiene el contenedor de concesión. Si no se establece, se usa el valor `Connection`. Este parámetro se establece automáticamente cuando se crea el enlace en el portal. La cadena de conexión para el contenedor de concesiones debe tener permisos de escritura.
LeaseDatabaseName	(Opcional) Nombre de la base de datos que contiene el contenedor que se usa para almacenar las concesiones. Si no se establece, se usa el valor de la configuración `databaseName`.
LeaseContainerName	(Opcional) Nombre del contenedor utilizado para almacenar concesiones. Si no se establece, se usa el valor `leases`.
CreateLeaseContainerIfNotExists	(Opcional) Cuando se establece en `true`, el contenedor de concesiones se crea automáticamente cuando todavía no existe. El valor predeterminado es `false`. Al usar identidades de Microsoft Entra si establece el valor en `true`, la creación de contenedores no es una operación permitida y la función no podrá iniciarse.
LeasesContainerThroughput	(Opcional) Define la cantidad de unidades de solicitud que se asignan cuando se crea el contenedor de concesiones. Esta configuración solo se usa cuando `CreateLeaseContainerIfNotExists` se establece en `true`. Este parámetro se establece automáticamente cuando el enlace se crea con el portal.
LeaseContainerPrefix	(Opcional) Cuando se establece, el valor se agrega como prefijo a las concesiones creadas en el contenedor de concesiones para esta función. El uso de un prefijo permite que dos funciones de Azure Functions independientes compartan el mismo contenedor de concesiones con prefijos diferentes.
FeedPollDelay	(Opcional) El tiempo (en milisegundos) del retraso entre sondeos de una partición en busca de nuevos cambios en la fuente, después de que todos los cambios actuales se purguen. El valor predeterminado es de 5 000 milisegundos (o 5 segundos).
LeaseAcquireInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para iniciar una tarea para calcular si las particiones se distribuyen uniformemente entre las instancias de host conocidas. El valor predeterminado es 13 000 (13 segundos).
LeaseExpirationInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para el que se toma la concesión en una concesión que representa una partición. Si la concesión no se renueva dentro de este intervalo, expirará y la propiedad de la partición se moverá a otra instancia. El valor predeterminado es 60 000 (60 segundos).
LeaseRenewInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo de renovación para todas las concesiones para las particiones que mantiene una instancia actualmente. El valor predeterminado es 17 000 (17 segundos).
MaxItemsPerInvocation	(Opcional) Al establecerse, esta propiedad establece la cantidad máxima de elementos recibidos por llamada de función. Si las operaciones del contenedor supervisado se realizan mediante procedimientos almacenados, el ámbito de transacción se conserva al leer los elementos de la fuente de cambios. Como resultado, es posible que el número de elementos recibidos sea mayor que el valor especificado, de modo que los elementos que cambian en la misma transacción se devuelvan como parte de un lote atómico.
StartFromBeginning	(Opcional) Esta opción indica al desencadenador que lea los cambios desde el principio del historial de cambios del contenedor en lugar de comenzar en la hora actual. La lectura desde el principio solo funciona la primera vez que se inicia el desencadenador, ya que en las ejecuciones posteriores, los puntos de control ya están almacenados. Si esta opción se establece en `true` cuando ya hay concesiones creadas no tiene ningún efecto.
StartFromTime	(Opcional) Obtiene o establece la fecha y hora a partir de la que se va a inicializar la operación de lectura de fuente de cambios. El formato recomendado es ISO 8601 con el designador UTC, como `2021-02-16T14:19:29Z`. Esto solo se usa para establecer el estado inicial del desencadenador. Una vez que el desencadenador tiene un estado de concesión, cambiar este valor no tiene ningún efecto.
PreferredLocations	(Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, "Este de EE. UU., Centro-sur de EE. UU. Norte de Europa".

Propiedad de atributo	Descripción
ConnectionStringSetting	Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
DatabaseName	Nombre de la base de datos de Azure Cosmos DB con la colección que se está supervisando.
CollectionName	Nombre de la colección que se está supervisando.
LeaseConnectionStringSetting	(Opcional) Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que contiene la colección de concesiones. Si no se establece, se usa el valor `ConnectionStringSetting`. Este parámetro se establece automáticamente cuando se crea el enlace en el portal. La cadena de conexión para la colección de concesiones debe tener permisos de escritura.
LeaseDatabaseName	(Opcional) Nombre de la base de datos que contiene la colección que se usa para almacenar las concesiones. Si no se establece, se usa el valor de la configuración `databaseName`.
LeaseCollectionName	(Opcional) Nombre de la colección que se usa para almacenar concesiones. Si no se establece, se usa el valor `leases`.
CreateLeaseCollectionIfNotExists	(Opcional) Cuando se establece en `true`, la colección de concesiones se crea automáticamente cuando todavía no existe. El valor predeterminado es `false`.
LeasesCollectionThroughput	(Opcional) Define la cantidad de unidades de solicitud que se asignan cuando se crea la colección de concesiones. Esta configuración solo se usa cuando `CreateLeaseCollectionIfNotExists` se establece en `true`. Este parámetro se establece automáticamente cuando el enlace se crea con el portal.
LeaseCollectionPrefix	(Opcional) Cuando se establece, el valor se agrega como prefijo a las concesiones creadas en la colección de concesiones para esta función. El uso de un prefijo permite que dos funciones de Azure Functions independientes compartan la misma colección de concesiones con prefijos diferentes.
FeedPollDelay	(Opcional) El tiempo (en milisegundos) del retraso entre sondeos de una partición en busca de nuevos cambios en la fuente, después de que todos los cambios actuales se purguen. El valor predeterminado es de 5 000 milisegundos (o 5 segundos).
LeaseAcquireInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para iniciar una tarea para calcular si las particiones se distribuyen uniformemente entre las instancias de host conocidas. El valor predeterminado es 13 000 (13 segundos).
LeaseExpirationInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para el que se toma la concesión en una concesión que representa una partición. Si la concesión no se renueva dentro de este intervalo, expirará y la propiedad de la partición se moverá a otra instancia. El valor predeterminado es 60 000 (60 segundos).
LeaseRenewInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo de renovación para todas las concesiones para las particiones que mantiene una instancia actualmente. El valor predeterminado es 17 000 (17 segundos).
CheckpointInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo entre los puntos de comprobación de las concesiones. El valor predeterminado siempre se encuentra después de una llamada de función.
CheckpointDocumentCount	(Opcional) Personaliza la cantidad de documentos entre puntos de control de concesión. De manera predeterminada, es después de cada llamada de función.
MaxItemsPerInvocation	(Opcional) Al establecerse, esta propiedad establece la cantidad máxima de elementos recibidos por llamada de función. Si las operaciones de la colección supervisada se realizan mediante procedimientos almacenados, el ámbito de transacción se conserva al leer los elementos de la fuente de cambios. Como resultado, es posible que el número de elementos recibidos sea mayor que el valor especificado, de modo que los elementos que cambian en la misma transacción se devuelvan como parte de un lote atómico.
StartFromBeginning	(Opcional) Esta opción indica al desencadenador que lea los cambios desde el principio del historial de cambios de la colección en lugar de comenzar en la hora actual. La lectura desde el principio solo funciona la primera vez que se inicia el desencadenador, ya que en las ejecuciones posteriores, los puntos de control ya están almacenados. Si esta opción se establece en `true` cuando ya hay concesiones creadas no tiene ningún efecto.
PreferredLocations	(Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, "Este de EE. UU., Centro-sur de EE. UU. Norte de Europa".
UseMultipleWriteLocations	(Opcional) Habilita las cuentas de varias regiones para escribir en la colección de concesiones.
UseDefaultJsonSerialization	(Opcional) Permite usar `JsonConvert.DefaultSettings` en la colección supervisada. Esta configuración solo se aplica a la colección supervisada y al consumidor para configurar la serialización usada en la colección supervisada. El `JsonConvert.DefaultSettings` debe establecerse en una clase derivada de `CosmosDBWebJobsStartup`.

Propiedad de atributo	Descripción
Connection	Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
DatabaseName	Nombre de la base de datos de Azure Cosmos DB con el contenedor que se está supervisando.
ContainerName	Nombre del contenedor que se está supervisando.
LeaseConnection	(Opcional) Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que contiene el contenedor de concesión. Si no se establece, se usa el valor `Connection`. Este parámetro se establece automáticamente cuando se crea el enlace en el portal. La cadena de conexión para el contenedor de concesiones debe tener permisos de escritura.
LeaseDatabaseName	(Opcional) Nombre de la base de datos que contiene el contenedor que se usa para almacenar las concesiones. Si no se establece, se usa el valor de la configuración `databaseName`.
LeaseContainerName	(Opcional) Nombre del contenedor utilizado para almacenar concesiones. Si no se establece, se usa el valor `leases`.
CreateLeaseContainerIfNotExists	(Opcional) Cuando se establece en `true`, el contenedor de concesiones se crea automáticamente cuando todavía no existe. El valor predeterminado es `false`. Al usar identidades de Microsoft Entra si establece el valor en `true`, la creación de contenedores no es una operación permitida y la función no podrá iniciarse.
LeasesContainerThroughput	(Opcional) Define la cantidad de unidades de solicitud que se asignan cuando se crea el contenedor de concesiones. Esta configuración solo se usa cuando `CreateLeaseContainerIfNotExists` se establece en `true`. Este parámetro se establece automáticamente cuando el enlace se crea con el portal.
LeaseContainerPrefix	(Opcional) Cuando se establece, el valor se agrega como prefijo a las concesiones creadas en el contenedor de concesiones para esta función. El uso de un prefijo permite que dos funciones de Azure Functions independientes compartan el mismo contenedor de concesiones con prefijos diferentes.
FeedPollDelay	(Opcional) El tiempo (en milisegundos) del retraso entre sondeos de una partición en busca de nuevos cambios en la fuente, después de que todos los cambios actuales se purguen. El valor predeterminado es de 5 000 milisegundos (o 5 segundos).
LeaseAcquireInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para iniciar una tarea para calcular si las particiones se distribuyen uniformemente entre las instancias de host conocidas. El valor predeterminado es 13 000 (13 segundos).
LeaseExpirationInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para el que se toma la concesión en una concesión que representa una partición. Si la concesión no se renueva dentro de este intervalo, expirará y la propiedad de la partición se moverá a otra instancia. El valor predeterminado es 60 000 (60 segundos).
LeaseRenewInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo de renovación para todas las concesiones para las particiones que mantiene una instancia actualmente. El valor predeterminado es 17 000 (17 segundos).
MaxItemsPerInvocation	(Opcional) Al establecerse, esta propiedad establece la cantidad máxima de elementos recibidos por llamada de función. Si las operaciones del contenedor supervisado se realizan mediante procedimientos almacenados, el ámbito de transacción se conserva al leer los elementos de la fuente de cambios. Como resultado, es posible que el número de elementos recibidos sea mayor que el valor especificado, de modo que los elementos que cambian en la misma transacción se devuelvan como parte de un lote atómico.
StartFromBeginning	(Opcional) Esta opción indica al desencadenador que lea los cambios desde el principio del historial de cambios del contenedor en lugar de comenzar en la hora actual. La lectura desde el principio solo funciona la primera vez que se inicia el desencadenador, ya que en las ejecuciones posteriores, los puntos de control ya están almacenados. Si esta opción se establece en `true` cuando ya hay concesiones creadas no tiene ningún efecto.
StartFromTime	(Opcional) Obtiene o establece la fecha y hora a partir de la que se va a inicializar la operación de lectura de fuente de cambios. El formato recomendado es ISO 8601 con el designador UTC, como `2021-02-16T14:19:29Z`. Esto solo se usa para establecer el estado inicial del desencadenador. Una vez que el desencadenador tiene un estado de concesión, cambiar este valor no tiene ningún efecto.
PreferredLocations	(Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, "Este de EE. UU., Centro-sur de EE. UU. Norte de Europa".

Propiedad de atributo	Descripción
ConnectionStringSetting	Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
DatabaseName	Nombre de la base de datos de Azure Cosmos DB con la colección que se está supervisando.
CollectionName	Nombre de la colección que se está supervisando.
LeaseConnectionStringSetting	(Opcional) Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que contiene la colección de concesiones. Si no se establece, se usa el valor `ConnectionStringSetting`. Este parámetro se establece automáticamente cuando se crea el enlace en el portal. La cadena de conexión para la colección de concesiones debe tener permisos de escritura.
LeaseDatabaseName	(Opcional) Nombre de la base de datos que contiene la colección que se usa para almacenar las concesiones. Si no se establece, se usa el valor de la configuración `databaseName`.
LeaseCollectionName	(Opcional) Nombre de la colección que se usa para almacenar concesiones. Si no se establece, se usa el valor `leases`.
CreateLeaseCollectionIfNotExists	(Opcional) Cuando se establece en `true`, la colección de concesiones se crea automáticamente cuando todavía no existe. El valor predeterminado es `false`.
LeasesCollectionThroughput	(Opcional) Define la cantidad de unidades de solicitud que se asignan cuando se crea la colección de concesiones. Esta configuración solo se usa cuando `CreateLeaseCollectionIfNotExists` se establece en `true`. Este parámetro se establece automáticamente cuando el enlace se crea con el portal.
LeaseCollectionPrefix	(Opcional) Cuando se establece, el valor se agrega como prefijo a las concesiones creadas en la colección de concesiones para esta función. El uso de un prefijo permite que dos funciones de Azure Functions independientes compartan la misma colección de concesiones con prefijos diferentes.
FeedPollDelay	(Opcional) El tiempo (en milisegundos) del retraso entre sondeos de una partición en busca de nuevos cambios en la fuente, después de que todos los cambios actuales se purguen. El valor predeterminado es de 5 000 milisegundos (o 5 segundos).
LeaseAcquireInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para iniciar una tarea para calcular si las particiones se distribuyen uniformemente entre las instancias de host conocidas. El valor predeterminado es 13 000 (13 segundos).
LeaseExpirationInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para el que se toma la concesión en una concesión que representa una partición. Si la concesión no se renueva dentro de este intervalo, expirará y la propiedad de la partición se moverá a otra instancia. El valor predeterminado es 60 000 (60 segundos).
LeaseRenewInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo de renovación para todas las concesiones para las particiones que mantiene una instancia actualmente. El valor predeterminado es 17 000 (17 segundos).
CheckpointInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo entre los puntos de comprobación de las concesiones. El valor predeterminado siempre se encuentra después de una llamada de función.
CheckpointDocumentCount	(Opcional) Personaliza la cantidad de documentos entre puntos de control de concesión. De manera predeterminada, es después de cada llamada de función.
MaxItemsPerInvocation	(Opcional) Al establecerse, esta propiedad establece la cantidad máxima de elementos recibidos por llamada de función. Si las operaciones de la colección supervisada se realizan mediante procedimientos almacenados, el ámbito de transacción se conserva al leer los elementos de la fuente de cambios. Como resultado, es posible que el número de elementos recibidos sea mayor que el valor especificado, de modo que los elementos que cambian en la misma transacción se devuelvan como parte de un lote atómico.
StartFromBeginning	(Opcional) Esta opción indica al desencadenador que lea los cambios desde el principio del historial de cambios de la colección en lugar de comenzar en la hora actual. La lectura desde el principio solo funciona la primera vez que se inicia el desencadenador, ya que en las ejecuciones posteriores, los puntos de control ya están almacenados. Si esta opción se establece en `true` cuando ya hay concesiones creadas no tiene ningún efecto.
PreferredLocations	(Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, "Este de EE. UU., Centro-sur de EE. UU. Norte de Europa".
UseMultipleWriteLocations	(Opcional) Habilita las cuentas de varias regiones para escribir en la colección de concesiones.
UseDefaultJsonSerialization	(Opcional) Permite usar `JsonConvert.DefaultSettings` en la colección supervisada. Esta configuración solo se aplica a la colección supervisada y al consumidor para configurar la serialización usada en la colección supervisada. El `JsonConvert.DefaultSettings` debe establecerse en una clase derivada de `CosmosDBWebJobsStartup`.

Elementos Decorator

Solo se aplica al modelo de programación de Python v2.

Para las funciones de Python v2 definidas mediante un decorador, se aplican las siguientes propiedades en cosmos_db_trigger:

Propiedad	Descripción
`arg_name`	Nombre de la variable que se utiliza en el código de función y que representa la lista de documentos con los cambios.
`database_name`	Nombre de la base de datos de Azure Cosmos DB con la colección que se está supervisando.
`collection_name`	Nombre de la colección de Azure Cosmos DB que se está supervisando.
`connection`	Cadena de conexión de Azure Cosmos DB que se está supervisando.

Para las funciones de Python definidas mediante function.json, consulte la sección Configuración.

Debido a los cambios de esquema en el SDK de Azure Cosmos DB, la versión 4.x de la extensión Azure Cosmos DB requiere azure-functions-java-library V3.0.0 para las funciones Java.

Use la @CosmosDBTrigger anotación en parámetros que leen datos de Azure Cosmos DB. La anotación admite las propiedades siguientes:

Propiedad de atributo	Descripción
connection	Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
name	El nombre de la función.
databaseName	Nombre de la base de datos de Azure Cosmos DB con el contenedor que se está supervisando.
containerName	Nombre del contenedor que se está supervisando.
leaseConnectionStringSetting	(Opcional) Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que contiene el contenedor de concesión. Si no se establece, se usa el valor `Connection`. Este parámetro se establece automáticamente cuando se crea el enlace en el portal. La cadena de conexión para el contenedor de concesiones debe tener permisos de escritura.
leaseDatabaseName	(Opcional) Nombre de la base de datos que contiene el contenedor que se usa para almacenar las concesiones. Si no se establece, se usa el valor de la configuración `databaseName`.
leaseContainerName	(Opcional) Nombre del contenedor utilizado para almacenar concesiones. Si no se establece, se usa el valor `leases`.
createLeaseContainerIfNotExists	(Opcional) Cuando se establece en `true`, el contenedor de concesiones se crea automáticamente cuando todavía no existe. El valor predeterminado es `false`. Al usar identidades de Microsoft Entra si establece el valor `true`en , la creación de contenedores no es una operación permitida y la función no se iniciará.
leasesContainerThroughput	(Opcional) Define la cantidad de unidades de solicitud que se asignan cuando se crea el contenedor de concesiones. Esta configuración solo se usa cuando `CreateLeaseContainerIfNotExists` se establece en `true`. Este parámetro se establece automáticamente cuando el enlace se crea con el portal.
leaseContainerPrefix	(Opcional) Cuando se establece, el valor se agrega como prefijo a las concesiones creadas en el contenedor de concesiones para esta función. El uso de un prefijo permite que dos funciones de Azure Functions independientes compartan el mismo contenedor de concesiones con prefijos diferentes.
feedPollDelay	(Opcional) El tiempo (en milisegundos) del retraso entre sondeos de una partición en busca de nuevos cambios en la fuente, después de que todos los cambios actuales se purguen. El valor predeterminado es de 5 000 milisegundos (o 5 segundos).
leaseAcquireInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para iniciar una tarea para calcular si las particiones se distribuyen uniformemente entre las instancias de host conocidas. El valor predeterminado es 13 000 (13 segundos).
leaseExpirationInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para el que se toma la concesión en una concesión que representa una partición. Si la concesión no se renueva dentro de este intervalo, expirará y la propiedad de la partición se moverá a otra instancia. El valor predeterminado es 60 000 (60 segundos).
leaseRenewInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo de renovación para todas las concesiones para las particiones que mantiene una instancia actualmente. El valor predeterminado es 17 000 (17 segundos).
maxItemsPerInvocation	(Opcional) Al establecerse, esta propiedad establece la cantidad máxima de elementos recibidos por llamada de función. Si las operaciones del contenedor supervisado se realizan mediante procedimientos almacenados, el ámbito de transacción se conserva al leer los elementos de la fuente de cambios. Como resultado, es posible que el número de elementos recibidos sea mayor que el valor especificado, de modo que los elementos que cambian en la misma transacción se devuelvan como parte de un lote atómico.
startFromBeginning	(Opcional) Esta opción indica al desencadenador que lea los cambios desde el principio del historial de cambios del contenedor en lugar de comenzar en la hora actual. La lectura desde el principio solo funciona la primera vez que se inicia el desencadenador, ya que en las ejecuciones posteriores, los puntos de control ya están almacenados. Si esta opción se establece en `true` cuando ya hay concesiones creadas no tiene ningún efecto.
preferredLocations	(Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, "Este de EE. UU., Centro-sur de EE. UU. Norte de Europa".

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @CosmosDBTrigger en los parámetros que leen datos de Azure Cosmos DB. La anotación admite las propiedades siguientes:

Configuración

Solo se aplica al modelo de programación de Python v1.

Model v4
Model v3

En la tabla siguiente se explican las propiedades que puede establecer en el objeto options que se pasa al métodoapp.cosmosDB(). Las propiedades type, direction y name no se aplican al modelo v4.

En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json, donde las propiedades difieren en la versión de la extensión:

Extensión 4.x y posteriores
Functions 2.x+

Propiedad de function.json	Descripción
type	Se debe establecer en `cosmosDBTrigger`.
direction	Se debe establecer en `in`. Este parámetro se establece automáticamente cuando se crea el desencadenador en Azure Portal.
name	Nombre de la variable que se utiliza en el código de función y que representa la lista de documentos con los cambios.
connection	Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
databaseName	Nombre de la base de datos de Azure Cosmos DB con el contenedor que se está supervisando.
containerName	Nombre del contenedor que se está supervisando.
leaseConnection	(Opcional) Nombre de una configuración de aplicación o contenedor de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que contiene la colección de concesiones. Si no se establece, se usa el valor `connection`. Este parámetro se establece automáticamente cuando se crea el enlace en el portal. La cadena de conexión para el contenedor de concesiones debe tener permisos de escritura.
leaseDatabaseName	(Opcional) Nombre de la base de datos que contiene el contenedor que se usa para almacenar las concesiones. Si no se establece, se usa el valor de la configuración `databaseName`.
leaseContainerName	(Opcional) Nombre del contenedor utilizado para almacenar concesiones. Si no se establece, se usa el valor `leases`.
createLeaseContainerIfNotExists	(Opcional) Cuando se establece en `true`, el contenedor de concesiones se crea automáticamente cuando todavía no existe. El valor predeterminado es `false`. Al usar identidades de Microsoft Entra si establece el valor en `true`, la creación de contenedores no es una operación permitida y la función no podrá iniciarse.
leasesContainerThroughput	(Opcional) Define la cantidad de unidades de solicitud que se asignan cuando se crea el contenedor de concesiones. Esta configuración solo se usa cuando `createLeaseContainerIfNotExists` se establece en `true`. Este parámetro se establece automáticamente cuando el enlace se crea con el portal.
leaseContainerPrefix	(Opcional) Cuando se establece, el valor se agrega como prefijo a las concesiones creadas en el contenedor de concesiones para esta función. El uso de un prefijo permite que dos funciones de Azure Functions independientes compartan el mismo contenedor de concesiones con prefijos diferentes.
feedPollDelay	(Opcional) El tiempo (en milisegundos) del retraso entre sondeos de una partición en busca de nuevos cambios en la fuente, después de que todos los cambios actuales se purguen. El valor predeterminado es de 5 000 milisegundos (o 5 segundos).
leaseAcquireInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para iniciar una tarea para calcular si las particiones se distribuyen uniformemente entre las instancias de host conocidas. El valor predeterminado es 13 000 (13 segundos).
leaseExpirationInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para el que se toma la concesión en una concesión que representa una partición. Si la concesión no se renueva dentro de este intervalo, expirará y la propiedad de la partición se moverá a otra instancia. El valor predeterminado es 60 000 (60 segundos).
leaseRenewInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo de renovación para todas las concesiones para las particiones que mantiene una instancia actualmente. El valor predeterminado es 17 000 (17 segundos).
maxItemsPerInvocation	(Opcional) Al establecerse, esta propiedad establece la cantidad máxima de elementos recibidos por llamada de función. Si las operaciones del contenedor supervisado se realizan mediante procedimientos almacenados, el ámbito de transacción se conserva al leer los elementos de la fuente de cambios. Como resultado, es posible que el número de elementos recibidos sea mayor que el valor especificado, de modo que los elementos que cambian en la misma transacción se devuelvan como parte de un lote atómico.
startFromBeginning	(Opcional) Esta opción indica al desencadenador que lea los cambios desde el principio del historial de cambios del contenedor en lugar de comenzar en la hora actual. La lectura desde el principio solo funciona la primera vez que se inicia el desencadenador, ya que en las ejecuciones posteriores, los puntos de control ya están almacenados. Si esta opción se establece en `true` cuando ya hay concesiones creadas no tiene ningún efecto.
startFromTime	(Opcional) Obtiene o establece la fecha y hora a partir de la que se va a inicializar la operación de lectura de fuente de cambios. El formato recomendado es ISO 8601 con el designador UTC, como `2021-02-16T14:19:29Z`. Esto solo se usa para establecer el estado inicial del desencadenador. Una vez que el desencadenador tiene un estado de concesión, cambiar este valor no tiene ningún efecto.
preferredLocations	(Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, "Este de EE. UU., Centro-sur de EE. UU. Norte de Europa".

Propiedad de function.json	Descripción
type	Se debe establecer en `cosmosDBTrigger`.
direction	Se debe establecer en `in`. Este parámetro se establece automáticamente cuando se crea el desencadenador en Azure Portal.
name	Nombre de la variable que se utiliza en el código de función y que representa la lista de documentos con los cambios.
connectionStringSetting	Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
databaseName	Nombre de la base de datos de Azure Cosmos DB con la colección que se está supervisando.
collectionName	Nombre de la colección que se está supervisando.
leaseConnectionStringSetting	(Opcional) Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que contiene la colección de concesiones. Si no se establece, se usa el valor `connectionStringSetting`. Este parámetro se establece automáticamente cuando se crea el enlace en el portal. La cadena de conexión para la colección de concesiones debe tener permisos de escritura.
leaseDatabaseName	(Opcional) Nombre de la base de datos que contiene la colección que se usa para almacenar las concesiones. Si no se establece, se usa el valor de la configuración `databaseName`.
leaseCollectionName	(Opcional) Nombre de la colección que se usa para almacenar concesiones. Si no se establece, se usa el valor `leases`.
createLeaseCollectionIfNotExists	(Opcional) Cuando se establece en `true`, la colección de concesiones se crea automáticamente cuando todavía no existe. El valor predeterminado es `false`.
leasesCollectionThroughput	(Opcional) Define la cantidad de unidades de solicitud que se asignan cuando se crea la colección de concesiones. Esta configuración solo se usa cuando `createLeaseCollectionIfNotExists` se establece en `true`. Este parámetro se establece automáticamente cuando el enlace se crea con el portal.
leaseCollectionPrefix	(Opcional) Cuando se establece, el valor se agrega como prefijo a las concesiones creadas en la colección de concesiones para esta función. El uso de un prefijo permite que dos funciones de Azure Functions independientes compartan la misma colección de concesiones con prefijos diferentes.
feedPollDelay	(Opcional) El tiempo (en milisegundos) del retraso entre sondeos de una partición en busca de nuevos cambios en la fuente, después de que todos los cambios actuales se purguen. El valor predeterminado es de 5 000 milisegundos (o 5 segundos).
leaseAcquireInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para iniciar una tarea para calcular si las particiones se distribuyen uniformemente entre las instancias de host conocidas. El valor predeterminado es 13 000 (13 segundos).
leaseExpirationInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo para el que se toma la concesión en una concesión que representa una partición. Si la concesión no se renueva dentro de este intervalo, expirará y la propiedad de la partición se moverá a otra instancia. El valor predeterminado es 60 000 (60 segundos).
leaseRenewInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo de renovación para todas las concesiones para las particiones que mantiene una instancia actualmente. El valor predeterminado es 17 000 (17 segundos).
checkpointInterval	(Opcional) Al establecerse, define, en milisegundos, el intervalo entre los puntos de comprobación de las concesiones. El valor predeterminado siempre se encuentra después de una llamada de función.
checkpointDocumentCount	(Opcional) Personaliza la cantidad de documentos entre puntos de control de concesión. De manera predeterminada, es después de cada llamada de función.
maxItemsPerInvocation	(Opcional) Al establecerse, esta propiedad establece la cantidad máxima de elementos recibidos por llamada de función. Si las operaciones de la colección supervisada se realizan mediante procedimientos almacenados, el ámbito de transacción se conserva al leer los elementos de la fuente de cambios. Como resultado, es posible que el número de elementos recibidos sea mayor que el valor especificado, de modo que los elementos que cambian en la misma transacción se devuelvan como parte de un lote atómico.
startFromBeginning	(Opcional) Esta opción indica al desencadenador que lea los cambios desde el principio del historial de cambios de la colección en lugar de comenzar en la hora actual. La lectura desde el principio solo funciona la primera vez que se inicia el desencadenador, ya que en las ejecuciones posteriores, los puntos de control ya están almacenados. Si esta opción se establece en `true` cuando ya hay concesiones creadas no tiene ningún efecto.
preferredLocations	(Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, "Este de EE. UU., Centro-sur de EE. UU. Norte de Europa".
useMultipleWriteLocations	(Opcional) Habilita las cuentas de varias regiones para escribir en la colección de concesiones.

Consulte la sección de ejemplos para ver ejemplos completos.

Uso

El desencadenador requiere una segunda colección que utiliza para almacenar concesiones en las particiones. La colección que se está supervisando y la colección que contiene las concesiones deben estar disponibles para que el desencadenador funcione.

Importante

Si hay varias funciones configuradas para usar un desencadenador de Azure Cosmos DB para la misma colección, cada una de ellas debe usar una colección de concesión dedicada, o bien se debe especificar un valor de LeaseCollectionPrefix para cada función. En caso contrario, se desencadena solo una de las funciones. Para obtener información acerca del prefijo, consulte la sección de atributos.

Importante

Si hay varias funciones configuradas para usar un desencadenador de Azure Cosmos DB para la misma colección, cada una de ellas debe usar una colección de concesión dedicada, o bien se debe especificar un valor de leaseCollectionPrefix para cada función. En caso contrario, se desencadena solo una de las funciones. Para obtener información acerca del prefijo, consulte la sección de anotaciones.

Importante

Si hay varias funciones configuradas para usar un desencadenador de Azure Cosmos DB para la misma colección, cada una de ellas debe usar una colección de concesión dedicada, o bien se debe especificar un valor de leaseCollectionPrefix para cada función. En caso contrario, se desencadenará solo una de las funciones. Para obtener información acerca del prefijo, consulte la sección de configuración.

El desencadenador no indica si un documento se actualizó o se insertó; solo proporciona el propio documento. Si tiene que administrar las actualizaciones e inserciones de manera diferente, puede hacerlo mediante la implementación de campos de marca de tiempo para las inserciones o actualizaciones.

El tipo de parámetro admitido por el desencadenador de Azure Cosmos DB depende de la versión del tiempo de ejecución de Functions, la versión del paquete de extensión y la modalidad de C# utilizada.

Cuando quiera que la función procese un único documento, el desencadenador de Cosmos DB puede enlazarse a los siguientes tipos:

Tipo	Descripción
Tipos serializables con JSON	Functions intenta deserializar los datos JSON del documento de la fuente de cambios de Cosmos DB en un tipo CLR antiguo y sin formato (POCO).

Cuando quiera que la función procese un lote de documentos, el desencadenador de Cosmos DB puede enlazarse a los siguientes tipos:

Tipo	Descripción
`IEnumerable<T>` donde `T` es un tipo serializable JSON	Una enumeración de entidades incluidas en el lote. Cada entrada representa un documento de la fuente de cambios de Cosmos DB.

Conexiones

Las propiedades connectionStringSetting/connection y leaseConnectionStringSetting/leaseConnection son referencias a la configuración del entorno que especifica cómo se debe conectar la aplicación a Azure Cosmos DB. Pueden especificar:

El nombre de una configuración de la aplicación que contiene una cadena de conexión
El nombre de un prefijo compartido para varias configuraciones de la aplicación que juntas definen una conexión basada en identidad. Esta opción solo está disponible para las versiones connection y leaseConnection de la versión 4.x o posterior de la extensión.

Si el valor configurado es tanto una coincidencia exacta de una única configuración como una coincidencia de prefijo de otras configuraciones, se usa la coincidencia exacta.

Cadena de conexión

La cadena de conexión de la cuenta de base de datos debe almacenarse en una configuración de la aplicación con un nombre que coincida con el valor especificado por la propiedad de conexión de la configuración de enlace.

Conexiones basadas en identidades

Si usa la versión 4.x o posterior de la extensión, en lugar de usar una cadena de conexión con un secreto, puede hacer que la aplicación use una identidad de Microsoft Entra. Para ello, defina la configuración con un prefijo común que se asigne a la propiedad de conexión en la configuración de desencadenador y enlace.

En este modo, la extensión requiere las siguientes propiedades:

Propiedad	Plantilla de variable de entorno	Descripción	Valor de ejemplo
Punto de conexión de la cuenta	`<CONNECTION_NAME_PREFIX>__accountEndpoint`	El identificador URI del punto de conexión de la cuenta de Azure Cosmos DB.	https://<database_account_name>.documents.azure.com:443/

Se pueden establecer propiedades adicionales para personalizar la conexión. Consulte Propiedades comunes para conexiones basadas en identidades.

Cuando se hospeda en el servicio de Azure Functions, las conexiones basadas en identidades usan una identidad administrada. La identidad asignada por el sistema se usa de manera predeterminada, aunque se puede especificar una identidad asignada por el usuario con las propiedades credential y clientID. Tenga en cuenta que no se admite la configuración de una identidad asignada por el usuario con un identificador de recurso. Cuando se ejecuta en otros contextos, como el de desarrollo local, se usa en su lugar la identidad del desarrollador, aunque se puede personalizar. Consulte Desarrollo local con conexiones basadas en identidades.

Concesión de permiso a la identidad

Cualquier identidad que se utilice debe tener permisos para realizar las acciones previstas. Para la mayoría de los servicios de Azure, esto significa que debe asignar un rol en Azure RBAC mediante roles integrados o personalizados que proporcionen esos permisos.

Importante

Es posible que el servicio de destino muestre algunos permisos que no son necesarios para todos los contextos. Siempre que sea posible, respete el principio de privilegios mínimos y conceda solo los privilegios necesarios a la identidad. Por ejemplo, si la aplicación solo necesita poder leer desde un origen de datos, use un rol que solo tenga permiso de lectura. Sería inadecuado asignar un rol que también permita escribir en ese servicio, ya que sería un permiso excesivo para una operación de lectura. De forma similar, le interesa asegurarse de que la asignación de roles esté limitada solo a los recursos que se deben leer.

Cosmos DB no usa Azure RBAC para las operaciones de datos. En su lugar, usa un sistema de RBAC integrado de Cosmos DB que se basa en conceptos similares. Deberá crear una asignación de roles que proporcione acceso a la cuenta de base de datos en tiempo de ejecución. Los roles de administración de Azure RBAC, como Propietario, no son suficientes. En la tabla siguiente se muestran los roles integrados que se recomiendan al usar la extensión de Azure Cosmos DB en funcionamiento normal. Puede que la aplicación precise permisos adicionales en función del código que escriba.

Tipo de enlace	Roles integrados de ejemplo¹
Desencadenador²	Colaborador de datos integrado de Cosmos DB
Enlace de entrada	Lector de datos integrado de Cosmos DB
Enlace de salida	Colaborador de datos integrado de Cosmos DB

¹ Estos roles no se pueden usar en una asignación de roles de RBAC de Azure. Consulte la documentación del sistema de RBAC integrado de Cosmos DB para más información sobre cómo asignar estos roles.

² Cuando se usa la identidad, Cosmos DB trata la creación de contenedores como una operación de administración. No está disponible como una operación de plano de datos para el desencadenador. Deberá asegurarse de crear los contenedores necesarios para el desencadenador (incluido el contenedor de concesión) antes de configurar la función.

Desencadenador de Azure Cosmos DB para Azure Functions 2.x y versiones posteriores

Ejemplo

Atributos

Elementos Decorator

anotaciones

Configuración

Uso

Conexiones

Cadena de conexión

Conexiones basadas en identidades

Concesión de permiso a la identidad

Pasos siguientes

Recursos adicionales