Información general sobre el desencadenador y los enlaces de Azure Cosmos DB para Azure Functions 2.x y versiones superiores

• Versión 1
• Versión 2 y superiores

En este conjunto de artículos se explica cómo trabajar con enlaces de Azure Cosmos DB en Azure Functions 2.x y versiones superiores. Azure Functions enlaces de desencadenador, de entrada y de salida para Azure Cosmos DB.

Acción	Tipo
Ejecución de una función cuando se crea o modifica un documento de Azure Cosmos DB	Desencadenador
Lectura de un documento de Azure Cosmos DB	Enlace de entrada
Guardar cambios en un documento de Azure Cosmos DB	Enlace de salida

Nota

Esta referencia va dirigida a Azure Functions, versión 2.x y superiores. Para obtener información acerca del uso de estos enlaces en Functions 1.x, consulte Enlaces de Azure Cosmos DB para Azure Functions 1.x.

Este enlace se llamaba originalmente DocumentDB. En Azure Functions, versión 2.x y posteriores, tanto el desencadenador, como los enlaces y el paquete se denominan Azure Cosmos DB.

API admitidas

Solo se admiten enlaces de Azure Cosmos DB para su uso con Azure Cosmos DB for NoSQL. La compatibilidad con Azure Cosmos DB for Table se proporciona mediante los enlaces de almacenamiento de Table, empezando por la extensión 5.x. Para el resto de API de Azure Cosmos DB, debe acceder a la base de datos desde la función mediante el cliente estático de la API, por ejemplo Azure Cosmos DB for MongoDB, Azure Cosmos DB for Cassandra y Azure Cosmos DB for Apache Gremlin.

Instalación de la extensión

El paquete NuGet de la extensión que instale depende del modo de C# que esté usando en la aplicación de funciones:

Modelo de trabajo aislado

Las funciones se ejecutan en un proceso de trabajo de C# aislado. Para más información, consulte Guía para ejecutar C# Azure Functions en un proceso de trabajo aislado.

Modelo de proceso

Importante

El soporte técnico del modelo en proceso finalizará el 10 de noviembre de 2026. Se recomienda encarecidamente migrar las aplicaciones al modelo de trabajo aislado para obtener soporte técnico completo.

Las funciones se ejecutan en el mismo proceso que el host de Functions. Para más información, consulte Desarrollo de funciones de la biblioteca de clases de C# con Azure Functions.

En una variación de este modelo, Functions se puede ejecutar mediante el scripting de C#, que se admite principalmente para la edición del portal de C#. Para actualizar las extensiones de enlace existentes de las aplicaciones del script de C# que se ejecutan en el portal sin tener que volver a publicar la aplicación de funciones, consulte Actualización de las extensiones.

El proceso para instalar la extensión varía en función de la versión de la extensión:

Extensión 4.x y posteriores

En esta sección se describe el uso de una biblioteca de clases. En el caso del scripting de C#, en su lugar, tendría que instalar la agrupación de extensiones, versión 4.x.

Esta versión de la extensión de enlaces de Azure Cosmos DB presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Esta versión también cambia los tipos con los que se puede enlazar; así, los tipos del SDK v2 Microsoft.Azure.DocumentDB se reemplazan por otros tipos más recientes del SDK v3 Microsoft.Azure.Cosmos. Obtenga más información sobre en qué se diferencian estos nuevos tipos y cómo migrarlos en la guía de migración de SDK y en los ejemplos de desencadenador, enlace de entrada y enlace de salida.

Esta versión de la extensión está disponible como un paquete NuGet, versión 4.x.

Functions 2.x+

En esta sección, se describe el uso de una biblioteca de clases. En el caso del scripting de C#, tendría que instalar en su lugar la agrupación de extensiones, versión 2.x o 3.x.

Para trabajar con el desencadenador y los enlaces, es necesario hacer referencia al paquete NuGet adecuado. Instale el paquete NuGet, versión 3.x.

Extensión 4.x y posteriores

Esta versión de la extensión de enlaces de Azure Cosmos DB presenta la posibilidad de conectarse con una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Para agregar la extensión al proyecto, instale el paquete NuGet, versión 4.x.

Si va a escribir la aplicación con F#, también debe configurar esta extensión como parte de la configuración de inicio de la aplicación. En la llamada a ConfigureFunctionsWorkerDefaults() o ConfigureFunctionsWebApplication(), agregue un delegado que tome un parámetro IFunctionsWorkerApplication. A continuación, dentro del cuerpo de ese delegado, llame a ConfigureCosmosDBExtension() en el objeto:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Functions 2.x+

Para agregar la extensión al proyecto, instale el paquete NuGet, versión 3.x.

Instalación del conjunto

La extensión de enlaces de Azure Cosmos DB forma parte de un conjunto de extensiones que se especifica en el archivo de proyecto host.json. Es posible que tenga que modificar este conjunto para cambiar la versión de los enlaces o en caso de que los conjuntos aún no estén instalados. Para obtener más información, consulte Conjuntos de extensiones.

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.

Versión 4.x del conjunto

Esta versión del conjunto contiene la versión 4.x de la extensión de enlaces de Azure Cosmos DB, que presenta la posibilidad de conectarse mediante una identidad en lugar de un secreto. Para obtener un tutorial sobre cómo configurar las aplicaciones de funciones con identidades administradas, consulte el tutorial Creación de una aplicación de funciones con conexiones basadas en identidades.

Agregue o reemplace el código siguiente en el archivo host.json para agregar esta versión de la extensión desde el conjunto de extensiones de versión preliminar v4:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.0.0, 5.0.0)"
  }
}

Para obtener más información, consulte Actualización de las extensiones.

Conjunto v2.x y v3.x

