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

O Gatilho do Azure Cosmos DB usa o feed de alterações do Azure Cosmos DB para ouvir inserções e atualizações entre partições. O feed de alterações publica itens novos e atualizados, não incluindo atualizações de exclusões.

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

As decisões de dimensionamento do Cosmos DB para os planos Consumo e Premium são feitas por meio do dimensionamento baseado em metas. Para obter mais informações, consulte Dimensionamento baseado em destino.

Importante

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

O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

v2

O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

v1

O modelo de programação Python v1 requer que você defina ligações em um arquivo function.json separado na pasta de funções. Para obter mais informações, consulte o guia do desenvolvedor do Python.

Este artigo suporta 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 em seu aplicativo de função, que pode ser uma das seguintes:

Modelo de trabalhador isolado

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

Modelo em processo

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte total.

Uma biblioteca de classes em processo é uma função C# compilada executada no mesmo processo que o tempo de execução do Functions.

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

Extensão 4.x+

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 refere-se a um tipo simples ToDoItem .

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

Funções 2.x+

O exemplo a seguir mostra uma função C# que é invocada quando há inserções ou atualizações no banco de dados e na coleção 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}");
            }
        }
    }
}

Extensão 4.x+

Este exemplo refere-se a um tipo simples ToDoItem :

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

A função a seguir é invocada quando há inserções ou atualizações no banco de dados e na coleção 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);
        }
    }
}

Funções 2.x+

O código a seguir define um MyDocument tipo:

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 vinculação de gatilho do Azure Cosmos DB no exemplo a seguir:

