Visão geral de gatilhos e associações do Azure Cosmos DB para Azure Functions 2.x e superiores

• Versão 1
• Versão 2 e superiores

Este conjunto de artigos explica como trabalhar com associações do Azure Cosmos DB no Azure Functions 2.x e superiores. 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 for criado ou modificado	Gatilho
Leia um documento do Azure Cosmos DB	Associação de entrada
Salvar alterações a um documento do Azure Cosmos DB	Associação de saída

Observação

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

Essa associação era originalmente denominada DocumentDB. No Azure Functions versão 2.x e superior, o gatilho, as associações e o pacote são todos chamados Azure Cosmos DB.

APIs com suporte

Só há suporte para uso das associações do Azure Cosmos DB com o Azure Cosmos DB for NoSQL. O suporte para o Azure Cosmos DB for Table é fornecido por meio das 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 da sua função usando o cliente estático da API, incluindo o Azure Cosmos DB for MongoDB, o Azure Cosmos DB for Cassandra e o Azure Cosmos DB for Apache Gremlin.

Instalar a extensão

O pacote NuGet da extensão instalado depende do modo C# usado no aplicativo de funções:

Modelo de trabalho isolado

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

Modelo em processo

Importante

O suporte terminará para o modelo em processo em 10 de novembro de 2026. É altamente recomendável migrar seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

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

Em uma variação desse modelo, o Functions pode ser executado usando scripts C#, que é compatível principalmente com a edição do portal C#. Para atualizar as extensões de associação existentes dos aplicativos do script do C# no portal sem precisar republicar o aplicativo de funções, consulte Atualizar as extensões.

O processo para instalar a extensão varia de acordo com a versão da extensão:

Extensão 4.x e posterior

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

Esta versão da extensão de associações do Azure Cosmos DB introduz a capacidade de conexão usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções 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 v2 Microsoft.Azure.DocumentDB por tipos mais novos do SDK v3 Microsoft.Azure.Cosmos. Saiba mais sobre como esses novos tipos são diferentes e como migrá-los dos exemplos guia de migração do SDK, gatilho, associação de entrada e associação de saída.

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

Functions 2.x+

Essa seção descreve como usar uma biblioteca de classes. Para scripts 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ê referencie o pacote NuGet adequado. Instale o pacote NuGet versão 3.x.

Extensão 4.x e posterior

Esta versão da extensão de associações do Azure Cosmos DB introduz a capacidade de conexão usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções 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 representante que usa um parâmetro IFunctionsWorkerApplication. Em seguida, dentro do corpo desse representante, chame ConfigureCosmosDBExtension() no objeto:

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

Functions 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 no arquivo de projeto host.json. Talvez seja necessário modificar esse pacote se for preciso alterar a versão das associações ou se os pacotes ainda não estiverem instalados. Para saber mais, confira pacotes de extensão.

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

Pacote v4.x

Esta versão do pacote contém a versão 4.x da extensão de associações do Azure Cosmos DB que introduz a capacidade de conexão por meio de uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções com conexões baseadas em identidade.

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

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

Para saber mais, confira Atualizar suas extensões.

Pacote v2.x and v3.x

Essa versão da extensão pode ser instalada no aplicativo de funções 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 associação

Os tipos de associação com suporte para .NET dependem da versão da extensão e do modo de execução do C#, que pode ser um dos seguintes:

Modelo de trabalho isolado

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

Modelo em processo

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

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

Extensão 4.x e posterior

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

Cenário de associação	Tipos de parâmetro
Gatilho do Cosmos DB (documento único)	Tipos serializáveis JSON1
Gatilho do Cosmos DB (lote de documentos)	IEnumerable<T> em que T é um tipo serializável por JSON 1
Entrada do Cosmos DB (documento único)	Tipos serializáveis JSON1
Entrada do Cosmos DB (consulta que retorna vários documentos)	CosmosClient IEnumerable<T> em que T é um tipo serializável por JSON 1
Saída do Cosmos DB (documento único)	Tipos serializáveis JSON1
Saída do Cosmos DB (vários documentos)	ICollector<T> ou IAsyncCollector<T> em que T é um tipo serializável por JSON 1

¹ Documentos que contêm dados JSON podem ser desserializados em tipos POCO (objeto CLR) conhecidos.

Functions 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 e posterior

O processo de trabalho isolado dá suporte a tipos de parâmetro de acordo com a tabela abaixo. A compatibilidade com associações a tipo do Microsoft.Azure.Cosmos está em versão prévia.

Gatilho do Azure Cosmos DB

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.

Associação de entrada do Azure Cosmos DB

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

Type	Descrição
Tipos serializáveis JSON	O Functions tenta desserializar os dados JSON do documento em um tipo de objeto CLR básico (POCO) simples.

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

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

¹ Para usar esses tipos, você precisa referenciar Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0-preview1 ou posterior e as dependências comuns para associações de tipo SDK.

Associação de saída do Cosmos DB

Quando você desejar que a função seja gravada em um único documento, a associação de saída do Cosmos DB poderá ser associada aos seguintes tipos:

Type	Descrição
Tipos serializáveis JSON	Um objeto que representa o conteúdo JSON de um documento. O Functions tenta serializar um tipo de objeto CLR básico (POCO) em dados JSON.

Quando você desejar que a função seja gravada em vários documentos, a associação de saída do Cosmos DB poderá ser associada aos seguintes tipos:

Type	Descrição
T[] em que T é um tipo serializável por JSON	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 com outros tipos diretamente de 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 do SDK do Azure.

Functions 2.x+

Versões anteriores de extensões no processo de trabalho isolado só dão suporte à associação a tipos serializáveis JSON. Opções adicionais estão disponíveis para extensão 4.x e superior.

Exceções e códigos de retorno

Associação	Referência
Azure Cosmos DB	Códigos de status HTTP para Azure Cosmos DB

configurações de host.json

Esta seção descreve as definições de configuração disponíveis para a 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 do aplicativo de funções. O arquivo host.json de exemplo abaixo contém apenas as configurações das versões 2.x e superiores para a associação. Para saber mais sobre as definições de configuração do aplicativo de funções nas versões 2.x e superiores, confira a referência de host.json para o Azure Functions.

Extensão 4.x e posterior

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

Propriedade	Padrão	Descrição
connectionMode	Gateway	O modo de conexão usado pela função ao se conectar ao serviço do Azure Cosmos DB. As opções são Direct e Gateway
userAgentSuffix	n/d	Adiciona o valor da cadeia de caracteres especificada a todas as solicitações feitas pelo gatilho ou pela associação ao serviço. Isso facilita o acompanhamento da atividade no Azure Monitor, com base em um aplicativo de funções específico e com o filtro por User Agent.

Functions 2.x+

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

Propriedade	Padrão	Descrição
connectionMode	Gateway	O modo de conexão usado pela função ao se conectar ao serviço do Azure Cosmos DB. As opções são Direct e Gateway
protocol	Https	O protocolo de conexão usado pela função ao se conectar ao serviço do Azure Cosmos DB. Leia aqui para obter uma explicação de ambos os modos.
leasePrefix	N/D	Prefixo de concessão a ser usado em todas as funções em um aplicativo.

Próximas etapas

• Executar uma função quando um documento do Azure Cosmos DB é criado ou modificado (Gatilho)
• Ler um documento do Azure Cosmos DB (Associação de entrada)
• Salvar alterações a um documento do Azure Cosmos DB (associação de saída)