Visão geral do gatilho e associações do Azure Cosmos DB para o Azure Functions

Este conjunto de artigos explica como trabalhar com associações do Azure Cosmos DB no Azure Functions. O Azure Functions dá suporte a associações de gatilho, entrada e saída para o Azure Cosmos DB.

Ação	Tipo
Executar uma função quando um documento do Azure Cosmos DB é criado ou modificado	Acionador
Ler um documento do Azure Cosmos DB	Vinculação de entrada
Salvar alterações em um documento do Azure Cosmos DB	Vinculação de saída

Importante

Esta versão da extensão de vinculação do Azure Cosmos DB dá suporte ao Azure Functions versão 4.x. Se seu aplicativo ainda usa a versão 1.x do tempo de execução do Functions, consulte Associações do Azure Cosmos DB para o Azure Functions 1.x. No tempo de execução do Functions v1.x, essa associação foi originalmente nomeada DocumentDB.

APIs suportadas

Esta tabela indica como se conectar às várias APIs do Azure Cosmos DB a partir do seu código de função:

API	Recommendation
Azure Cosmos DB para NoSQL	Usar a extensão de vinculação do Azure Cosmos DB
Azure Cosmos DB para MongoDB	Use um SDK de cliente nativo.
Azure Cosmos DB para Tabela	Use a versão 5.x ou posterior da extensão de vinculação Tabelas do Azure.
Azure Cosmos DB para Apache Cassandra	Use um SDK de cliente nativo.
Azure Cosmos DB para Apache Gremlin (Graph API)	Usar um SDK de cliente nativo
Azure Cosmos DB para PostgreSQL	Use um SDK de cliente nativo.

Instalar a extensão

O pacote de extensão NuGet que você instala depende do modo C# que você está usando em seu aplicativo de função:

Modelo de trabalhador isolado

As funções são executadas em um processo de trabalho C# isolado. Para saber mais, consulte Guia para executar o C# Azure Functions em um processo de trabalho isolado.

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.

As funções são executadas no mesmo processo que o host Functions. Para saber mais, consulte Desenvolver funções de biblioteca de classes C# usando o Azure Functions.

Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. Para atualizar extensões de vinculação existentes para aplicativos de script C# em execução no portal sem precisar publicar novamente seu aplicativo de função, consulte Atualizar suas extensões.

O processo de instalação da extensão varia dependendo da versão da extensão:

Extensão 4.x+

Esta seção descreve o uso de uma biblioteca de classes. Para scripts em C#, você precisaria instalar o pacote de extensão, versão 4.x.

Esta versão da extensão de ligações do Azure Cosmos DB introduz a capacidade de se conectar usando uma identidade em vez de um segredo. Para obter um tutorial sobre como configurar seus aplicativos de função com identidades gerenciadas, consulte o tutorial de criação de um aplicativo de função com conexões baseadas em identidade.

Esta versão também altera os tipos aos quais você pode se associar, substituindo os tipos do SDK Microsoft.Azure.DocumentDB v2 por tipos mais recentes do SDK v3 Microsoft.Azure.Cosmos. Saiba mais sobre como esses novos tipos são diferentes e como migrar para eles a partir do guia de migração do SDK, gatilho, vinculação de entrada e exemplos de vinculação de saída.

Esta versão de extensão está disponível como um pacote NuGet, versão 4.x.

Funções 2.x+

Esta seção descreve o uso de uma biblioteca de classes. Para scripts em C#, você precisaria instalar o pacote de extensão, versão 2.x ou 3.x.

Trabalhar com o gatilho e as associações requer que você faça referência ao pacote NuGet apropriado. Instale o pacote NuGet, versão 3.x.

Extensão 4.x+

Esta versão da extensão de ligações do Azure Cosmos DB introduz a capacidade de se conectar usando uma identidade em vez de um segredo. Para obter um tutorial sobre como configurar seus aplicativos de função com identidades gerenciadas, consulte o tutorial de criação de um aplicativo de função com conexões baseadas em identidade.

