Associações do Azure Cosmos DB para Azure Functions 1.x

• Versão 1
• Versão 2

Importante

O suporte da versão 1.x do runtime do Azure Functions terminará em 14 de setembro de 2026. Recomendamos que você migre seus aplicativos para a versão 4.x para receber suporte completo.

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

Observação

Este artigo serve para o Azure Functions 1.x. Para saber mais sobre como usar essas associações em Functions 2.x e superior, veja Associações do Azure Cosmos DB para Azure Functions 2.x.

Essa associação era originalmente denominada DocumentDB. No Azure Functions versão 1.x, apenas o gatilho foi renomeado Azure Cosmos DB; a associação de entrada, a associação de saída e o pacote NuGet mantêm o nome DocumentDB.

Observação

As associações do Azure Cosmos DB têm suporte apenas para usar com a API do SQL. 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 Apache Cassandra, o Azure Cosmos DB for Apache Gremlin e o Azure Cosmos DB for Table.

Pacotes - Functions 1. x

As associações do Azure Cosmos DB para Functions versão 1.x são fornecidas no pacote NuGet Microsoft.Azure.WebJobs.Extensions.DocumentDB, versão 1.x. O código-fonte para a associação está no repositório GitHub azure-webjobs-sdk-extensions.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.

Ambiente de desenvolvimento	Para adicionar suporte em Funções 1.x
Desenvolvimento local - biblioteca de classes do C#	Instalar o pacote
Desenvolvimento local - Script do C#, JavaScript, F#	Automática
Desenvolvimento de portal	Automática

Gatilho

O Gatilho do Azure Cosmos DB usa o Feed de Alterações do Azure Cosmos DB para escutar as inserções e atualizações nas partições. O feed de alteração publica inserções e atualizações, não exclusões.

Gatilho - exemplo

C#

O exemplo a seguir mostra uma função C# em processo que é chamada quando há inserções ou atualizações na coleção e no banco de dados especificados.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;

namespace CosmosDBSamplesV1
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            TraceWriter log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.Info($"Documents modified: {documents.Count}");
                log.Info($"First document Id: {documents[0].Id}");
            }
        }
    }
}

JavaScript

O exemplo a seguir mostra uma associação de gatilho do Azure Cosmos DB em um arquivo function.json e uma função do JavaScript que usa a associação. A função grava mensagens de log quando registros do Azure Cosmos DB são modificados.

Aqui estão os dados de associação no arquivo function.json:

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Aqui está o código JavaScript:

    module.exports = async function (context, documents) {
        context.log('First document Id modified : ', documents[0].id);
    }

Gatilho – atributos

C#

Para bibliotecas de classes de C# em processo, use o atributo CosmosDBTrigger.

O construtor do atributo toma o nome do banco de dados e o nome da coleção. Para obter informações sobre essas configurações e outras propriedades que podem ser configuradas, consulte Gatilho – configurações. Aqui está um exemplo de atributo CosmosDBTrigger em uma assinatura de método:

    [FunctionName("DocumentUpdates")]
    public static void Run(
        [CosmosDBTrigger("database", "collection", ConnectionStringSetting = "myCosmosDB")]
    IReadOnlyList<Document> documents,
        TraceWriter log)
    {
        ...
    }

Para ver um exemplo completo, consulte Gatilho – exemplo de C#.

JavaScript

O JavaScript não dá suporte a atributos.

Gatilho – configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no atributo .

