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

  • Artigo

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:

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.

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

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

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.

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.

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:

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

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

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.

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.

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

Próximos passos