Adicione a extensão ao seu projeto instalando o pacote NuGet, versão 4.x.

Se você estiver escrevendo seu aplicativo usando F#, também deverá configurar essa extensão como parte da configuração de inicialização do aplicativo. Na chamada para ConfigureFunctionsWorkerDefaults() ou ConfigureFunctionsWebApplication(), adicione um delegado que usa um IFunctionsWorkerApplication parâmetro. Em seguida, dentro do corpo desse delegado, chame ConfigureCosmosDBExtension() o objeto:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Funções 2.x+

Adicione a extensão ao seu projeto instalando o pacote NuGet, versão 3.x.

Instalar pacote

Para poder usar essa extensão de associação em seu aplicativo, certifique-se de que o arquivo dehost.json na raiz do seu projeto contém esta extensionBundle referência:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

Neste exemplo, o version valor de instrui o host Functions a usar uma versão de [4.0.0, 5.0.0) pacote que seja pelo menos 4.0.0 , mas menor que 5.0.0, que inclui todas as versões potenciais do 4.x. Essa notação mantém efetivamente seu aplicativo na versão secundária mais recente disponível do pacote de extensão v4.x.

Quando possível, você deve usar a versão principal mais recente do pacote de extensão e permitir que o tempo de execução mantenha automaticamente a versão secundária mais recente. Você pode visualizar o conteúdo do pacote mais recente na página de lançamento dos pacotes de extensão. Para obter mais informações, consulte Pacotes de extensão do Azure Functions.

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.

Tipos de vinculação

Os tipos de associação suportados para .NET dependem da versão da extensão e do modo de execução C#, que pode ser um dos 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

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

Escolha uma versão para ver os detalhes do tipo de vinculação para o modo e a versão.

Extensão 4.x+

A extensão do Azure Cosmos DB dá suporte a tipos de parâmetros de acordo com a tabela abaixo.

Cenário de vinculação	Tipos de parâmetros
Gatilho do Cosmos DB (documento único)	JSON serializável tipos1
Gatilho do Cosmos DB (lote de documentos)	IEnumerable<T>onde T é um JSON serializável tipo1
Entrada do Cosmos DB (documento único)	JSON serializável tipos1
Entrada do Cosmos DB (consulta que retorna vários documentos)	CosmosClient IEnumerable<T> onde T é um JSON serializável tipo1
Saída do Cosmos DB (documento único)	JSON serializável tipos1
Saída do Cosmos DB (vários documentos)	ICollector<T> ou IAsyncCollector<T> onde T é um JSON serializável tipo1

1 Os documentos que contêm dados JSON podem ser desserializados em tipos conhecidos de objeto CLR (POCO) simples.

Funções 2.x+

Versões anteriores da extensão expuseram tipos do namespace Microsoft.Azure.Documents agora preterido. Os tipos mais recentes do Microsoft.Azure.Cosmos são exclusivos da extensão 4.x e superior.

Extensão 4.x+

O processo de trabalho isolado suporta tipos de parâmetros de acordo com as tabelas abaixo. O suporte para associação a tipos de Microsoft.Azure.Cosmosestá em visualização.

Gatilho do Cosmos DB

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

Tipo	Descrição
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	Descrição
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.

Vinculação de entrada do Cosmos DB

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

Tipo	Descrição
Tipos serializáveis JSON	As funções tentam desserializar os dados JSON do documento em um tipo de objeto CLR antigo (POCO).

Quando você deseja que a função processe vários documentos de uma consulta, a associação de entrada do Cosmos DB pode se vincular aos seguintes tipos:

Tipo	Descrição
IEnumerable<T>onde T é um tipo serializável JSON	Uma enumeração de entidades retornadas pela consulta. Cada entrada representa um documento.
CosmosClient1	Um cliente conectado à conta do Cosmos DB.
Base de dados1	Um cliente conectado ao banco de dados do Cosmos DB.
Contentor1	Um cliente conectado ao contêiner do Cosmos DB.

