Gatilho do Azure Cosmos DB para o Azure Functions 2.x e superior

Artigo
02/02/2024

O gatilho do Azure Cosmos DB usa o feed de alterações do Azure Cosmos DB para escutar as inserções e as atualizações nas partições. O feed de alterações publica itens novos e atualizados, sem incluir as atualizações de exclusões.

Para obter informações sobre a instalação e detalhes de configuração, confira a visão geral.

As decisões de colocação em escala do Cosmos DB para os planos Consumo e Premium são feitas por meio da colocação em escala baseada no destino. Para obter mais informações, confira Colocação em escala baseada em destino.

Importante

Este artigo usa guias para dar suporte a várias versões do modelo de programação Node.js. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Para obter mais detalhes sobre como funciona o modelo v4, consulte o Guia do desenvolvedor do Node.js para o Azure Functions. Para saber mais sobre as diferenças entre os modelos v3 e a v4, consulte o Guia de migração.

O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a ambos os modelos de programação.

Exemplo

O uso do gatilho depende da versão do pacote de extensão e da modalidade C# usada no aplicativo de funções, que pode ser:

Modelo de trabalho isolado
Modelo em processo

Uma função C# compilada da biblioteca de classes do processo de trabalho isolado é executada em um processo isolado do runtime.

Os exemplos a seguir dependem da versão da extensão para o modo C# fornecido.

Os aplicativos que usam a extensão do Azure Cosmos DB versão 4.x ou superior têm propriedades de atributo diferentes, que são mostradas aqui. Este exemplo se refere a um tipo ToDoItem simples.

namespace CosmosDBSamplesV2
{
    // Customize the model with your own desired properties
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

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

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "databaseName",
            containerName: "containerName",
            Connection = "CosmosDBConnectionSetting",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> input, ILogger log)
        {
            if (input != null && input.Count > 0)
            {
                log.LogInformation("Documents modified " + input.Count);
                log.LogInformation("First document Id " + input[0].id);
            }
        }
    }
}

O exemplo a seguir mostra uma função C# que é chamada quando há inserções ou atualizações na coleção e no banco de dados especificados.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            ILogger log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.LogInformation($"Documents modified: {documents.Count}");
                log.LogInformation($"First document Id: {documents[0].Id}");
            }
        }
    }
}

Este exemplo se refere a um tipo ToDoItem simples:

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

A função a seguir é chamada quando há inserções ou atualizações na coleção e no banco de dados especificados.

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

O seguinte código define um tipo MyDocument:

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

Um IReadOnlyList<T> é usado como o parâmetro de associação de gatilho de evento do Azure Cosmos DB no seguinte exemplo:

