Associação de entrada do Azure Cosmos DB para o Azure Functions 2.x e superiores

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.

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

Observação

Se a coleção for particionada, as operações de pesquisa também precisarão especificar o valor da chave de partição.

Importante

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

O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

v2

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

v1

O modelo de programação v1 do Python requer que você defina as associações em um arquivo function.json separado na pasta de funções. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a ambos os modelos de programação.

Exemplo

Salvo indicação em contrário, os exemplos neste artigo se referem à 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 atributos e propriedades por container.

A função C# pode ser criada por meio de um dos seguintes modos C#:

• Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework. As extensões para funções do processo de trabalho isoladas usam namespaces Microsoft.Azure.Functions.Worker.Extensions.*.
• Modelo em processo: função C# compilada no mesmo processo que o runtime do 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#. As extensões para funções dentro do processo usam namespaces Microsoft.Azure.WebJobs.Extensions.*.

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 completo.

Modelo de trabalho isolado

Esta seção contém exemplos que exigem a versão 3.x da extensão do Azure Cosmos DB e a 5.x da extensão Armazenamento do Azure. Se elas ainda não estiverem presentes no aplicativo de funções, adicione uma referência aos seguintes pacotes NuGet:

• Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

• Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

• Gatilho da fila, pesquisar ID no JSON

Os exemplos se referem a um tipo ToDoItem simples:

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

Gatilho da fila, pesquisar ID no JSON

O exemplo a seguir mostra uma função que recupera um documento individual. A função é disparada por uma mensagem JSON na fila de armazenamento. O gatilho de fila analisa o JSON em um objeto do tipo ToDoItemLookup, que contém a ID e o valor da chave de partição a ser recuperado. Essa ID e o valor da chave de partição são usados para retornar um documento ToDoItem do banco de dados e da coleção especificados.

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

Modelo em processo

Esta seção contém os exemplos a seguir para usar funções de biblioteca de classes em C# em processo com a versão da extensão 3.x:

• 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
• Gatilho HTTP, obter vários documentos, usando CosmosClient (extensão v4)

Os exemplos se referem a um tipo ToDoItem simples:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        [JsonProperty("id")]
        public string Id { get; set; }

        [JsonProperty("partitionKey")]
        public string PartitionKey { 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 de fila analisará o JSON em um objeto do tipo ToDoItemLookup, que contém a ID e o valor da chave de partição a ser buscado. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

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

        public string ToDoItemPartitionKeyValue { get; set; }
    }
}

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}",
                PartitionKey = "{ToDoItemPartitionKeyValue}")]ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

            if (toDoItem == null)
            {
                log.LogInformation($"ToDo item not found");
            }
            else
            {
                log.LogInformation($"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 caracteres de consulta para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

Observação

O parâmetro de cadeia de caracteres de consulta HTTP diferencia maiusculas de minúsculas.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}",
                PartitionKey = "{Query.partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

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 dados de rota para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{partitionKey}/{id}")]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}",
                PartitionKey = "{partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

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.

O exemplo mostra como usar uma expressão de associação no parâmetro SqlQuery. Você pode passar os dados da rota para o parâmetro SqlQuery conforme mostrado, mas atualmente SqlQuery.

Observação

Se você precisar consultar apenas a ID, é recomendável usar uma pesquisa, como os exemplos anteriores, pois consumirá menos unidades de solicitação. As operações de leitura de ponto (GET) são mais eficientes do que as consultas por ID.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequest req,
            [CosmosDB("ToDoItems", "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

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.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

Gatilho HTTP, obter vários documentos, usando DocumentClient

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.

Observação

Você também pode usar a interface IDocumentClient para facilitar o teste.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
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 Microsoft.Extensions.Logging;
using System;
using System.Linq;
using System.Threading.Tasks;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"];
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");

            log.LogInformation($"Searching for: {searchterm}");

            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.LogInformation(result.Description);
                }
            }
            return new OkResult();
        }
    }
}

Gatilho HTTP, obter vários documentos, usando CosmosClient

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 CosmosClient fornecida pela associação do Azure Cosmos DB, disponível na CosmosClient para ler uma lista de documentos. A instância CosmosClient também pode ser usada para as operações de gravação.

