Compartir vía


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

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:

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.

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

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

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

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

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

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 cómo ejecutar una función a medida que los datos cambian en Azure Cosmos DB.

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": 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'])

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

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.

anotaciones

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 trueen , 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".

Configuración

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

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:

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

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:

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 ejemplo1
Desencadenador2 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

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

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

Pasos siguientes