Propriedade function.json	Propriedade de atributo	Descrição
tipo	n/d	Deve ser definido como cosmosDBTrigger.
direction	n/d	Deve ser definido como in. Esse parâmetro é definido automaticamente quando você cria o gatilho no portal do Azure.
name	n/d	O nome da variável usado no código de função que representa a lista de documentos com alterações.
connectionStringSetting	ConnectionStringSetting	O nome de uma configuração de aplicativo que contém a cadeia de conexão usada para conectar-se à conta do Azure Cosmos DB que está sendo monitorada.
databaseName	DatabaseName	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
collectionName	CollectionName	O nome da coleção que está sendo monitorada.
leaseConnectionStringSetting	LeaseConnectionStringSetting	(Opcional) O nome de uma configuração de aplicativo que contém a cadeia de conexão para o serviço com a coleção de concessão. Quando não definido, o valor connectionStringSetting é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal. A cadeia de conexão da coleção de concessões deve ter permissões de gravação.
leaseDatabaseName	LeaseDatabaseName	(Opcional) O nome do banco de dados que contém a coleção usada para armazenar as concessões. Quando não definido, o valor da configuração databaseName é usado. Esse parâmetro é definido automaticamente quando a associação é criada no portal.
leaseCollectionName	LeaseCollectionName	(Opcional) O nome da coleção usada para armazenar as concessões. Quando não definido, o valor leases é usado.
createLeaseCollectionIfNotExists	CreateLeaseCollectionIfNotExists	(Opcional) Quando definido como true, a coleção de concessões é criada automaticamente quando ela ainda não existe. O valor padrão é false.
leasesCollectionThroughput	leasesCollectionThroughput	(Opcional) Define a quantidade de Unidades de Solicitação a atribuir quando a coleção de concessões for criada. Essa configuração é usada apenas quando createLeaseCollectionIfNotExists é definido como true. Esse parâmetro é definido automaticamente quando a associação é criada usando o portal.
leaseCollectionPrefix	LeaseCollectionPrefix	(Opcional) Quando definido, ele adiciona um prefixo às concessões criadas na coleção de Concessão para esta Função, permitindo efetivamente duas funções do Azure Functions separadas para compartilhar a mesma coleção de Concessão usando prefixos diferentes.
feedPollDelay	FeedPollDelay	(Opcional) Quando definido, ele define, em milissegundos, o atraso entre a sondagem de uma partição quanto a novas alterações no feed, depois que todas as alterações atuais forem descarregadas. O padrão é 5000 (5 segundos).
leaseAcquireInterval	LeaseAcquireInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo para disparar uma tarefa para computar se as partições são distribuídas uniformemente entre as instâncias de host conhecidas. O padrão é 13000 (13 segundos).
leaseExpirationInterval	LeaseExpirationInterval	(Opcional), Quando definido, ele define, em milissegundos, o intervalo para o qual a concessão é tomada em uma concessão que representa uma partição. Se a concessão não for renovada dentro deste intervalo, ela será expirada e a propriedade da partição será movida para outra instância. O padrão é 60000 (60 segundos).
leaseRenewInterval	LeaseRenewInterval	(Opcional) Quando definido, ele define, em milissegundos, o intervalo de renovação para todas as concessões para partições atualmente mantidas por uma instância. O padrão é 17000 (17 segundos).
checkpointFrequency	CheckpointFrequency	(Opcional) Quando definido, ele define, em milissegundos, o intervalo entre os pontos de verificação de concessão. O padrão é sempre após cada chamada de Função.
maxItemsPerInvocation	MaxItemsPerInvocation	(Opcional) Quando definido, ele personaliza a quantidade máxima de itens recebidos por chamada de Função.
startFromBeginning	startFromBeginning	Quando definido, ele informa o gatilho para iniciar a leitura de alterações desde o início do histórico de coleção em vez da hora atual. Isso funciona apenas na primeira vez em que gatilho inicia, como em execuções subsequentes, os pontos de verificação já estão armazenados. Definir isso como true quando houver concessões já criadas não tem nenhum efeito.

Ao desenvolver localmente, adicione suas configurações do aplicativo no arquivo ocal.settings.json na coleção Values.

Gatilho - uso

O gatilho requer uma segunda coleção que ele usa para armazenar concessões sobre as partições. Tanto a coleção que está sendo monitorada quanto a coleção que contém as concessões devem estar disponíveis para o gatilho funcionar.

Importante

Se várias funções estiverem configuradas para usar um gatilho do Azure Cosmos DB para a mesma coleção, cada uma das funções deverá usar uma coleção de concessões dedicada ou especificar uma LeaseCollectionPrefix diferente para cada função. Caso contrário, apenas uma das funções será disparada. Para obter informações sobre o prefixo, veja a seção de Configuração.

O gatilho não indica se um documento foi atualizado ou inserido, ele fornece apenas o documento em si. Se você precisa lidar com inserções e atualizações de forma diferente, você pode fazer isso com a implementação de campos de carimbo de hora de inserção ou atualização.

Entrada

A associação de dados de entrada do Azure Cosmos DB usa a API de SQL para recuperar um ou mais documentos do Azure Cosmos DB e passá-los para o parâmetro de entrada da função. A ID do documento ou os parâmetros de consulta podem ser determinados com base no gatilho que invoca a função.

Entrada - exemplo

C#

Esta seção contém os seguintes exemplos:

• Gatilho da fila, pesquisar ID no JSON
• Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta
• Gatilho HTTP, pesquisar ID nos dados da rota
• Gatilho HTTP, pesquisar ID nos dados da rota, usando SqlQuery
• Gatilho HTTP, obter vários documentos, usando SqlQuery
• Gatilho HTTP, obter vários documentos, usando DocumentClient

Os exemplos se referem a um tipo ToDoItem simples:

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Gatilho da fila, pesquisar ID no JSON

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é disparada por uma mensagem da fila que contém um objeto JSON. O gatilho da fila analisa o JSON em um objeto chamado ToDoItemLookup, que contém a ID a pesquisar. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