using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingCosmosClient
    {  
        [FunctionName("DocsByUsingCosmosClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")] CosmosClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"].ToString();
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Container container = client.GetDatabase("ToDoItems").GetContainer("Items");

            log.LogInformation($"Searching for: {searchterm}");

            QueryDefinition queryDefinition = new QueryDefinition(
                "SELECT * FROM items i WHERE CONTAINS(i.Description, @searchterm)")
                .WithParameter("@searchterm", searchterm);
            using (FeedIterator<ToDoItem> resultSet = container.GetItemQueryIterator<ToDoItem>(queryDefinition))
            {
                while (resultSet.HasMoreResults)
                {
                    FeedResponse<ToDoItem> response = await resultSet.ReadNextAsync();
                    ToDoItem item = response.First();
                    log.LogInformation(item.Description);
                }
            }

            return new OkResult();
        }
    }
}

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

• Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta - parâmetro cadeia de caracteres
• Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta - parâmetro POJO
• Gatilho HTTP, pesquisar ID nos dados da rota
• Gatilho HTTP, pesquisar ID nos dados da rota, usando SqlQuery
• Gatilho HTTP, obter vários documentos dos dados da rota, usando SqlQuery

Os exemplos se referem a um tipo ToDoItem simples:

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta - parâmetro cadeia de caracteres

O exemplo a seguir mostra uma função Java que recupera um único documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento do banco de dados e da coleção especificados, no formato Cadeia de caracteres.

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

Na biblioteca de runtime de funções Java, use a anotação @CosmosDBInput em parâmetros de função cujo valor seria proveniente do Azure Cosmos DB. Essa anotação pode ser usada com tipos nativos do Java, POJOs ou valores que permitem valor nulos usando Optional<T>.

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta - parâmetro POJO

O exemplo a seguir mostra uma função Java que recupera um único documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento do banco de dados e da coleção especificados. O documento é então convertido em uma instância de ToDoItem POJO criado anteriormente e passada como um argumento para a função.

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir mostra uma função Java que recupera um único documento. A função é disparada por uma solicitação HTTP que usa um parâmetro de rota para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento do banco de dados e da coleção especificados, retornando-o como um Optional<String>.

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

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

O exemplo a seguir mostra uma função Java que recupera um único documento. A função é disparada por uma solicitação HTTP que usa um parâmetro de rota para especificar a ID a ser pesquisada. Essa ID é usada para recuperar um documento da coleção e banco de dados especificado, converter o resultado definido como um ToDoItem[], já que muitos documentos podem ser retornados, dependendo dos critérios de consulta.

Observação

Se você precisar consultar apenas a ID, é recomendável usar uma pesquisa, como os exemplos anteriores, pois consumirá menos unidades de solicitação. As operações de leitura de ponto (GET) são mais eficientes do que as consultas por ID.

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

Gatilho HTTP, obter vários documentos dos dados da rota, usando SqlQuery

O exemplo a seguir mostra uma função Java que recupera vários documentos. A função é disparada por uma solicitação HTTP que usa um parâmetro de rota desc para especificar a cadeia de caracteres a ser pesquisada no campo description. O termo de pesquisa é usado para recuperar uma coleção de documentos do banco de dados e coleção especificados, convertendo o conjunto de resultados para um ToDoItem[] e passando-o como um argumento para a função.

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

Esta seção contém os seguintes exemplos que leem um documento especificando um valor de ID de várias fontes:

• 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 função TypeScript que lê apenas um documento e atualiza o valor de texto do documento.

Modelo v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

Modelo v3

As amostras de TypeScript não estão documentadas para o modelo v3.

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função TypeScript que recupera apenas um documento. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

Modelo v4

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

Modelo v3

As amostras de TypeScript não estão documentadas para o modelo v3.

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir mostra uma função TypeScript que recupera apenas um documento. A função é disparada por uma solicitação HTTP que usa dados de rota para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

Modelo v4

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

Modelo v3

