Compartilhar via


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

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:

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.

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

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

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

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

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

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 como executar uma função como alterações de dados no Azure Cosmos DB.

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

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

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.

Anotações

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

Configuração

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

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:

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

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 internas1
Gatilho2 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

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

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

Próximas etapas