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

• Versão 1
• Versão 2 e superior

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

Ação	Type
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

Nota

Esta referência é para o Azure Functions versão 2.x e superior. Para obter informações sobre como usar essas associações no Functions 1.x, consulte Associações do Azure Cosmos DB para o Azure Functions 1.x.

Essa associação foi originalmente chamada de Banco de Dados de Documentos. No Azure Functions versão 2.x e superior, o gatilho, as associações e o pacote são todos denominados Azure Cosmos DB.

APIs suportadas

As associações do Azure Cosmos DB só têm suporte para uso com o Azure Cosmos DB para NoSQL. O suporte para o Azure Cosmos DB for Table é fornecido usando as associações de armazenamento de tabela, começando com a extensão 5.x. Para todas as outras APIs do Azure Cosmos DB, você deve acessar o banco de dados de sua função usando o cliente estático para sua API, incluindo o Azure Cosmos DB para MongoDB, Azure Cosmos DB para Cassandra e Azure Cosmos DB para Apache Gremlin.

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

A extensão de associações do Azure Cosmos DB faz parte de um pacote de extensão, que é especificado em seu arquivo de projeto host.json . Talvez seja necessário modificar esse pacote para alterar a versão da associação ou se os pacotes ainda não estiverem instalados. Para saber mais, consulte Pacote de extensão.

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.

Pacote v4.x

Esta versão do pacote contém a versão 4.x da extensão de ligações do Azure Cosmos DB que 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.

Você pode adicionar esta versão da extensão do pacote de extensão de visualização v4 adicionando ou substituindo o seguinte código em seu host.json arquivo:

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

Para saber mais, consulte Atualizar suas extensões.

Pacote v2.x e v3.x

Você pode instalar esta versão da extensão em seu aplicativo de função registrando o pacote de extensão, versão 2.x ou 3.x.

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

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

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

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 nas versões 2.x e superiores. As configurações no arquivo host.json se aplicam a todas as funções em uma instância de aplicativo de função. O exemplo host.json arquivo abaixo contém apenas as configurações da versão 2.x+ para essa ligação. Para obter mais informações sobre definições de configuração de aplicativo de função nas versões 2.x e versões posteriores, consulte host.json referência para o Azure Functions.

Extensão 4.x+

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

Property	Predefinição	Description
connectionMode	Gateway	O modo de conexão usado pela função ao se conectar ao serviço Azure Cosmos DB. As opções são Direct e Gateway
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"
            }
        }
    }
}

Property	Predefinição	Description
connectionMode	Gateway	O modo de conexão usado pela função ao se conectar ao serviço Azure Cosmos DB. As opções são Direct e Gateway
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)