As amostras de TypeScript não estão documentadas para o modelo v3.

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

O exemplo a seguir mostra uma função TypeScript que 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.

Modelo v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

Modelo v3

As amostras de TypeScript não estão documentadas para o modelo v3.

Esta seção contém os seguintes exemplos que leem um documento especificando um valor de ID de várias fontes:

• 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 função JavaScript que lê apenas um documento e atualiza o valor de texto do documento.

Modelo v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

Modelo v3

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

{
    "name": "inputDocumentIn",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "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 caracteres de consulta para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

Modelo v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

Modelo v3

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": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "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 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 dados de rota para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

Modelo v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

Modelo v3

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{partitionKeyValue}/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}",
      "PartitionKey": "{partitionKeyValue}"
    }
  ],
  "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 função JavaScript que 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.

Modelo v4

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

Modelo v3

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

{
    "name": "documents",
    "type": "cosmosDB",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connectionStringSetting": "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 (const document of documents) {
    // operate on each document
  }
};

• 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 demonstra como ler e atualizar um único documento de Azure Cosmos DB. O identificador exclusivo do documento é fornecido por meio do valor JSON em uma mensagem da fila.

A associação de entrada do Azure Cosmos DB é listada primeiro na lista de associações encontradas no arquivo de configuração da função (function.json).

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

O arquivo run.ps1 tem o código do PowerShell que lê o documento de entrada e gera alterações.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document  

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta

O exemplo a seguir demonstra como ler e atualizar um único documento do Azure Cosmos DB de uma API Web. O identificador exclusivo do documento é fornecido por meio de um parâmetro querystring da solicitação HTTP, conforme definido na propriedade "Id": "{Query.Id}" da associação.

A associação de entrada do Azure Cosmos DB é listada primeiro na lista de associações encontradas no arquivo de configuração da função (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
} 

O arquivo run.ps1 tem o código do PowerShell que lê o documento de entrada e gera alterações.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir demonstra como ler e atualizar um único documento do Azure Cosmos DB de uma API Web. O identificador exclusivo do documento é fornecido por meio de um parâmetro de rota. O parâmetro de rota é definido na propriedade route da associação de solicitação HTTP e referenciado na propriedade da associação "Id": "{Id}" do Azure Cosmos DB.

A associação de entrada do Azure Cosmos DB é listada primeiro na lista de associações encontradas no arquivo de configuração da função (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
} 

O arquivo run.ps1 tem o código do PowerShell que lê o documento de entrada e gera alterações.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
} 

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

O exemplo a seguir demonstra como ler vários documentos do Azure Cosmos DB. O arquivo de configuração da função (function.json) define as propriedades de associação, que incluemsqlQuery. A instrução SQL fornecida para a propriedade sqlQuery seleciona o conjunto de documentos fornecidos para a função.

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
} 

O arquivo run1.ps1 tem o código do PowerShell, que lê os documentos de entrada.

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
} 

Esta seção contém os seguintes exemplos que leem um documento especificando um valor de ID de várias fontes:

• 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

Os exemplos dependem de você usar o modelo de programação do Python v1 ou v2 .

Gatilho da fila, pesquisar ID no JSON

O exemplo a seguir mostra uma associação de entrada do Azure Cosmos DB. A função lê um documento único e atualiza o valor de texto do documento.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

v1

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

{
    "name": "documents",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "$return",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

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

Aqui está o código Python:

import azure.functions as func

def main(queuemsg: func.QueueMessage, documents: func.DocumentList) -> func.Document:
    if documents:
        document = documents[0]
        document['text'] = 'This was updated!'
        return document

Gatilho HTTP, pesquisar ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função que recupera um documento individual. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

v2

Nenhum exemplo equivalente para a v2 no momento.

v1

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": "cosmosDB",
      "name": "todoitems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "scriptFile": "__init__.py"
}

Aqui está o código Python:

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])

    return 'OK'

Gatilho HTTP, pesquisar ID nos dados da rota

O exemplo a seguir mostra uma função que recupera um documento individual. A função é disparada por uma solicitação HTTP que usa dados de rota para especificar a ID e o valor da chave de partição a ser procurada. Essa ID e o valor da chave de partição são usados para recuperar um documento ToDoItem do banco de dados e da coleção especificados.