[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 using instruções:

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+

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

Funções 2.x+

    @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 tempo de execução de funções Java, use a @CosmosDBTrigger anotação em parâmetros cujo valor viria do Azure Cosmos DB. Essa anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando Optional<T>.

Modelo v4

O exemplo a seguir mostra uma função TypeScript de gatilho do Azure Cosmos DB. A função grava mensagens de log quando os 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 v3

Os exemplos do TypeScript não estão documentados para o modelo v3.

Modelo v4

O exemplo a seguir mostra uma função JavaScript de gatilho do Azure Cosmos DB. A função grava mensagens de log quando os 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`);
    },
});

Modelo v3

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

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

Funções 2.x+

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

Funções 4.x+

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

Observe que alguns dos nomes de atributos 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.

Funções 2.x+

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

Funções 4.x+

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

Observe que alguns dos nomes de atributos 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 aciona a função por meio do $Documents parâmetro.

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 depende se você usa o modelo de programação Python v1 ou v2.

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

v1

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

Funções 2.x+

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

Funções 4.x+

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

Observe que alguns dos nomes de atributos 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# de processo em processo e isoladas usam o 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#.

Extensão 4.x+

Propriedade Attribute	Description
Ligaçã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 monitorada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
Nome do contêiner	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 Connection valor é usado. Este parâmetro é definido automaticamente quando a ligação é criada no portal. A cadeia de conexão para o 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 concessões . Quando não está definido, o databaseName valor da configuração é usado.
LeaseContainerName	(Opcional) O nome do contêiner usado para armazenar locações. Quando não definido, o valor leases é usado.
CreateLeaseContainerIfNotExists	(Opcional) Quando definido como true, o contêiner de concessões é criado automaticamente quando ainda não existe. O valor predefinido é 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 poderá ser iniciada.
LeasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação a serem atribuídas quando o contêiner de concessões é criado. Essa configuração só é usada quando CreateLeaseContainerIfNotExists está definida como true. Este parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo às concessões criadas no contêiner Lease para essa função. O uso de um prefixo permite que duas Funções do Azure separadas compartilhem o mesmo contêiner de Concessão usando prefixos diferentes.
FeedPollDelay	(Opcional) O tempo (em milissegundos) para o atraso entre a sondagem de uma partição para novas alterações no feed, depois que todas as alterações atuais são drenadas. O padrão é 5.000 milissegundos ou 5 segundos.
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para iniciar uma tarefa para calcular se as partições são distribuídas uniformemente entre 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 de 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 ao ler itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior do 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 ao Gatilho para ler as alterações desde o início do histórico de alterações do contêiner em vez de começar no momento atual. A leitura desde o início só funciona na primeira vez que o gatilho é iniciado, pois nas execuções subsequentes, os pontos de verificação já estão armazenados. Definir essa opção para true quando houver concessões já criadas não terá efeito.
StartFromTime	(Opcional) Obtém ou define a data e a hora a partir das quais inicializar a operação de leitura do feed de alterações. O formato recomendado é 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, alterar esse valor não terá efeito.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Funções 2.x+

Propriedade Attribute	Description
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 monitorada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com a coleção 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 contém a coleção de concessão. Quando não definido, o ConnectionStringSetting valor é usado. Este parâmetro é definido automaticamente quando a ligação é criada no portal. A cadeia de conexão para a 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 concessões . Quando não está definido, o databaseName valor da configuração é usado.
LeaseCollectionName	(Opcional) O nome da coleção usada para armazenar locações. Quando não definido, o valor leases é usado.
CreateLeaseCollectionIfNotExists	(Opcional) Quando definida como true, a coleção de concessões é criada automaticamente quando ainda não existe. O valor predefinido é false.
LeasesCollectionThroughput	(Opcional) Define o número de Unidades de Solicitação a serem atribuídas quando a coleção de concessões é criada. Essa configuração só é usada quando CreateLeaseCollectionIfNotExists está definida como true. Este parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseCollectionPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo às concessões criadas na coleção Lease para esta função. O uso de um prefixo permite que duas Funções do Azure separadas compartilhem a mesma coleção de Concessão usando prefixos diferentes.
FeedPollDelay	(Opcional) O tempo (em milissegundos) para o atraso entre a sondagem de uma partição para novas alterações no feed, depois que todas as alterações atuais são drenadas. O padrão é 5.000 milissegundos ou 5 segundos.
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para iniciar uma tarefa para calcular se as partições são distribuídas uniformemente entre 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 de partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
Ponto de verificaçãoInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo entre os pontos de verificação de locação. O padrão é sempre após cada chamada de função.
Ponto de verificaçãoDocumentCount	(Opcional) Personaliza a quantidade de documentos entre os pontos de verificação de locaçã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 ao ler itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior do 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 ao Gatilho para ler as alterações desde o início do histórico de alterações da coleção, em vez de começar no momento atual. A leitura desde o início só funciona na primeira vez que o gatilho é iniciado, pois nas execuções subsequentes, os pontos de verificação já estão armazenados. Definir essa opção para true quando houver concessões já criadas não terá efeito.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".
UseMultipleWriteLocations	(Opcional) Permite que contas de várias regiões gravem na coleção de locações.
UseDefaultJsonSerialization	(Opcional) Permite que você use JsonConvert.DefaultSettings na coleção monitorada. Essa configuração só se aplica à 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.

Extensão 4.x+

Propriedade Attribute	Description
Ligaçã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 monitorada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
Nome do contêiner	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 Connection valor é usado. Este parâmetro é definido automaticamente quando a ligação é criada no portal. A cadeia de conexão para o 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 concessões . Quando não está definido, o databaseName valor da configuração é usado.
LeaseContainerName	(Opcional) O nome do contêiner usado para armazenar locações. Quando não definido, o valor leases é usado.
CreateLeaseContainerIfNotExists	(Opcional) Quando definido como true, o contêiner de concessões é criado automaticamente quando ainda não existe. O valor predefinido é 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 poderá ser iniciada.
LeasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação a serem atribuídas quando o contêiner de concessões é criado. Essa configuração só é usada quando CreateLeaseContainerIfNotExists está definida como true. Este parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo às concessões criadas no contêiner Lease para essa função. O uso de um prefixo permite que duas Funções do Azure separadas compartilhem o mesmo contêiner de Concessão usando prefixos diferentes.
FeedPollDelay	(Opcional) O tempo (em milissegundos) para o atraso entre a sondagem de uma partição para novas alterações no feed, depois que todas as alterações atuais são drenadas. O padrão é 5.000 milissegundos ou 5 segundos.
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para iniciar uma tarefa para calcular se as partições são distribuídas uniformemente entre 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 de 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 ao ler itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior do 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 ao Gatilho para ler as alterações desde o início do histórico de alterações do contêiner em vez de começar no momento atual. A leitura desde o início só funciona na primeira vez que o gatilho é iniciado, pois nas execuções subsequentes, os pontos de verificação já estão armazenados. Definir essa opção para true quando houver concessões já criadas não terá efeito.
StartFromTime	(Opcional) Obtém ou define a data e a hora a partir das quais inicializar a operação de leitura do feed de alterações. O formato recomendado é 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, alterar esse valor não terá efeito.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Funções 2.x+

Propriedade Attribute	Description
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 monitorada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com a coleção 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 contém a coleção de concessão. Quando não definido, o ConnectionStringSetting valor é usado. Este parâmetro é definido automaticamente quando a ligação é criada no portal. A cadeia de conexão para a 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 concessões . Quando não está definido, o databaseName valor da configuração é usado.
LeaseCollectionName	(Opcional) O nome da coleção usada para armazenar locações. Quando não definido, o valor leases é usado.
CreateLeaseCollectionIfNotExists	(Opcional) Quando definida como true, a coleção de concessões é criada automaticamente quando ainda não existe. O valor predefinido é false.
LeasesCollectionThroughput	(Opcional) Define o número de Unidades de Solicitação a serem atribuídas quando a coleção de concessões é criada. Essa configuração só é usada quando CreateLeaseCollectionIfNotExists está definida como true. Este parâmetro é definido automaticamente quando a associação é criada usando o portal.
LeaseCollectionPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo às concessões criadas na coleção Lease para esta função. O uso de um prefixo permite que duas Funções do Azure separadas compartilhem a mesma coleção de Concessão usando prefixos diferentes.
FeedPollDelay	(Opcional) O tempo (em milissegundos) para o atraso entre a sondagem de uma partição para novas alterações no feed, depois que todas as alterações atuais são drenadas. O padrão é 5.000 milissegundos ou 5 segundos.
LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para iniciar uma tarefa para calcular se as partições são distribuídas uniformemente entre 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 de partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
Ponto de verificaçãoInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo entre os pontos de verificação de locação. O padrão é sempre após cada chamada de função.
Ponto de verificaçãoDocumentCount	(Opcional) Personaliza a quantidade de documentos entre os pontos de verificação de locaçã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 ao ler itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior do 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 ao Gatilho para ler as alterações desde o início do histórico de alterações da coleção, em vez de começar no momento atual. A leitura desde o início só funciona na primeira vez que o gatilho é iniciado, pois nas execuções subsequentes, os pontos de verificação já estão armazenados. Definir essa opção para true quando houver concessões já criadas não terá efeito.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".
UseMultipleWriteLocations	(Opcional) Permite que contas de várias regiões gravem na coleção de locações.
UseDefaultJsonSerialization	(Opcional) Permite que você use JsonConvert.DefaultSettings na coleção monitorada. Essa configuração só se aplica à 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 apenas ao modelo de programação Python v2.

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

Property	Description
arg_name	O nome da variável usada no código da 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 sendo monitorada.
collection_name	O nome da coleção do Azure Cosmos DB que está sendo monitorada.
connection	A cadeia de conexão do Azure Cosmos DB que está sendo monitorada.

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

Anotações

Extensão 4.x+

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

Use a @CosmosDBTrigger anotação em parâmetros que leem dados do Azure Cosmos DB. A anotação suporta as seguintes propriedades:

Propriedade Attribute	Description
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 monitorada. Para obter mais informações, consulte Conexões.
Designação	O nome da função.
Nome do banco de dados	O nome do banco de dados do Azure Cosmos DB com o contêiner 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 Connection valor é usado. Este parâmetro é definido automaticamente quando a ligação é criada no portal. A cadeia de conexão para o 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 concessões . Quando não está definido, o databaseName valor da configuração é usado.
leaseContainerName	(Opcional) O nome do contêiner usado para armazenar locações. Quando não definido, o valor leases é usado.
createLeaseContainerIfNotExists	(Opcional) Quando definido como true, o contêiner de concessões é criado automaticamente quando ainda não existe. O valor predefinido é 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 será iniciada.
leasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação a serem atribuídas quando o contêiner de concessões é criado. Essa configuração só é usada quando CreateLeaseContainerIfNotExists está definida como true. Este parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo às concessões criadas no contêiner Lease para essa função. O uso de um prefixo permite que duas Funções do Azure separadas compartilhem o mesmo contêiner de Concessão usando prefixos diferentes.
feedPollDelay	(Opcional) O tempo (em milissegundos) para o atraso entre a sondagem de uma partição para novas alterações no feed, depois que todas as alterações atuais são drenadas. O padrão é 5.000 milissegundos ou 5 segundos.
leaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para iniciar uma tarefa para calcular se as partições são distribuídas uniformemente entre 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 de 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 ao ler itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior do 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 ao Gatilho para ler as alterações desde o início do histórico de alterações do contêiner em vez de começar no momento atual. A leitura desde o início só funciona na primeira vez que o gatilho é iniciado, pois nas execuções subsequentes, os pontos de verificação já estão armazenados. Definir essa opção para true quando houver concessões já criadas não terá efeito.
preferredLocations	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Funções 2.x+

Na biblioteca de tempo de execução de funções Java, use a @CosmosDBTrigger anotação em parâmetros que leem dados do Azure Cosmos DB. A anotação suporta as seguintes propriedades:

• Designação
• connectionStringSetting
• Nome do banco de dados
• collectionName
• leaseConnectionStringSetting
• leaseDatabaseName
• leaseCollectionName
• createLeaseCollectionIfNotExists
• leasesCollectionThroughput
• leaseCollectionPrefix
• feedPollDelay
• leaseAcquireInterval
• leaseExpirationInterval
• leaseRenewInterval
• checkpointInterval
• ponto de verificaçãoDocumentCount
• maxItemsPerInvocation
• startFromBeginning
• preferredLocations

Configuração

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

Modelo v4

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

Modelo v3

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json, onde as propriedades diferem de acordo com a versão da extensão:

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json, onde as propriedades diferem de acordo com a versão da extensão:

Extensão 4.x+

function.json propriedade	Description
type	Deve ser definido como cosmosDBTrigger.
direção	Deve ser definido como in. Esse parâmetro é definido automaticamente quando você cria o gatilho no portal do Azure.
Designação	O nome da variável usada no código da função que representa a lista de documentos com alterações.
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 monitorada. Para obter mais informações, consulte Conexões.
Nome do banco de dados	O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
containerName	O nome do contêiner que está sendo monitorado.
arrendarConexão	(Opcional) O nome de uma configuração de aplicativo ou contêiner de configuração que especifica como se conectar à conta do Azure Cosmos DB que contém o contêiner de concessão. Quando não definido, o connection valor é usado. Este parâmetro é definido automaticamente quando a ligação é criada no portal. A cadeia de conexão para o 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 concessões . Quando não está definido, o databaseName valor da configuração é usado.
leaseContainerName	(Opcional) O nome do contêiner usado para armazenar locações. Quando não definido, o valor leases é usado.
createLeaseContainerIfNotExists	(Opcional) Quando definido como true, o contêiner de concessões é criado automaticamente quando ainda não existe. O valor predefinido é 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 poderá ser iniciada.
leasesContainerThroughput	(Opcional) Define o número de Unidades de Solicitação a serem atribuídas quando o contêiner de concessões é criado. Essa configuração só é usada quando createLeaseContainerIfNotExists está definida como true. Este parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseContainerPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo às concessões criadas no contêiner Lease para essa função. O uso de um prefixo permite que duas Funções do Azure separadas compartilhem o mesmo contêiner de Concessão usando prefixos diferentes.
feedPollDelay	(Opcional) O tempo (em milissegundos) para o atraso entre a sondagem de uma partição para novas alterações no feed, depois que todas as alterações atuais são drenadas. O padrão é 5.000 milissegundos ou 5 segundos.
leaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para iniciar uma tarefa para calcular se as partições são distribuídas uniformemente entre 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 de 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 ao ler itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior do 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 ao Gatilho para ler as alterações desde o início do histórico de alterações do contêiner em vez de começar no momento atual. A leitura desde o início só funciona na primeira vez que o gatilho é iniciado, pois nas execuções subsequentes, os pontos de verificação já estão armazenados. Definir essa opção para true quando houver concessões já criadas não terá efeito.
startFromTime	(Opcional) Obtém ou define a data e a hora a partir das quais inicializar a operação de leitura do feed de alterações. O formato recomendado é 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, alterar esse valor não terá efeito.
preferredLocations	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Funções 2.x+

function.json propriedade	Description
type	Deve ser definido como cosmosDBTrigger.
direção	Deve ser definido como in. Esse parâmetro é definido automaticamente quando você cria o gatilho no portal do Azure.
Designação	O nome da variável usada no código da 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 monitorada. Para obter mais informações, consulte Conexões.
Nome do banco de dados	O nome do banco de dados do Azure Cosmos DB com a coleção 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 contém a coleção de concessão. Quando não definido, o connectionStringSetting valor é usado. Este parâmetro é definido automaticamente quando a ligação é criada no portal. A cadeia de conexão para a 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 concessões . Quando não está definido, o databaseName valor da configuração é usado.
leaseCollectionName	(Opcional) O nome da coleção usada para armazenar locações. Quando não definido, o valor leases é usado.
createLeaseCollectionIfNotExists	(Opcional) Quando definida como true, a coleção de concessões é criada automaticamente quando ainda não existe. O valor predefinido é false.
leasesCollectionThroughput	(Opcional) Define o número de Unidades de Solicitação a serem atribuídas quando a coleção de concessões é criada. Essa configuração só é usada quando createLeaseCollectionIfNotExists está definida como true. Este parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseCollectionPrefix	(Opcional) Quando definido, o valor é adicionado como um prefixo às concessões criadas na coleção Lease para esta função. O uso de um prefixo permite que duas Funções do Azure separadas compartilhem a mesma coleção de Concessão usando prefixos diferentes.
feedPollDelay	(Opcional) O tempo (em milissegundos) para o atraso entre a sondagem de uma partição para novas alterações no feed, depois que todas as alterações atuais são drenadas. O padrão é 5.000 milissegundos ou 5 segundos.
leaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para iniciar uma tarefa para calcular se as partições são distribuídas uniformemente entre 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 de 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 locação. O padrão é sempre após cada chamada de função.
ponto de verificaçãoDocumentCount	(Opcional) Personaliza a quantidade de documentos entre os pontos de verificação de locaçã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 ao ler itens do feed de alterações. Como resultado, o número de itens recebidos pode ser maior do 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 ao Gatilho para ler as alterações desde o início do histórico de alterações da coleção, em vez de começar no momento atual. A leitura desde o início só funciona na primeira vez que o gatilho é iniciado, pois nas execuções subsequentes, os pontos de verificação já estão armazenados. Definir essa opção para true quando houver concessões já criadas não terá efeito.
preferredLocations	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".
useMultipleWriteLocations	(Opcional) Permite que contas de várias regiões gravem na coleção de locações.

Consulte a seção Exemplo para obter exemplos completos.

Utilização

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 locações devem estar disponíveis para que o gatilho funcione.

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ão dedicada ou especificar uma diferente LeaseCollectionPrefix 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ão dedicada ou especificar uma diferente leaseCollectionPrefix 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ão dedicada ou especificar uma diferente leaseCollectionPrefix para cada função. Caso contrário, apenas uma das funções será acionada. Para obter informações sobre o prefixo, consulte a seção Configuração.

O gatilho não indica se um documento foi atualizado ou inserido, apenas fornece o próprio documento. Se você precisar lidar com atualizações e inserções de forma diferente, poderá fazer isso implementando campos de carimbo de data/hora para inserção ou atualização.

O tipo de parâmetro suportado pelo gatilho do Azure Cosmos DB depende da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Extensão 4.x+

Consulte Tipos de vinculação para obter uma lista de tipos suportados.

Funções 2.x+

Consulte Tipos de vinculação para obter uma lista de tipos suportados.

Extensão 4.x+

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

Tipo	Description
Tipos serializáveis JSON	As funções tentam desserializar os dados JSON do documento do feed de alteração do Cosmos DB para um tipo de objeto CLR (POCO) simples.

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

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

Funções 2.x+

Consulte Tipos de vinculação para obter uma lista de tipos suportados.

Ligações

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

• O nome de uma configuração de aplicativo que contém uma cadeia de conexão
• O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade. Esta opção só está disponível para as connection versões e leaseConnection da versão 4.x ou superior da extensão.

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

Connection string

A cadeia de conexão para sua conta de banco de dados deve ser armazenada em uma configuração de aplicativo com um nome correspondente ao valor especificado pela propriedade connection da configuração de ligaçã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 tal, deverá especificar as definições num prefixo comum que mapeia para a propriedade de connection na configuração do enlace e do acionador.

Neste modo, a extensão requer as seguintes propriedades:

Property	Modelo de variável de ambiente	Description	Valor de exemplo
Ponto de extremidade da conta	<CONNECTION_NAME_PREFIX>__accountEndpoint	O URI do ponto de extremidade da conta do Azure Cosmos DB.	https://< database_account_name.documents.azure.com:443/>

Propriedades adicionais podem ser definidas para personalizar a conexão. Consulte Propriedades comuns para conexões baseadas em identidade.

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

Conceder permissão à 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 você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha 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 integrado do Cosmos DB que é construído em conceitos semelhantes. Você precisará criar uma atribuição de função que forneça acesso à sua conta de banco de dados em tempo de execução. As funções de Gerenciamento do RBAC do Azure, como 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 que você escreve.

Tipo de vinculação	Exemplo de funçõesinternas 1
Gatilho2	Colaborador de dados integrado do Cosmos DB
Vinculação de entrada	Leitor de dados integrado do Cosmos DB
Vinculação de saída	Colaborador de dados integrado do Cosmos DB

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

2 Ao usar a identidade, o Cosmos DB trata a criação de contêineres 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 que você crie os contêineres necessários para o gatilho (incluindo o contêiner de concessão) antes de configurar sua função.

Próximos passos

• Ler um documento do Azure Cosmos DB (Ligação de entrada)
• Salvar alterações em um documento do Azure Cosmos DB (vinculação de saída)