namespace CosmosDBSamplesV1
{
    public class ToDoItemLookup
    {
        public string ToDoItemId { get; set; }
    }
}

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}")]ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId}");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
        }
    }
}

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de consulta para especificar a ID a ser pesquisada. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é disparada por uma solicitação HTTP que usa os dados da rota para especificar a ID a pesquisar. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static HttpResponseMessage Run(
            [HttpTrigger(
                AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Ignorar exemplos de entrada

Gatilho HTTP, pesquisar ID nos dados da rota, usando SqlQuery

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é disparada por uma solicitação HTTP que usa os dados da rota para especificar a ID a pesquisar. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")] IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Ignorar exemplos de entrada

Gatilho HTTP, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma função C# que recupera uma lista de documentos. A função é disparada por uma solicitação HTTP. A consulta é especificada na propriedade do atributo SqlQuery.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

Ignorar exemplos de entrada

Gatilho HTTP, obter vários documentos, usando DocumentClient (C#)

O exemplo a seguir mostra uma função C# que recupera uma lista de documentos. A função é disparada por uma solicitação HTTP. O código usa uma instância DocumentClient fornecida pela associação do Azure Cosmos DB para ler uma lista de documentos. A instância DocumentClient também pode ser usada para as operações de gravação.

using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

namespace CosmosDBSamplesV1
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
            string searchterm = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "searchterm", true) == 0)
                .Value;

            if (searchterm == null)
            {
                return req.CreateResponse(HttpStatusCode.NotFound);
            }

            log.Info($"Searching for word: {searchterm} using Uri: {collectionUri.ToString()}");
            IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
                .Where(p => p.Description.Contains(searchterm))
                .AsDocumentQuery();

            while (query.HasMoreResults)
            {
                foreach (ToDoItem result in await query.ExecuteNextAsync())
                {
                    log.Info(result.Description);
                }
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

JavaScript

Esta seção contém os seguintes exemplos:

• Gatilho da fila, pesquisar ID no JSON
• Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta
• Gatilho HTTP, pesquisar ID nos dados da rota
• Gatilho da fila, obter vários documentos, usando SqlQuery

Gatilho da fila, pesquisar ID no JSON

O exemplo a seguir mostra uma associação de dados de entrada do Cosmos DB em um arquivo function.json e uma função script C# que usa a associação de dados. A função lê um documento único e atualiza o valor de texto do documento.

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "inputDocumentIn",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

A seção configuração explica essas propriedades.

Aqui está o código JavaScript:

    // Change input document contents using Azure Cosmos DB input binding, using context.bindings.inputDocumentOut
    module.exports = async function (context) {
        context.bindings.inputDocumentOut = context.bindings.inputDocumentIn;
        context.bindings.inputDocumentOut.text = "This was updated!";
    };

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função de script JavaScript que recupera um único documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de consulta para especificar a ID a ser pesquisada. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}"
    }
  ],
  "disabled": true
}

Aqui está o código JavaScript:

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir mostra uma função de script JavaScript que recupera um único documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de consulta para especificar a ID a ser pesquisada. Essa ID é usada para recuperar um documento ToDoItem no banco de dados e na coleção especificados.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}"
    }
  ],
  "disabled": false
}

Aqui está o código JavaScript:

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

Gatilho da fila, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma associação de dados de entrada do Cosmos DB em um arquivo function.json e uma função script C# que usa a associação de dados. A função recupera vários documentos especificados por uma consulta SQL usando um gatilho de fila para personalizar os parâmetros de consulta.

O gatilho de consulta fornece um parâmetro departmentId. Uma mensagem de consulta de { "departmentId" : "Finance" } retornará todos os registros ao departamento financeiro.

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "documents",
    "type": "documentdb",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connection": "CosmosDBConnection"
}

A seção configuração explica essas propriedades.

Aqui está o código JavaScript:

    module.exports = async function (context, input) {
        var documents = context.bindings.documents;
        for (var i = 0; i < documents.length; i++) {
            var document = documents[i];
            // operate on each document
        }
    };

Entrada – atributos

C#

Em bibliotecas de classes de C# em processo, use o atributo DocumentDB.

O construtor do atributo toma o nome do banco de dados e o nome da coleção. Para obter informações sobre essas configurações e outras propriedades que podem ser configuradas, consulte a seção de configuração a seguir.

JavaScript

O JavaScript não dá suporte a atributos.

Entrada - configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no atributo .

Propriedade function.json	Propriedade de atributo	Descrição
tipo	n/d	Deve ser definido como documentdb.
direction	n/d	Deve ser definido como in.
name	n/d	Nome do parâmetro de associação que representa o documento na função.
databaseName	DatabaseName	O banco de dados que contém o documento.
collectionName	CollectionName	O nome da coleção que contém o documento.
id	Id	A ID do documento a ser recuperado. Essa propriedade dá suporte a expressões de associação. Não defina ambas as propriedades id e sqlQuery. Se você não definir uma ou outra, toda a coleção é recuperada.
sqlQuery	SqlQuery	Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade dá suporte a associações em tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina ambas as propriedades id e sqlQuery. Se você não definir uma ou outra, toda a coleção é recuperada.
connection	ConnectionStringSetting	O nome da configuração do aplicativo que contém a cadeia de conexão do Azure Cosmos DB.
partitionKey	PartitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação.