1 Para usar esses tipos, você precisa fazer referência a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 ou posterior e às dependências comuns para associações de tipo SDK.

Ligação de saída do Cosmos DB

Quando você deseja que a função grave em um único documento, a associação de saída do Cosmos DB pode se vincular aos seguintes tipos:

Tipo	Descrição
Tipos serializáveis JSON	Um objeto que representa o conteúdo JSON de um documento. As funções tentam serializar um tipo de objeto CLR (POCO) antigo em dados JSON.

Quando você deseja que a função grave em vários documentos, a associação de saída do Cosmos DB pode se vincular aos seguintes tipos:

Tipo	Descrição
T[] onde T é JSON tipo serializável	Uma matriz que contém vários documentos. Cada entrada representa um documento.

Para outros cenários de saída, crie e use um CosmosClient diretamente com outros tipos do Microsoft.Azure.Cosmos . Consulte Registrar clientes do Azure para obter um exemplo de como usar a injeção de dependência para criar um tipo de cliente a partir do SDK do Azure.

Funções 2.x+

As versões anteriores das extensões no processo de trabalho isolado suportam apenas a vinculação a tipos serializáveis JSON. Opções adicionais estão disponíveis para a extensão 4.x e superior.

Tipos de vinculação SDK

O suporte de Tipo de SDK para o Azure Cosmos está em Pré-visualização. Siga o exemplo Python SDK Bindings for CosmosDB para começar a usar os tipos de SDK para Cosmos em Python.

Importante

Usar associações de tipo SDK requer o modelo de programação Python v2.

---

Enlace	Tipos de parâmetros	Exemplos
Entrada do CosmosDB	ContainerProxy, CosmosClient, DatabaseProxy	ContainerProxy, CosmosClient, DatabaseProxy

---

Exceções e códigos de devolução

Enlace	Referência
Azure Cosmos DB	Códigos de estado HTTP do Azure Cosmos DB

host.json configurações

Esta seção descreve as definições de configuração disponíveis para essa associação na versão 2.x e posterior. As configurações no arquivo host.json se aplicam a todas as funções em uma instância de aplicativo de função. Para obter mais informações sobre definições de configuração de aplicativo de função, consulte host.json referência para o Azure Functions.

Extensão 4.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Propriedade	Predefinição	Descrição
connectionMode	Gateway	O modo de conexão usado pela função ao se conectar ao serviço Azure Cosmos DB. Opções: Direct conecta-se diretamente a réplicas de back-end por TCP e pode fornecer latência mais baixa e Gateway roteia solicitações por meio de um gateway front-end por HTTPS. Para obter mais informações, consulte Modos de conexão do SDK do Azure Cosmos DB.
userAgentSuffix	n/d	Adiciona o valor de cadeia de caracteres especificado a todas as solicitações feitas pelo gatilho ou associação ao serviço. Isso facilita o acompanhamento da atividade no Azure Monitor, com base em um aplicativo de função específica e na filtragem por User Agent.

Funções 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Propriedade	Predefinição	Descrição
connectionMode	Gateway	O modo de conexão usado pela função ao se conectar ao serviço Azure Cosmos DB. Opções: Direct conecta-se diretamente a réplicas de back-end por TCP e pode fornecer latência mais baixa e Gateway roteia solicitações por meio de um gateway front-end por HTTPS. Para obter mais informações, consulte Modos de conexão do SDK do Azure Cosmos DB.
protocolo	Https	O protocolo de conexão usado pela função ao se conectar ao serviço Azure Cosmos DB. Leia aqui uma explicação de ambos os modos.
leasePrefix	n/d	Prefixo de concessão para usar em todas as funções em um aplicativo.

Próximos passos

• Executar uma função quando um documento do Azure Cosmos DB é criado ou modificado (Trigger)
• 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)