Compartir a través de

Introducción al desencadenador y enlaces de Azure Cosmos DB para Azure Functions

En este conjunto de artículos se explica cómo trabajar con enlaces de Azure Cosmos DB en Azure Functions. 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

Importante

Esta versión de la extensión de enlace de Azure Cosmos DB admite la versión 4.x de Azure Functions. Si la aplicación sigue usando la versión 1.x del entorno de ejecución de Functions, consulte enlaces de Azure Cosmos DB para Azure Functions 1.x. En el entorno de ejecución de Functions v1.x, este enlace se denominaba DocumentDBoriginalmente .

API admitidas

En esta tabla se indica cómo conectarse a las distintas API de Azure Cosmos DB desde el código de función:

API Recomendación
Azure Cosmos DB para NoSQL Uso de la extensión de enlace de Azure Cosmos DB
Azure Cosmos DB for MongoDB Use un SDK de cliente nativo.
Azure Cosmos DB para Table Use la versión 5.x o posterior de la extensión de enlace de Tablas de Azure.
Azure Cosmos DB para Apache Cassandra Use un SDK de cliente nativo.
Azure Cosmos DB para Apache Gremlin (Graph API) Uso de un SDK de cliente nativo
Azure Cosmos DB para PostgreSQL Use un SDK de cliente nativo.

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

Para poder usar esta extensión de enlace en la aplicación, asegúrese de que el archivo host.json en la raíz del proyecto contiene esta extensionBundle referencia:

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

En este ejemplo, el version valor de [4.0.0, 5.0.0) indica al host de Functions que use una versión de agrupación que sea al menos 4.0.0 pero menor 5.0.0que , que incluye todas las versiones potenciales de 4.x. Esta notación mantiene eficazmente la aplicación en la versión secundaria más reciente disponible del paquete de extensiones v4.x.

Cuando sea posible, debe usar la versión principal del paquete de extensiones más reciente y permitir que el tiempo de ejecución mantenga automáticamente la versión secundaria más reciente. Puede ver el contenido de la agrupación más reciente en la página de versión de paquetes de extensiones. Para más información, consulte Paquetes de extensiones de Azure Functions.

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.

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 serializable JSON Una enumeración de entidades devueltas por la consulta. Cada entrada representa un documento.
CosmosClient1 Un cliente conectado a la cuenta de Cosmos DB.
Base de datos1 Un cliente conectado a la base de datos de Cosmos DB.
Contenedor1 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 cosmosClientcon 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.

Tipos de enlace del SDK

La compatibilidad con el tipo de SDK para Azure Cosmos está en versión preliminar. Siga el ejemplo de enlaces del SDK de Python para CosmosDB para empezar a trabajar con los tipos de SDK para Cosmos en Python.

Importante

El uso de enlaces de tipos de SDK requiere el modelo de programación de Python v2.

Enlace Tipos de parámetro Muestras
Entrada de CosmosDB ContainerProxy,
CosmosClient,
DatabaseProxy
 ContainerProxy,
CosmosClient,
DatabaseProxy

Excepciones y códigos de retorno

Enlace Referencia
Azure Cosmos DB (la base de datos de Azure Cosmos) 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 la versión 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. Para más información sobre las opciones de configuración de la aplicación de funciones, consulte host.json referencia 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. Opciones: Direct se conecta directamente a las réplicas de back-end a través de TCP y puede proporcionar una menor latencia y Gateway enruta las solicitudes a través de una puerta de enlace de front-end a través de HTTPS. Para más información, consulte Modos de conexión del SDK de Azure Cosmos DB.
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

  • Last updated on