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

  • Artículo

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:

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.

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

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

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.

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.

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:

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.

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

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.

1 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 tipos de Microsoft.Azure.Cosmos directamente.

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.

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

Pasos siguientes