v2

Nenhum exemplo equivalente para a v2 no momento.

v1

Aqui está o arquivo function.json:

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

Aqui está o código Python:

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])
    return 'OK'

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

O exemplo a seguir mostra uma função Python de associação de entrada do Azure Cosmos DB que usa a associação. 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.

v2

Nenhum exemplo equivalente para a v2 no momento.

v1

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

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

Atributos

As bibliotecas C# em processo e de processo de trabalho isolado 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#.

Extensão 4.x e posterior

Propriedade de atributo	Descrição
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 consultada. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
ContainerName	O nome do contêiner que está sendo monitorado.
PartitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação. É necessário para as pesquisas em coleções particionadas.
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 das duas, toda a coleção será recuperada.
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 das duas, toda a coleção será recuperada.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, East US,South Central US,North Europe.

Functions 2.x+

Propriedade de atributo	Descrição
ConnectionStringSetting	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 monitorado. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
CollectionName	O nome da coleção que está sendo monitorada.
PartitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação. Ele é necessário para as pesquisas em coleções particionadas.
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	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.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Extensão 4.x e posterior

Propriedade de atributo	Descrição
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 consultada. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
ContainerName	O nome do contêiner que está sendo monitorado.
PartitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação. É necessário para as pesquisas em coleções particionadas.
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 das duas, toda a coleção será recuperada.
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 das duas, toda a coleção será recuperada.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, East US,South Central US,North Europe.

Functions 2.x+

Propriedade de atributo	Descrição
ConnectionStringSetting	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 monitorado. Para mais informações, consulte as Conexões.
DatabaseName	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
CollectionName	O nome da coleção que está sendo monitorada.
PartitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação. Ele é necessário para as pesquisas em coleções particionadas.
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	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.
PreferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Decoradores

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

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

Propriedade	DESCRIÇÃO
arg_name	O nome da variável usado no código de 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 que está sendo monitorada.
collection_name	O nome da coleção do Azure Cosmos DB sendo monitorada.
connection_string_setting	A cadeia de conexão do Azure Cosmos DB sendo monitorada.
partition_key	A chave de partição do Azure Cosmos DB que está sendo monitorada.
id	A ID do documento a ser recuperado.

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

Anotações

Na biblioteca de runtime de funções Java, use a anotação @CosmosDBInput nos parâmetros que leem dados do Azure Cosmos DB. Essa anotação dá suporte às seguintes propriedades:

• name
• connectionStringSetting
• databaseName
• collectionName
• dataType
• id
• partitionKey
• sqlQuery

Configuração

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

Modelo v4

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

Modelo v3

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json. Essas propriedades se diferenciam pela versão da extensão:

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json. Essas propriedades se diferenciam pela versão da extensão:

Extensão 4.x e posterior

Propriedade function.json	Descrição
tipo	Deve ser definido como cosmosDB.
direction	Deve ser definido como in.
name	O nome da variável usado no código de função que representa a lista de documentos com alterações.
connection	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 mais informações, consulte as Conexões.
databaseName	O nome do banco de dados do Azure Cosmos DB com o contêiner que está sendo monitorado.
containerName	O nome do contêiner que está sendo monitorado.
partitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação. É necessário para as pesquisas em coleções particionadas.
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 das duas, toda a coleção será recuperada.
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 das duas, toda a coleção será recuperada.
preferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, East US,South Central US,North Europe.

Functions 2.x+

Propriedade function.json	Descrição
tipo	Deve ser definido como cosmosDBTrigger.
direction	Deve ser definido como in.
name	O nome da variável usado no código de função que representa a lista de documentos com alterações.
connectionStringSetting	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 monitorado. Para mais informações, consulte as Conexões.
databaseName	O nome do banco de dados do Azure Cosmos DB com a coleção que está sendo monitorada.
collectionName	O nome da coleção que está sendo monitorada.
partitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de associação. Ele é necessário para as pesquisas em coleções particionadas.
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	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.
preferredLocations	(Opcional) Define locais (regiões) preferenciais para contas de banco de dados com replicação geográfica no serviço Azure Cosmos DB. Os valores devem ser separados por vírgulas. Por exemplo, East US,South Central US,North Europe.

