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

  • Artigo

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:

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.

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

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

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.

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.

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:

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

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

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.

1 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 tipos diretamente do Microsoft.Azure.Cosmos.

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.

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

Próximas etapas