Enlace de salida de Azure Cosmos DB para Azure Functions 2.x y versiones superiores

El enlace de salida de Azure Cosmos DB permite escribir un nuevo documento en una base de datos de Azure Cosmos DB mediante SQL API.

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

En esta sección se incluyen los ejemplos siguientes:

Los ejemplos hacen referencia a un tipo de ToDoItem simple:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Desencadenador de cola, escribir un documento

En el ejemplo siguiente se muestra una función de C# que agrega un documento a una base de datos mediante los datos que se proporcionan en el mensaje desde Queue Storage.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Desencadenador de cola, escribir un documento (extensión v4)

Las aplicaciones que usan la versión 4.x o posterior de la extensión de Cosmos DB tendrán propiedades de atributo diferentes, que se muestran a continuación. En el ejemplo siguiente se muestra una función de C# que agrega un documento a una base de datos mediante los datos que se proporcionan en el mensaje desde Queue Storage.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Desencadenador de cola, escribir documentos mediante IAsyncCollector

En el ejemplo siguiente se muestra una función de C# que agrega una colección de documentos a una base de datos mediante los datos que se proporcionan en un mensaje de cola JSON.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

Atributos y anotaciones

En las bibliotecas de clases de C#, use el atributo CosmosDB.

El constructor del atributo toma el nombre de la base de datos y el nombre de la colección. Para información sobre esos valores y otras propiedades que puede configurar, consulte Salida: configuración. A continuación, se muestra un ejemplo del atributo CosmosDB en una signatura de método:

    [FunctionName("QueueToDocDB")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [CosmosDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

En la versión 4.x de la extensión, algunos valores y propiedades se han quitado o se han cambiado de nombre. Para obtener más información sobre estos cambios, consulte Salida: configuración. A continuación, se muestra un ejemplo del atributo CosmosDB en una signatura de método:

    [FunctionName("QueueToCosmosDB")]
    public static void Run(
      [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
      [CosmosDB("database", "container", Connection = "CosmosDBConnectionSetting")] out dynamic document)
    {
        ...
    }

Configuración

En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json y el atributo .

Propiedad de function.json Propiedad de atributo Descripción
type N/D Se debe establecer en cosmosDB.
direction N/D Se debe establecer en out.
name N/D Nombre del parámetro de enlace que representa al documento en la función.
databaseName DatabaseName Base de datos que contiene la colección en la que se ha creado el documento.
collectionName
o
containerName
CollectionName
o
ContainerName
Nombre de la colección en la que se ha creado el documento.

En la versión 4.x de la extensión, esta propiedad se denomina .
createIfNotExists CreateIfNotExists Valor booleano que indica si la colección se ha creado si no existía. El valor predeterminado es false porque las colecciones nuevas se crean con rendimiento reservado, lo que afecta el costo. Consulte la página de preciospara obtener más información.
partitionKey PartitionKey Cuando el valor de CreateIfNotExists es true, define la ruta de la clave de partición para la colección creada.
collectionThroughput
o
containerThroughput
CollectionThroughput
o
ContainerThroughput
Cuando el valor de CreateIfNotExists es true, define el CreateIfNotExists de la colección creada.

En la versión 4.x de la extensión, esta propiedad se denomina .
connectionStringSetting
o
connection
ConnectionStringSetting
o
Connection
Nombre de una configuración de aplicación o de una colección de configuraciones de aplicación que especifica cómo conectarse a la cuenta de Azure Cosmos DB. Consulte Conexiones.

En la versión 4.x de la extensión, esta propiedad se denomina .
preferredLocations 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 UseMultipleWriteLocations (Opcional) Cuando se establece en true junto con PreferredLocations, puede aprovechar true en el servicio Azure Cosmos DB.

En la versión 4.x de la extensión, esta propiedad no está disponible.

Cuando desarrolla localmente, la configuración de aplicación pasa al archivo local.settings.json.

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 connection.

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 Azure Active Directory. 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. 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. Deberá 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.

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, como propietario no son suficientes. En la tabla siguiente se muestran los roles integrados que se recomiendan al usar la extensión de 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

Uso

De forma predeterminada, cuando se escribe en el parámetro de salida de la función, se crea un documento en la base de datos. Este documento tiene un GUID generado automáticamente como identificador de documento. Puede especificar el identificador de documento del documento de salida si especifica la propiedad id en el objeto JSON pasado al parámetro de salida.

Nota

Cuando especifica el identificador de un documento existente, se sobrescribe con el nuevo documento de salida.

Excepciones y códigos de retorno

Enlace Referencia
CosmosDB Códigos de error de CosmosDB

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",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}
Propiedad Valor predeterminado Descripción
GatewayMode Puerta de enlace 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.

Esta configuración no está disponible en la versión 4.x de la extensión.
leasePrefix N/D Prefijo de concesión que se usará en todas las funciones de una aplicación.

Esta configuración no está disponible en la versión 4.x de la extensión.

Pasos siguientes