Consulte a Seção de exemplo para obter exemplos completos.

Uso

Extensão 4.x e posterior

Quando a função sai com êxito, todas as alterações feitas no documento de entrada persistem automaticamente.

Functions 2.x+

Quando a função sai com êxito, todas as alterações feitas no documento de entrada persistem automaticamente.

Extensão 4.x e posterior

Quando a função sai com êxito, todas as alterações feitas no documento de entrada persistem automaticamente.

Functions 2.x+

Quando a função sai com êxito, todas as alterações feitas no documento de entrada persistem automaticamente.

Os tipos específicos com suporte pela associação de entrada do Cosmos DB dependem da versão de runtime do Functions, da versão do pacote de extensão e da modalidade de C# usada.

Extensão 4.x e posterior

Consulte Tipos de associação para obter uma lista dos tipos compatíveis.

Functions 2.x+

Consulte Tipos de associação para obter uma lista dos tipos compatíveis.

Extensão 4.x e posterior

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.

Functions 2.x+

Consulte Tipos de associação para obter uma lista dos tipos compatíveis.

Na biblioteca de runtime de funções Java, a anotação @CosmosDBInput expõe os dados do Azure Cosmos DB para a função. Essa anotação pode ser usada com tipos nativos do Java, POJOs ou valores que permitem valor nulos usando Optional<T>.

Modelo v4

Acesse o documento usando context.extraInputs.get().

Modelo v3

Acesse o documento usando context.bindings.<name>, em que <name> é o valor especificado na propriedade name de function.json.

As atualizações dos documentos não são feitas automaticamente após a saída da função. Para atualizar documentos em uma função, use uma associação de saída. Confira o exemplo do PowerShell para mais detalhes.

Os dados são disponibilizados para a função por meio de um parâmetro DocumentList. As alterações feitas no documento não são persistidas automaticamente.

conexões

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

• O nome da configuração de um aplicativo contendo uma cadeia de conexão
• O nome de um prefixo compartilhado com várias configurações de aplicativo, definindo juntas uma conexão baseada em identidade. Essa opção só está disponível para as versões connection e leaseConnection da connection.

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

Cadeia de conexão

A cadeia de conexão para sua conta do banco de dados deve ser armazenada em uma configuração de aplicativo com um nome que corresponde ao valor especificado pela propriedade da conexão da configuração de associaçã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 fazer isso, defina as configurações em um prefixo comum que mapeia para a propriedade da conexão na configuração de gatilho e de associação.

Nesse modo, a extensão exige as seguintes propriedades:

Propriedade	Modelo de variável de ambiente	Descrição	Valor de exemplo
Ponto de extremidade da conta	<CONNECTION_NAME_PREFIX>__accountEndpoint	URI do ponto de extremidade da conta do Azure Cosmos DB.	https://<nome_da_conta_do_banco_de_dados>.documents.azure.com:443/

É possível definir propriedades adicionais para personalizar a conexão. Confira Propriedades comuns para conexões baseadas em identidade.

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

Conceder permissão para a 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 será necessário atribuir uma função no Azure RBAC, usando as funções internas ou as personalizadas que fornecem essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o 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 interno do Cosmos DB que se baseia em conceitos semelhantes. Será necessário criar uma atribuição de função que forneça acesso a sua conta de banco de dados em runtime. As funções de Gerenciamento de RBAC do Azure, como a de 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 escrito por você.

Tipo de associação	Exemplo de funções internas1
Gatilho2	Colaborador de dados internos do Cosmos DB
Associação de entrada	Leitor de dados internos do Cosmos DB
Associação de saída	Colaborador de dados internos do Cosmos DB

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

² Ao usar a identidade, o Cosmos DB trata a criação de contêiner 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 a criação dos contêineres necessários para o gatilho (incluindo o contêiner de concessão) antes de configurar a função.

Próximas etapas

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