[Function(nameof(CosmosDBFunction))]
[ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
[CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
public object Run(
    [CosmosDBTrigger(
        "%CosmosDb%",
        "%CosmosContainerIn%",
        Connection = "CosmosDBConnection",
        LeaseContainerName = "leases",
        CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
    FunctionContext context)
{
    if (input != null && input.Any())
    {
        foreach (var doc in input)
        {
            _logger.LogInformation("Doc Id: {id}", doc.Id);
        }

        // Cosmos Output
        return input.Select(p => new { id = p.Id });
    }

    return null;
}

Este exemplo requer as seguintes instruções using:

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

Essa função é invocada quando há inserções ou atualizações no banco de dados e no contêiner especificados.

Extensão 4.x e posterior
Functions 2.x+

Devido às alterações de esquema no SDK do Azure Cosmos DB, a versão 4.x da extensão do Azure Cosmos DB requer o azure-functions-java-library V3.0.0 para as funções 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());
    }

    @FunctionName("cosmosDBMonitor")
    public void cosmosDbProcessor(
        @CosmosDBTrigger(name = "items",
            databaseName = "ToDoList",
            collectionName = "Items",
            leaseCollectionName = "leases",
            createLeaseCollectionIfNotExists = true,
            connectionStringSetting = "AzureCosmosDBConnection") String[] items,
            final ExecutionContext context ) {
                context.getLogger().info(items.length + "item(s) is/are changed.");
            }

Na biblioteca de runtime de funções Java, use a anotação @CosmosDBTrigger nos parâmetros cujo valor seria proveniente do Azure Cosmos DB. Essa anotação pode ser usada com tipos nativos do Java, POJOs ou valores que permitem valor nulos usando Optional<T>.

Modelo v4
Modelo v3

O exemplo a seguir mostra uma associação de gatilho da função TypeScript do Azure Cosmos DB. A função grava mensagens de log quando registros do Azure Cosmos DB são adicionados ou modificados.

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

Modelo v4
Modelo v3

O exemplo a seguir mostra uma associação de gatilho da função JavaScript do Azure Cosmos DB. A função grava mensagens de log quando registros do Azure Cosmos DB são adicionados ou modificados.

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

O exemplo a seguir mostra uma associação de gatilho do Azure Cosmos DB em um arquivo function.json e uma função do JavaScript que usa a associação. A função grava mensagens de log quando registros do Azure Cosmos DB são adicionados ou modificados.

Aqui estão os dados de associação no arquivo function.json:

Functions 2.x+
Funções 4.x+

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

Observe que alguns dos nomes de atributo de associação foram alterados na versão 4.x da extensão do Azure Cosmos DB.

Aqui está o código JavaScript:

    module.exports = async function (context, documents) {
      context.log('First document Id modified : ', documents[0].id);
    }

O exemplo a seguir mostra como executar uma função como alterações de dados no Azure Cosmos DB.

Functions 2.x+
Funções 4.x+

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

Observe que alguns dos nomes de atributo de associação foram alterados na versão 4.x da extensão do Azure Cosmos DB.

No arquivo run.ps1, você tem acesso ao documento que dispara a função por meio do parâmetro $Documents.

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)"

O exemplo a seguir mostra uma associação de gatilho do Azure Cosmos DB. O exemplo varia dependendo de você utilizar o modelo de programação v1 ou v2 do Python.

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'])

A função grava mensagens de log quando registros do Azure Cosmos DB são modificados. Aqui estão os dados de associação no arquivo function.json:

Functions 2.x+
Funções 4.x+

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

Observe que alguns dos nomes de atributo de associação foram alterados na versão 4.x da extensão do Azure Cosmos DB.

Aqui está o código Python:

    import logging
    import azure.functions as func


    def main(documents: func.DocumentList) -> str:
        if documents:
            logging.info('First document Id modified: %s', documents[0]['id'])

Atributos

As bibliotecas C# em processo e de processo isolado usam o atributo CosmosDBTriggerAttribute para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Propriedade de atributo	Descrição
Conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
ContainerName	O nome do contêiner que está sendo monitorado.
LeaseConnection	(Opcional) O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que contém o contêiner de concessão. Quando não definido, o valor `Connection` é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão do contêiner de concessões deve ter permissões de gravação.
LeaseDatabaseName	(Opcional) O nome do banco de dados que contém o contêiner usado para armazenar as concessões. Quando não definido, o valor da configuração `databaseName` é usado.
LeaseContainerName	(Opcional) O nome do contêiner usado para armazenar concessões. Quando não definido, o valor `leases` é usado.
CreateLeaseContainerIfNotExists	(Opcional) Quando definido como `true`, a coleção de contêineres é criada automaticamente quando ela ainda não existe. O valor padrão é `false`. Ao usar identidades do Microsoft Entra, se você definir o valor como `true`, a criação de contêineres não será uma operação permitida e sua função não poderá ser iniciada.
LeasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação que será atribuído quando o contêiner de concessões for criado. Essa configuração é usada apenas quando `CreateLeaseContainerIfNotExists` está definido como `true`. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas no contêiner de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem o mesmo contêiner de concessões usando prefixos diferentes.
FeedPollDelay	(Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
LeaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
LeaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
MaxItemsPerInvocation	(Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações no contêiner monitorado forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning	(Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações do contêiner, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como `true` quando já houver concessões já criadas não terá nenhum efeito.
StartFromTime	(Opcional) Obtém ou define a data e a hora a partir da qual inicializar a operação de leitura do feed de alterações. O formato recomendado é o ISO 8601 com o designador UTC, como `2021-02-16T14:19:29Z`. Isso é usado apenas para definir o estado inicial do gatilho. Depois que o gatilho tiver um estado de concessão, a alteração desse valor não terá nenhum efeito.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Propriedade de atributo	Descrição
ConnectionStringSetting	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
CollectionName	O nome da coleção que está sendo monitorada.
LeaseConnectionStringSetting	(Opcional) O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que mantém a coleção de concessão. Quando não definido, o valor `ConnectionStringSetting` é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão da coleção de concessões deve ter permissões de gravação.
LeaseDatabaseName	(Opcional) O nome do banco de dados que contém a coleção usada para armazenar as concessões. Quando não definido, o valor da configuração `databaseName` é usado.
LeaseCollectionName	(Opcional) O nome da coleção usada para armazenar as concessões. Quando não definido, o valor `leases` é usado.
CreateLeaseCollectionIfNotExists	(Opcional) Quando definido como `true`, a coleção de concessões é criada automaticamente quando ela ainda não existe. O valor padrão é `false`.
leasesCollectionThroughput	(Opcional) Define o número de Unidades de Solicitação que será atribuído quando a coleção de concessões for criada. Essa configuração é usada apenas quando `CreateLeaseCollectionIfNotExists` está definido como `true`. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseCollectionPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas na coleção de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem a mesma coleção de concessões usando prefixos diferentes.
FeedPollDelay	(Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
LeaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
LeaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
CheckpointInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo entre os pontos de verificação de concessão. O padrão é sempre após cada chamada de Função.
CheckpointDocumentCount	(Opcional) Personaliza a quantidade de documentos entre pontos de verificação de concessão. O padrão é após cada chamada de função.
MaxItemsPerInvocation	(Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações na coleção monitorada forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning	(Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações da coleção, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como `true` quando já houver concessões já criadas não terá nenhum efeito.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".
UseMultipleWriteLocations	(Opcional) Habilita contas de várias regiões para gravação na coleção de concessões.
UseDefaultJsonSerialization	(Opcional) Permite que você use `JsonConvert.DefaultSettings` na coleção monitorada. Essa configuração se aplica somente à coleção monitorada e ao consumidor para configurar a serialização usada na coleção monitorada. O `JsonConvert.DefaultSettings` deve ser definido em uma classe derivada de `CosmosDBWebJobsStartup`.

Propriedade de atributo	Descrição
Conexão	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
ContainerName	O nome do contêiner que está sendo monitorado.
LeaseConnection	(Opcional) O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que contém o contêiner de concessão. Quando não definido, o valor `Connection` é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão do contêiner de concessões deve ter permissões de gravação.
LeaseDatabaseName	(Opcional) O nome do banco de dados que contém o contêiner usado para armazenar as concessões. Quando não definido, o valor da configuração `databaseName` é usado.
LeaseContainerName	(Opcional) O nome do contêiner usado para armazenar concessões. Quando não definido, o valor `leases` é usado.
CreateLeaseContainerIfNotExists	(Opcional) Quando definido como `true`, a coleção de contêineres é criada automaticamente quando ela ainda não existe. O valor padrão é `false`. Ao usar identidades do Microsoft Entra, se você definir o valor como `true`, a criação de contêineres não será uma operação permitida e sua função não poderá ser iniciada.
LeasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação que será atribuído quando o contêiner de concessões for criado. Essa configuração é usada apenas quando `CreateLeaseContainerIfNotExists` está definido como `true`. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas no contêiner de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem o mesmo contêiner de concessões usando prefixos diferentes.
FeedPollDelay	(Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
LeaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
LeaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
MaxItemsPerInvocation	(Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações no contêiner monitorado forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning	(Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações do contêiner, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como `true` quando já houver concessões já criadas não terá nenhum efeito.
StartFromTime	(Opcional) Obtém ou define a data e a hora a partir da qual inicializar a operação de leitura do feed de alterações. O formato recomendado é o ISO 8601 com o designador UTC, como `2021-02-16T14:19:29Z`. Isso é usado apenas para definir o estado inicial do gatilho. Depois que o gatilho tiver um estado de concessão, a alteração desse valor não terá nenhum efeito.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Propriedade de atributo	Descrição
ConnectionStringSetting	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
CollectionName	O nome da coleção que está sendo monitorada.
LeaseConnectionStringSetting	(Opcional) O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que mantém a coleção de concessão. Quando não definido, o valor `ConnectionStringSetting` é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão da coleção de concessões deve ter permissões de gravação.
LeaseDatabaseName	(Opcional) O nome do banco de dados que contém a coleção usada para armazenar as concessões. Quando não definido, o valor da configuração `databaseName` é usado.
LeaseCollectionName	(Opcional) O nome da coleção usada para armazenar as concessões. Quando não definido, o valor `leases` é usado.
CreateLeaseCollectionIfNotExists	(Opcional) Quando definido como `true`, a coleção de concessões é criada automaticamente quando ela ainda não existe. O valor padrão é `false`.
leasesCollectionThroughput	(Opcional) Define o número de Unidades de Solicitação que será atribuído quando a coleção de concessões for criada. Essa configuração é usada apenas quando `CreateLeaseCollectionIfNotExists` está definido como `true`. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseCollectionPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas na coleção de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem a mesma coleção de concessões usando prefixos diferentes.
FeedPollDelay	(Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
LeaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
LeaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
CheckpointInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo entre os pontos de verificação de concessão. O padrão é sempre após cada chamada de Função.
CheckpointDocumentCount	(Opcional) Personaliza a quantidade de documentos entre pontos de verificação de concessão. O padrão é após cada chamada de função.
MaxItemsPerInvocation	(Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações na coleção monitorada forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning	(Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações da coleção, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como `true` quando já houver concessões já criadas não terá nenhum efeito.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".
UseMultipleWriteLocations	(Opcional) Habilita contas de várias regiões para gravação na coleção de concessões.
UseDefaultJsonSerialization	(Opcional) Permite que você use `JsonConvert.DefaultSettings` na coleção monitorada. Essa configuração se aplica somente à coleção monitorada e ao consumidor para configurar a serialização usada na coleção monitorada. O `JsonConvert.DefaultSettings` deve ser definido em uma classe derivada de `CosmosDBWebJobsStartup`.

Decoradores

Aplica-se somente ao modelo de programação v2 do Python.

Para funções do Python v2 definidas usando um decorador, as seguintes propriedades no cosmos_db_trigger:

Propriedade	DESCRIÇÃO
`arg_name`	O nome da variável usado no código de função que representa a lista de documentos com alterações.
`database_name`	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
`collection_name`	O nome da coleção do Azure Cosmos DB sendo monitorada.
`connection`	A cadeia de conexão do Azure Cosmos DB sendo monitorada.

Para funções do Python definidas usando function.json, confira a seção Configuração.

Devido às alterações de esquema no SDK do Azure Cosmos DB, a versão 4.x da extensão do Azure Cosmos DB requer o azure-functions-java-library V3.0.0 para as funções Java.

Use a @CosmosDBTrigger anotação em parâmetros que leem dados do Azure Cosmos DB. Essa anotação dá suporte às seguintes propriedades:

Propriedade de atributo	Descrição
connection	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
name	O nome da função.
databaseName	O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
containerName	O nome do contêiner que está sendo monitorado.
leaseConnectionStringSetting	(Opcional) O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que contém o contêiner de concessão. Quando não definido, o valor `Connection` é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão do contêiner de concessões deve ter permissões de gravação.
leaseDatabaseName	(Opcional) O nome do banco de dados que contém o contêiner usado para armazenar as concessões. Quando não definido, o valor da configuração `databaseName` é usado.
leaseContainerName	(Opcional) O nome do contêiner usado para armazenar concessões. Quando não definido, o valor `leases` é usado.
createLeaseContainerIfNotExists	(Opcional) Quando definido como `true`, a coleção de contêineres é criada automaticamente quando ela ainda não existe. O valor padrão é `false`. Ao usar identidades do Microsoft Entra, se você definir o valor como `true`, a criação de contêineres não é uma operação permitida e sua função não será iniciada.
leasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação que será atribuído quando o contêiner de concessões for criado. Essa configuração é usada apenas quando `CreateLeaseContainerIfNotExists` está definido como `true`. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas no contêiner de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem o mesmo contêiner de concessões usando prefixos diferentes.
feedPollDelay	(Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
leaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
leaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro desse intervalo, ela expirará e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
leaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
maxItemsPerInvocation	(Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações no contêiner monitorado forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning	(Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações do contêiner, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como `true` quando já houver concessões já criadas não terá nenhum efeito.
preferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Na biblioteca de runtime de funções Java, use a anotação @CosmosDBTrigger nos parâmetros que leem dados do Azure Cosmos DB. Essa anotação dá suporte às seguintes propriedades:

Configuração

Aplica-se apenas ao modelo de programação v1 do Python.

Modelo v4
Modelo v3

A tabela a seguir explica as propriedades que você pode definir no objeto options passado para o método app.cosmosDB(). As propriedades type, direction e name não se aplicam ao modelo v4.

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json. Essas propriedades se diferenciam pela versão da extensão:

Extensão 4.x e posterior
Functions 2.x+

Propriedade function.json	Descrição
tipo	Deve ser definido como `cosmosDBTrigger`.
direction	Deve ser definido como `in`. Esse parâmetro é definido automaticamente quando você cria o gatilho no portal do Azure.
name	O nome da variável usado no código de função que representa a lista de documentos com alterações.
connection	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
databaseName	O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
containerName	O nome do contêiner que está sendo monitorado.
leaseConnection	(Opcional) O nome de uma configuração de aplicativo ou contêiner de configurações que especifica como se conectar à conta do Azure Cosmos DB que mantém o contêiner de concessão. Quando não definido, o valor `connection` é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão do contêiner de concessões deve ter permissões de gravação.
leaseDatabaseName	(Opcional) O nome do banco de dados que contém o contêiner usado para armazenar as concessões. Quando não definido, o valor da configuração `databaseName` é usado.
leaseContainerName	(Opcional) O nome do contêiner usado para armazenar concessões. Quando não definido, o valor `leases` é usado.
createLeaseContainerIfNotExists	(Opcional) Quando definido como `true`, a coleção de contêineres é criada automaticamente quando ela ainda não existe. O valor padrão é `false`. Ao usar identidades do Microsoft Entra, se você definir o valor como `true`, a criação de contêineres não será uma operação permitida e sua função não poderá ser iniciada.
leasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação que será atribuído quando o contêiner de concessões for criado. Essa configuração é usada apenas quando `createLeaseContainerIfNotExists` está definido como `true`. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas no contêiner de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem o mesmo contêiner de concessões usando prefixos diferentes.
feedPollDelay	(Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
leaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
leaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
leaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
maxItemsPerInvocation	(Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações no contêiner monitorado forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning	(Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações do contêiner, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como `true` quando já houver concessões já criadas não terá nenhum efeito.
startFromTime	(Opcional) Obtém ou define a data e a hora a partir da qual inicializar a operação de leitura do feed de alterações. O formato recomendado é o ISO 8601 com o designador UTC, como `2021-02-16T14:19:29Z`. Isso é usado apenas para definir o estado inicial do gatilho. Depois que o gatilho tiver um estado de concessão, a alteração desse valor não terá nenhum efeito.
preferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Propriedade function.json	Descrição
tipo	Deve ser definido como `cosmosDBTrigger`.
direction	Deve ser definido como `in`. Esse parâmetro é definido automaticamente quando você cria o gatilho no portal do Azure.
name	O nome da variável usado no código de função que representa a lista de documentos com alterações.
connectionStringSetting	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorado. Para mais informações, consulte as Conexões.
databaseName	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
collectionName	O nome da coleção que está sendo monitorada.
leaseConnectionStringSetting	(Opcional) O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que mantém a coleção de concessão. Quando não definido, o valor `connectionStringSetting` é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão da coleção de concessões deve ter permissões de gravação.
leaseDatabaseName	(Opcional) O nome do banco de dados que contém a coleção usada para armazenar as concessões. Quando não definido, o valor da configuração `databaseName` é usado.
leaseCollectionName	(Opcional) O nome da coleção usada para armazenar as concessões. Quando não definido, o valor `leases` é usado.
createLeaseCollectionIfNotExists	(Opcional) Quando definido como `true`, a coleção de concessões é criada automaticamente quando ela ainda não existe. O valor padrão é `false`.
leasesCollectionThroughput	(Opcional) Define o número de Unidades de Solicitação que será atribuído quando a coleção de concessões for criada. Essa configuração é usada apenas quando `createLeaseCollectionIfNotExists` está definido como `true`. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseCollectionPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo nas concessões criadas na coleção de concessões desta função. O uso de um prefixo permite que dois Azure Functions separados compartilhem a mesma coleção de concessões usando prefixos diferentes.
feedPollDelay	(Opcional) O horário (em milissegundos) do atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem esvaziadas. O padrão é cinco mil milissegundos (ou cinco segundos).
leaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
leaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
leaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
checkpointInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo entre os pontos de verificação de concessão. O padrão é sempre após cada chamada de Função.
checkpointDocumentCount	(Opcional) Personaliza a quantidade de documentos entre pontos de verificação de concessão. O padrão é após cada chamada de função.
maxItemsPerInvocation	(Opcional) Quando definida, essa propriedade define o número máximo de itens recebidos por chamada de função. Se as operações na coleção monitorada forem executadas por meio de procedimentos armazenados, o escopo da transação será preservado durante a leitura de itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior que o valor especificado para que os itens alterados pela mesma transação sejam retornados como parte de um lote atômico.
startFromBeginning	(Opcional) Essa opção informa que o gatilho deve ler as alterações desde o início do histórico de alterações da coleção, em vez de iniciar na hora atual. Ler do começo funciona apenas na primeira vez em que gatilho inicia, pois nas execuções subsequentes os pontos de verificação já estão armazenados. Configurar essa opção como `true` quando já houver concessões já criadas não terá nenhum efeito.
preferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".
useMultipleWriteLocations	(Opcional) Habilita contas de várias regiões para gravação na coleção de concessões.

Consulte a Seção de exemplo para obter exemplos completos.

Uso

O gatilho requer uma segunda coleção que ele usa para armazenar concessões sobre as partições. Tanto a coleção que está sendo monitorada quanto a coleção que contém as concessões devem estar disponíveis para o gatilho funcionar.

Importante

Se várias funções estiverem configuradas para usar um gatilho do Azure Cosmos DB para a mesma coleção, cada uma das funções deverá usar uma coleção de concessões dedicada ou especificar uma LeaseCollectionPrefix diferente para cada função. Caso contrário, apenas uma das funções é acionada. Para obter informações sobre o prefixo, consulte a seção Atributos.

Importante

Se várias funções estiverem configuradas para usar um gatilho do Azure Cosmos DB para a mesma coleção, cada uma das funções deverá usar uma coleção de concessões dedicada ou especificar uma leaseCollectionPrefix diferente para cada função. Caso contrário, apenas uma das funções é acionada. Para obter informações sobre o prefixo, consulte a seção Anotações.

Importante

Se várias funções estiverem configuradas para usar um gatilho do Azure Cosmos DB para a mesma coleção, cada uma das funções deverá usar uma coleção de concessões dedicada ou especificar uma leaseCollectionPrefix diferente para cada função. Caso contrário, apenas uma das funções será disparada. Para obter informações sobre o prefixo, veja a seção de Configuração.

O gatilho não indica se um documento foi atualizado ou inserido, ele fornece apenas o documento em si. Se você precisa lidar com inserções e atualizações de forma diferente, você pode fazer isso com a implementação de campos de carimbo de hora de inserção ou atualização.

O tipo de parâmetro com suporte no gatilho do Azure Cosmos DB depende da versão de runtime do Functions, da versão do pacote de extensão e da modalidade de C# usada.

Quando você deseja que a função processe um único documento, o gatilho do Cosmos DB pode ser associado aos seguintes tipos:

Type	Descrição
Tipos serializáveis JSON	O Functions tenta desserializar os dados JSON do documento do feed de alterações do Cosmos DB em um tipo de objeto CLR (POCO) simples.

Quando você desejar que a função processe um lote de documentos, o gatilho do Cosmos DB pode ser associado aos seguintes tipos:

Type	Descrição
`IEnumerable<T>` em `T` é um tipo serializável por JSON	Uma enumeração de entidades incluídas no lote. Cada entrada representa um documento do feed de alterações do Cosmos DB.

conexões

As propriedades connectionStringSetting/connection e leaseConnectionStringSetting/leaseConnection são referências à configuração de ambiente que especifica como o aplicativo deve se conectar ao Azure Cosmos DB. Elas podem especificar:

O nome da configuração de um aplicativo contendo uma cadeia de conexão
O nome de um prefixo compartilhado com várias configurações de aplicativo, definindo juntas uma conexão baseada em identidade. Essa opção só está disponível para as versões connection e leaseConnection da connection.

Se o valor configurado for uma combinação exata para uma única configuração e um correspondência de prefixo para outras configurações, a correspondência exata será usada.

Cadeia de conexão

A cadeia de conexão para sua conta do banco de dados deve ser armazenada em uma configuração de aplicativo com um nome que corresponde ao valor especificado pela propriedade da conexão da configuração de associação.

Conexões baseadas em identidade

Se você estiver usando a versão 4.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para fazer isso, defina as configurações em um prefixo comum que mapeia para a propriedade da conexão na configuração de gatilho e de associação.

Nesse modo, a extensão exige as seguintes propriedades:

Propriedade	Modelo de variável de ambiente	Descrição	Valor de exemplo
Ponto de extremidade da conta	`<CONNECTION_NAME_PREFIX>__accountEndpoint`	URI do ponto de extremidade da conta do Azure Cosmos DB.	https://<nome_da_conta_do_banco_de_dados>.documents.azure.com:443/

É possível definir propriedades adicionais para personalizar a conexão. Confira Propriedades comuns para conexões baseadas em identidade.

Quando hospedadas no serviço de Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída pelo sistema é usada por padrão, embora a identidade atribuída pelo usuário possa ser especificada com as propriedades credential e clientID. Observe que não há suporte para configurar uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, a identidade do desenvolvedor é usada, embora isso possa ser personalizado. Confira Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão para a identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços do Azure, isso significa que será necessário atribuir uma função no Azure RBAC, usando as funções internas ou as personalizadas que fornecem essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o escopo apenas sobre os recursos que precisam ser lidos.

O Cosmos DB não usa o RBAC do Azure para operações de dados. Em vez disso, ele usa um sistema RBAC interno do Cosmos DB que se baseia em conceitos semelhantes. Será necessário criar uma atribuição de função que forneça acesso a sua conta de banco de dados em runtime. As funções de Gerenciamento de RBAC do Azure, como a de Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Azure Cosmos DB em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código escrito por você.

Tipo de associação	Exemplo de funções internas¹
Gatilho²	Colaborador de dados internos do Cosmos DB
Associação de entrada	Leitor de dados internos do Cosmos DB
Associação de saída	Colaborador de dados internos do Cosmos DB

¹ Essas funções não podem ser usadas em uma atribuição de função RBAC do Azure. Confira a documentação do sistema RBAC interno do Cosmos DB para obter detalhes sobre como atribuir essas funções.

² Ao usar a identidade, o Cosmos DB trata a criação de contêiner como uma operação de gerenciamento. Ele não está disponível como uma operação de plano de dados para o gatilho. Você precisará garantir a criação dos contêineres necessários para o gatilho (incluindo o contêiner de concessão) antes de configurar a função.

Compartilhar via

Gatilho do Azure Cosmos DB para o Azure Functions 2.x e superior

Exemplo

Atributos

Decoradores

Anotações

Configuração

Uso

conexões

Cadeia de conexão

Conexões baseadas em identidade

Conceder permissão para a identidade

Próximas etapas

Comentários

Recursos adicionais