Puede instalar esta versión de la extensión en la aplicación de funciones; para ello, debe registrar el conjunto de extensiones, versión 2.x o 3.x.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Tipos de enlaces

Los tipos de enlace admitidos para .NET dependen de la versión de extensión y del modo de ejecución de C#, que puede ser uno de los siguientes:

Modelo de trabajo aislado

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.

Modelo de proceso

Un biblioteca de clases en proceso es una función de C# compilada que se ejecuta en el mismo proceso que Functions Runtime.

Seleccione una versión para ver los detalles del tipo de enlace para el modo y la versión.

Extensión 4.x y posteriores

La extensión Azure Cosmos DB admite tipos de parámetros según la tabla siguiente.

Escenario de enlace	Tipos de parámetro
Desencadenador de Cosmos DB (documento único)	Tipos serializables con JSON1
Desencadenador de Cosmos DB (lote de documentos)	IEnumerable<T>donde T es un tipo JSON serializable1
Entrada de Cosmos DB (documento único)	Tipos serializables con JSON1
Entrada de Cosmos DB (consulta que devuelve varios documentos)	CosmosClient IEnumerable<T> donde T es un tipo JSON serializable1
Salida de Cosmos DB (documento único)	Tipos serializables con JSON1
Salida de Cosmos DB (varios documentos)	ICollector<T> o IAsyncCollector<T> donde T es un tipo JSON serializable1

¹ Los documentos que contienen datos JSON se pueden deserializar en tipos conocidos de objetos CLR sin formato (POCO).

Functions 2.x+

Las versiones anteriores de la extensión exponen tipos del espacio de nombres Microsoft.Azure.Storage.Documents ahora en desuso. Los tipos más recientes de Microsoft.Azure.Cosmos son exclusivos de la extensión 4.x y versiones posteriores.

Extensión 4.x y posteriores

El proceso de trabajo aislado admite tipos de parámetros según las tablas siguientes. La compatibilidad para enlazar a tipos desde Microsoft.Azure.Cosmos está en versión preliminar.

Desencadenador de Cosmos DB

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.

Enlace de entrada de Azure Cosmos DB

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

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

Cuando quiera que la función procese varios documentos desde una consulta, el enlace de entrada de Cosmos DB puede enlazarse a los siguientes tipos:

Tipo	Descripción
IEnumerable<T> donde T es un tipo JSON serializable	Una enumeración de entidades devueltas por la consulta. Cada entrada representa un documento.
CosmosClient1	Un cliente conectado a la cuenta de Cosmos DB.
Database1	Un cliente conectado a la base de datos de Cosmos DB.
Container1	Un cliente conectado al contenedor de Cosmos DB.

¹ Para usar estos tipos, debe hacer referencia a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 o posterior y a las dependencias comunes para los enlaces de tipo de SDK.

Enlace de salida de Cosmos DB

Cuando quiera que la función escriba en un único documento, el enlace de salida de Cosmos DB puede enlazarse a los siguientes tipos:

Tipo	Descripción
Tipos serializables con JSON	Un objeto que representa el contenido JSON de un documento. Functions intenta serializar un tipo de objetivo CLR (POCO) convencional en datos JSON.

Cuando quiera que la función escriba en varios documentos, el enlace de salida de Cosmos DB puede enlazarse a los siguientes tipos:

Tipo	Descripción
T[] donde T es un tipo JSON serializable	Una matriz que contiene varios documentos. Cada entrada representa un documento.

Para otros escenarios de salida, cree y use cosmosClient con otros tipos de Microsoft.Azure.Cosmos directamente. Consulte Registro de clientes de Azure para obtener un ejemplo de uso de la inserción de dependencias para crear un tipo de cliente a partir del SDK de Azure.

Functions 2.x+

Las versiones anteriores de extensiones del proceso de trabajo aislado solo admiten el enlace a tipos serializables JSON. Hay opciones adicionales disponibles para la extensión 4.x y versiones posteriores.

Excepciones y códigos de retorno

Enlace	Referencia
Azure Cosmos DB	Códigos de Estado HTTP en Azure Cosmos DB

configuración de host.json

En esta sección se describen las opciones de configuración disponibles para este enlace en las versiones 2.x y posteriores. La configuración del archivo host.json se aplica a todas las funciones de una instancia de la aplicación de funciones. El siguiente archivo host.json de ejemplo contiene solo la configuración de la versión 2.x+ para este enlace. Para obtener más información sobre la configuración de la aplicación de funciones en las versiones 2.x y posteriores, consulte la referencia de host.json para Azure Functions.

Extensión 4.x y posteriores

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Propiedad	Valor predeterminado	Descripción
connectionMode	Gateway	Modo de conexión que usa la función al conectarse al servicio de Azure Cosmos DB. Las opciones son Direct y Gateway
userAgentSuffix	n/d	Agrega el valor de cadena especificado a todas las solicitudes enviadas por el desencadenador o el enlace al servicio. Esto facilita el seguimiento de la actividad en Azure Monitor, en función de una aplicación de funciones específica y filtrando por User Agent.

Functions 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Propiedad	Valor predeterminado	Descripción
connectionMode	Gateway	Modo de conexión que usa la función al conectarse al servicio de Azure Cosmos DB. Las opciones son Direct y Gateway
protocolo	Https	Protocolo de conexión que usa la función al conectarse al servicio de Azure Cosmos DB. Lea este documento para obtener una explicación de los dos modos.
leasePrefix	N/D	Prefijo de concesión que se usará en todas las funciones de una aplicación.

Pasos siguientes

• Ejecución de una función cuando se crea o modifica un documento de Azure Cosmos DB (desencadenador)
• Lectura de un documento de Azure Cosmos DB (enlace de entrada)
• Guardar los cambios en un documento de Azure Cosmos DB (enlace de salida)