Vinculação de saída do Azure Cosmos DB para o Azure Functions 2.x e superior

  • Artigo

A associação de saída do Azure Cosmos DB permite gravar um novo documento em um banco de dados do Azure Cosmos DB usando a API SQL.

Para obter informações sobre detalhes de instalação e configuração, consulte a visão geral.

Importante

Este artigo usa guias para oferecer suporte a várias versões do modelo de programação Node.js. O modelo v4 está geralmente disponível e foi projetado para ter uma experiência mais flexível e intuitiva para desenvolvedores JavaScript e TypeScript. Para obter mais detalhes sobre como o modelo v4 funciona, consulte o Guia do desenvolvedor do Azure Functions Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

Este artigo suporta ambos os modelos de programação.

Uma função C# pode ser criada usando um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
  • Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do 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#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

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.

Exemplo

Salvo indicação em contrário, os exemplos neste artigo destinam-se à versão 3.x da extensão do Azure Cosmos DB. Para uso com a extensão versão 4.x, você precisa substituir a cadeia de caracteres collection em nomes de propriedade e atributo por container e connection_string_setting com connection.

O código a seguir define um MyDocument tipo:

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

No exemplo a seguir, o tipo de retorno é um IReadOnlyList<T>, que é uma lista modificada de documentos do parâmetro de vinculação de gatilho:

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public class CosmosDBFunction
    {
        private readonly ILogger<CosmosDBFunction> _logger;

        public CosmosDBFunction(ILogger<CosmosDBFunction> logger)
        {
            _logger = logger;
        }

        //<docsnippet_exponential_backoff_retry_example>
        [Function(nameof(CosmosDBFunction))]
        [ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
        [CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
        public object Run(
            [CosmosDBTrigger(
                "%CosmosDb%",
                "%CosmosContainerIn%",
                Connection = "CosmosDBConnection",
                LeaseContainerName = "leases",
                CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
            FunctionContext context)
        {
            if (input != null && input.Any())
            {
                foreach (var doc in input)
                {
                    _logger.LogInformation("Doc Id: {id}", doc.Id);
                }

                // Cosmos Output
                return input.Select(p => new { id = p.Id });
            }

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

Gatilho de fila, salvar mensagem no banco de dados via valor de retorno

O exemplo a seguir mostra uma função Java que adiciona um documento a um banco de dados com dados de uma mensagem no armazenamento de filas.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

Gatilho HTTP, salve um documento no banco de dados via valor de retorno

O exemplo a seguir mostra uma função Java cuja assinatura é anotada com @CosmosDBOutput e tem valor de retorno do tipo String. O documento JSON retornado pela função será gravado automaticamente na coleção correspondente do Azure Cosmos DB.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

Gatilho HTTP, salve um documento no banco de dados via OutputBinding

O exemplo a seguir mostra uma função Java que grava um documento no Azure Cosmos DB por meio de um OutputBinding<T> parâmetro de saída. Neste exemplo, o outputItem parâmetro precisa ser anotado com @CosmosDBOutput, não com a assinatura da função. O uso OutputBinding<T> permite que sua função aproveite a associação para gravar o documento no Azure Cosmos DB e, ao mesmo tempo, permita retornar um valor diferente para o chamador de função, como um documento JSON ou XML.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

HTTP trigger, salve vários documentos no banco de dados via OutputBinding

O exemplo a seguir mostra uma função Java que grava vários documentos no Azure Cosmos DB por meio de um OutputBinding<T> parâmetro de saída. Neste exemplo, o outputItem parâmetro é anotado com @CosmosDBOutput, não com a assinatura da função. O parâmetro output, outputItem tem uma lista de objetos como seu tipo de parâmetro de ToDoItem modelo. O uso OutputBinding<T> permite que sua função aproveite a associação para gravar os documentos no Azure Cosmos DB e, ao mesmo tempo, permitir retornar um valor diferente para o chamador de função, como um documento JSON ou XML.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

Na biblioteca de tempo de execução de funções Java, use a @CosmosDBOutput anotação em parâmetros que serão gravados no Azure Cosmos DB. O tipo de parâmetro de anotação deve ser OutputBinding<T>, onde T é um tipo Java nativo ou um POJO.

O exemplo a seguir mostra uma função TypeScript acionada pela fila de armazenamento para uma fila que recebe JSON no seguinte formato:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

A função cria documentos do Azure Cosmos DB no seguinte formato para cada registro:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Aqui está o código TypeScript:

import { app, InvocationContext, output } from '@azure/functions';

interface MyQueueItem {
    name: string;
    employeeId: string;
    address: string;
}

interface MyCosmosItem {
    id: string;
    name: string;
    employeeId: string;
    address: string;
}

export async function storageQueueTrigger1(queueItem: MyQueueItem, context: InvocationContext): Promise<MyCosmosItem> {
    return {
        id: `${queueItem.name}-${queueItem.employeeId}`,
        name: queueItem.name,
        employeeId: queueItem.employeeId,
        address: queueItem.address,
    };
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: output.cosmosDB({
        databaseName: 'MyDatabase',
        collectionName: 'MyCollection',
        createIfNotExists: true,
        connectionStringSetting: 'MyAccount_COSMOSDB',
    }),
    handler: storageQueueTrigger1,
});

Para produzir vários documentos, retorne uma matriz em vez de um único objeto. Por exemplo:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

O exemplo a seguir mostra uma função JavaScript acionada por fila de armazenamento para uma fila que recebe JSON no seguinte formato:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

A função cria documentos do Azure Cosmos DB no seguinte formato para cada registro:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Aqui está o código JavaScript:

const { app, output } = require('@azure/functions');

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: true,
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: cosmosOutput,
    handler: (queueItem, context) => {
        return {
            id: `${queueItem.name}-${queueItem.employeeId}`,
            name: queueItem.name,
            employeeId: queueItem.employeeId,
            address: queueItem.address,
        };
    },
});

Para produzir vários documentos, retorne uma matriz em vez de um único objeto. Por exemplo:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

O exemplo a seguir mostra como gravar dados no Azure Cosmos DB usando uma associação de saída. A associação é declarada no arquivo de configuração da função (functions.json) e obtém dados de uma mensagem de fila e grava em um documento do Azure Cosmos DB.

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
}

No arquivo run.ps1, o objeto retornado da função é mapeado para um EmployeeDocument objeto, que é persistido no banco de dados.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

O exemplo a seguir demonstra como gravar um documento em um banco de dados do Azure Cosmos DB como a saída de uma função. O exemplo depende se você usa o modelo de programação Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

Atributos

As bibliotecas C# do processo de trabalho em processo e isoladas usam atributos para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Propriedade Attribute Description
Ligação O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
Nome do contêiner O nome do contêiner que está sendo monitorado.
CreateIfNotExists Um valor booleano para indicar se o contêiner é criado quando ele não existe. O padrão é falso porque novos contêineres são criados com taxa de transferência reservada, o que tem implicações de custo. Para obter mais informações, consulte a página de preços.
PartitionKey Quando CreateIfNotExists é true, ele define o caminho da chave de partição para o contêiner criado. Pode incluir parâmetros de vinculação.
Taxa de transferência de contêiner Quando CreateIfNotExists é true, ele define a taxa de transferência do contêiner criado.
Locais preferidos (Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

Decoradores

Aplica-se apenas ao modelo de programação Python v2.

Para funções Python v2 definidas usando um decorador, as seguintes propriedades no cosmos_db_output:

Property Description
arg_name O nome da variável usada no código da função que representa a lista de documentos com alterações.
database_name O nome do banco de dados do Azure Cosmos DB com a coleção sendo monitorada.
collection_name O nome da coleção do Azure Cosmos DB que está sendo monitorada.
create_if_not_exists Um valor booleano que indica se o banco de dados e a coleção devem ser criados se não existirem.
connection_string_setting A cadeia de conexão do Azure Cosmos DB que está sendo monitorada.

Para funções Python definidas usando function.json, consulte a seção Configuração .

Anotações

Na biblioteca de tempo de execução de funções Java, use a @CosmosDBOutput anotação em parâmetros que gravam no Azure Cosmos DB. A anotação suporta as seguintes propriedades:

Configuração

Aplica-se apenas ao modelo de programação Python v1.

A tabela a seguir explica as propriedades que você pode definir no options objeto passado para o output.cosmosDB() método. As typepropriedades , direction, e name não se aplicam ao modelo v4.

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json, onde as propriedades diferem de acordo com a versão da extensão:

function.json propriedade Description
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorada. Para obter mais informações, consulte Conexões.
Nome do banco de dados O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
containerName O nome do contêiner que está sendo monitorado.
createIfNotExists Um valor booleano para indicar se o contêiner é criado quando ele não existe. O padrão é falso porque novos contêineres são criados com taxa de transferência reservada, o que tem implicações de custo. Para obter mais informações, consulte a página de preços.
partitionKey Quando createIfNotExists é true, ele define o caminho da chave de partição para o contêiner criado. Pode incluir parâmetros de vinculação.
taxa de transferência de contêiner Quando createIfNotExists é true, ele define a taxa de transferência do contêiner criado.
preferredLocations (Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

Consulte a seção Exemplo para obter exemplos completos.

Utilização

Por padrão, quando você grava no parâmetro de saída em sua função, um documento é criado em seu banco de dados. Você deve especificar a ID do documento de saída especificando a id propriedade no objeto JSON passado para o parâmetro output.

Nota

Quando você especifica a ID de um documento existente, ela é substituída pelo novo documento de saída.

O tipo de parâmetro suportado pela ligação de saída do Cosmos DB depende da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

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

Ligações

As connectionStringSetting/connection propriedades e leaseConnectionStringSetting/leaseConnection são referências à configuração do ambiente que especifica como o aplicativo deve se conectar ao Azure Cosmos DB. Podem especificar:

  • O nome de uma configuração de aplicativo que contém uma cadeia de conexão
  • O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade. Esta opção só está disponível para as connection versões e leaseConnection da versão 4.x ou superior da extensão.

Se o valor configurado for uma correspondência exata para uma única configuração e uma correspondência de prefixo para outras configurações, a correspondência exata será usada.

Connection string

A cadeia de conexão para sua conta de banco de dados deve ser armazenada em uma configuração de aplicativo com um nome correspondente ao valor especificado pela propriedade connection da configuração de ligação.

Conexões baseadas em identidade

Se você estiver usando a versão 4.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para tal, deverá especificar as definições num prefixo comum que mapeia para a propriedade de connection na configuração do enlace e do acionador.

Neste modo, a extensão requer as seguintes propriedades:

Property Modelo de variável de ambiente Description Valor de exemplo
Ponto de extremidade da conta <CONNECTION_NAME_PREFIX>__accountEndpoint O URI do ponto de extremidade da conta do Azure Cosmos DB. https://< database_account_name.documents.azure.com:443/>

Propriedades adicionais podem ser definidas para personalizar a conexão. Consulte Propriedades comuns para conexões baseadas em identidade.

Quando hospedadas no serviço Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída ao sistema é usada por padrão, embora uma identidade atribuída ao usuário possa ser especificada com as credential propriedades e clientID . Observe que não há suporte para a configuração de uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, sua identidade de desenvolvedor é usada, embora isso possa ser personalizado. Consulte Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão à identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços do Azure, isso significa que você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha escopo apenas sobre os recursos que precisam ser lidos.

O Cosmos DB não usa o RBAC do Azure para operações de dados. Em vez disso, ele usa um sistema RBAC integrado do Cosmos DB que é construído em conceitos semelhantes. Você precisará criar uma atribuição de função que forneça acesso à sua conta de banco de dados em tempo de execução. As funções de Gerenciamento do RBAC do Azure, como Proprietário , não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Azure Cosmos DB em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação Exemplo de funçõesinternas 1
Gatilho2 Colaborador de dados integrado do Cosmos DB
Vinculação de entrada Leitor de dados integrado do Cosmos DB
Vinculação de saída Colaborador de dados integrado do Cosmos DB

1 Essas funções não podem ser usadas em uma atribuição de função RBAC do Azure. Consulte a documentação do sistema RBAC integrado do Cosmos DB para obter detalhes sobre como atribuir essas funções.

2 Ao usar a identidade, o Cosmos DB trata a criação de contêineres como uma operação de gerenciamento. Ele não está disponível como uma operação de plano de dados para o gatilho. Você precisará garantir que você crie os contêineres necessários para o gatilho (incluindo o contêiner de concessão) antes de configurar sua função.

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

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

Próximos passos