Ao desenvolver localmente, adicione suas configurações do aplicativo no arquivo ocal.settings.json na coleção Values.

Entrada - uso

C#

Quando a função sai com êxito, todas as alterações feitas no documento de entrada por parâmetros de entrada nomeados são persistidas automaticamente.

JavaScript

As atualizações não são feitas automaticamente após a saída da função. Em vez disso, use context.bindings.<documentName>In e context.bindings.<documentName>Out para fazer atualizações. Consulte o exemplo de entrada.

Saída

Com a associação de saída do Azure Cosmos DB, você pode gravar um novo documento para um banco de dados do Azure Cosmos DB usando a API de SQL.

Saída - exemplo

C#

Esta seção contém os seguintes exemplos:

• Gatilho da fila, gravar um documento
• Gatilho da fila, gravar documentos usando IAsyncCollector

Os exemplos se referem a um tipo ToDoItem simples:

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

Gatilho da fila, gravar um documento

O exemplo a seguir mostra uma função C# que adiciona um documento a um banco de dados, usando os dados fornecidos na mensagem do armazenamento de fila.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System;

namespace CosmosDBSamplesV1
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            TraceWriter log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.Info($"C# Queue trigger function inserted one row");
            log.Info($"Description={queueMessage}");
        }
    }
}

Gatilho da fila, gravar documentos usando IAsyncCollector

O exemplo a seguir mostra uma função C# que adiciona uma coleção de documentos a um banco de dados, usando os dados fornecidos em um JSON de mensagem da fila.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;

namespace CosmosDBSamplesV1
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            TraceWriter log)
        {
            log.Info($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.Info($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

JavaScript

O exemplo a seguir mostra uma associação de saída do Azure Cosmos DB em um arquivo function.json e uma função de script C# que usa a associação. A função usa uma associação de entrada de fila para uma fila que recebe o JSON no seguinte formato:

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

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

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

Aqui estão os dados de associação no arquivo function.json:

{
    "name": "employeeDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

A seção configuração explica essas propriedades.

Aqui está o código JavaScript:

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

Saída - atributos

C#

Em bibliotecas de classes de C# em processo, use o atributo DocumentDB.

O construtor do atributo toma o nome do banco de dados e o nome da coleção. Para obter informações sobre essas configurações e outras propriedades que podem ser configuradas, consulte Saída – configurações. Aqui está um exemplo de atributo DocumentDB em uma assinatura de método:

    [FunctionName("QueueToDocDB")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [DocumentDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

Para um exemplo completo, confira Saída.

JavaScript

O JavaScript não dá suporte a atributos.

Saída - configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no atributo .

Propriedade function.json	Propriedade de atributo	Descrição
tipo	n/d	Deve ser definido como documentdb.
direction	n/d	Deve ser definido como out.
name	n/d	Nome do parâmetro de associação que representa o documento na função.
databaseName	DatabaseName	O banco de dados que contém a coleção na qual o documento será criado.
collectionName	CollectionName	O nome da coleção na qual o documento será criado.
createIfNotExists	CreateIfNotExists	É um valor booliano para indicar se a coleção será criada quando não existir. O padrão é false porque as novas coleções são criadas com a taxa de transferência reservada, o que tem implicações de preço. Para saber mais, confira a página de preço.
partitionKey	PartitionKey	Quando CreateIfNotExists for true, define o caminho da chave de partição para a coleção criada.
CollectionThroughput	CollectionThroughput	Quando CreateIfNotExists for true, define a CreateIfNotExists da coleção criada.
connection	ConnectionStringSetting	O nome da configuração do aplicativo que contém a cadeia de conexão do Azure Cosmos DB.

Ao desenvolver localmente, adicione suas configurações do aplicativo no arquivo ocal.settings.json na coleção Values.

Saída - uso

Por padrão, quando você grava no parâmetro de saída em sua função, um documento é criado no banco de dados. Este documento contém um GUID gerado automaticamente como a ID do documento. Você pode especificar a ID do documento de saída especificando a propriedade id no objeto JSON enviado ao parâmetro de saída.

Observação

Ao especificar a ID de um documento existente, ela é substituída pelo novo documento de saída.

Exceções e códigos de retorno

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

Próximas etapas

• Saiba mais sobre a computação de banco de dados sem servidor com o Azure Cosmos DB
• Saiba mais sobre gatilhos e associações do Azure Functions