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

O enlace de entrada do Azure Cosmos DB utiliza a API do SQL para obter um ou mais documentos do Azure Cosmos DB e passa-os para o parâmetro de entrada da função. Os parâmetros de consulta ou o ID do documento podem ser determinados com base no acionador que invoca a função.

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

Nota

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

Importante

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

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

v2

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

v1

O modelo de programação Python v1 requer que você defina ligações em um arquivo function.json separado na pasta de funções. Para obter mais informações, consulte o guia do desenvolvedor do Python.

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

Exemplo

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

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

• Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
• Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte total.

Modelo de trabalhador 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 do Armazenamento do Azure. Se ainda não estiver presente no seu aplicativo de função, adicione referência aos seguintes pacotes NuGet:

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

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

• Gatilho de fila, ID de pesquisa de JSON

Os exemplos referem-se a um tipo simples ToDoItem :

[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 de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma função que recupera um único documento. A função é acionada por uma mensagem JSON na fila de armazenamento. O gatilho de fila analisa o JSON em um objeto do tipo ToDoItemLookup, que contém o ID e o valor da chave de partição a serem recuperados. Esse ID e o valor da chave de partição são usados para retornar um ToDoItem documento 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 seguintes exemplos para usar funções de biblioteca de classes C# em processo com a extensão versão 3.x:

• Gatilho de fila, ID de pesquisa de JSON
• Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta
• Gatilho HTTP, procure ID a partir de dados de rota
• Gatilho HTTP, procure ID de dados de rota, usando SqlQuery
• HTTP trigger, obter vários documentos, usando SqlQuery
• Gatilho HTTP, obtenha vários documentos, usando DocumentClient
• HTTP trigger, obter vários documentos, usando CosmosClient (extensão v4)

Os exemplos referem-se a um tipo simples ToDoItem :

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 de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é acionada por uma mensagem de fila que contém um objeto JSON. O gatilho de fila analisa o JSON em um objeto do tipo ToDoItemLookup, que contém o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento 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, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

Nota

O parâmetro HTTP query string diferencia maiúsculas 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, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento 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, procure ID de dados de rota, usando SqlQuery

O exemplo a seguir mostra uma função C# que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID a ser pesquisado. Esse ID é usado para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

O exemplo mostra como usar uma expressão de associação no SqlQuery parâmetro. Você pode passar dados de rota para o SqlQuery parâmetro conforme mostrado, mas atualmente não é possível passar valores de cadeia de caracteres de consulta.

Nota

Se você precisar consultar apenas pelo ID, é recomendável usar uma pesquisa, como os exemplos anteriores, pois consumirá menos unidades de solicitação. As operações de leitura pontual (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();
        }
    }
}

HTTP trigger, obter vários documentos, usando SqlQuery

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

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, obtenha vários documentos, usando DocumentClient

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

Nota

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();
        }
    }
}

HTTP trigger, obter vários documentos, usando CosmosClient

O exemplo a seguir mostra uma função C# que recupera uma lista de documentos. A função é acionada por uma solicitação HTTP. O código usa uma CosmosClient instância fornecida pela associação do Azure Cosmos DB, disponível na extensão versão 4.x, para ler uma lista de documentos. A CosmosClient instância também pode ser usada para 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, ID de pesquisa da cadeia de caracteres de consulta - Parâmetro String
• Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta - parâmetro POJO
• Gatilho HTTP, procure ID a partir de dados de rota
• Gatilho HTTP, procure ID de dados de rota, usando SqlQuery
• HTTP trigger, obter vários documentos de dados de rota, usando SqlQuery

Os exemplos referem-se a um tipo simples ToDoItem :

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, ID de pesquisa da cadeia de caracteres de consulta - Parâmetro String

O exemplo a seguir mostra uma função Java que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse 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 String.

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 tempo de execução de funções Java, use a @CosmosDBInput anotação em parâmetros de função cujo valor viria do Azure Cosmos DB. Essa anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando Optional<T>.

Gatilho HTTP, ID de pesquisa da 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 é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse valor de ID e chave de partição usado para recuperar um documento do banco de dados e da coleção especificados. O documento é então convertido em uma instância do ToDoItem POJO criado anteriormente e passado 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, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função Java que recupera um único documento. A função é acionada por uma solicitação HTTP que usa um parâmetro route para especificar o ID e o valor da chave de partição a serem pesquisados. Esse 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>arquivo .

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, procure ID de dados de rota, usando SqlQuery

O exemplo a seguir mostra uma função Java que recupera um único documento. A função é acionada por uma solicitação HTTP que usa um parâmetro route para especificar o ID a ser pesquisado. Esse ID é usado para recuperar um documento do banco de dados e da coleção especificados, convertendo o conjunto de resultados em um ToDoItem[], já que muitos documentos podem ser retornados, dependendo dos critérios de consulta.

Nota

Se você precisar consultar apenas pelo ID, é recomendável usar uma pesquisa, como os exemplos anteriores, pois consumirá menos unidades de solicitação. As operações de leitura pontual (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();
        }
    }
}

HTTP trigger, obter vários documentos de dados de rota, usando SqlQuery

O exemplo a seguir mostra uma função Java que recupera vários documentos. A função é acionada por uma solicitação HTTP que usa um parâmetro desc route para especificar a cadeia de caracteres a ser pesquisada description no campo. O termo de pesquisa é usado para recuperar uma coleção de documentos do banco de dados e da coleção especificados, convertendo o conjunto de resultados em 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 único documento especificando um valor de ID de várias fontes:

• Gatilho de fila, ID de pesquisa de JSON
• Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta
• Gatilho HTTP, procure ID a partir de dados de rota
• Gatilho de fila, obter vários documentos, usando SqlQuery

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma função TypeScript que lê um único 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

Os exemplos de TypeScript não estão documentados para o modelo v3.

Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função TypeScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento 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

Os exemplos de TypeScript não estão documentados para o modelo v3.

Gatilho HTTP, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função TypeScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento 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

Os exemplos de TypeScript não estão documentados para o modelo v3.

Gatilho de 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 fila fornece um parâmetro departmentId. Uma mensagem de fila de { "departmentId" : "Finance" } retornaria todos os registros para o 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

Os exemplos de TypeScript não estão documentados para o modelo v3.

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

• Gatilho de fila, ID de pesquisa de JSON
• Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta
• Gatilho HTTP, procure ID a partir de dados de rota
• Gatilho de fila, obter vários documentos, usando SqlQuery

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma função JavaScript que lê um único 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 ligaçã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 de 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, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função JavaScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento 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, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função JavaScript que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento 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 de 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 fila fornece um parâmetro departmentId. Uma mensagem de fila de { "departmentId" : "Finance" } retornaria todos os registros para o 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 ligaçã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 de 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 de fila, ID de pesquisa de JSON
• Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta
• Gatilho HTTP, procure ID a partir de dados de rota
• Gatilho de fila, obter vários documentos, usando SqlQuery

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir demonstra como ler e atualizar um único documento do Azure Cosmos DB. O identificador exclusivo do documento é fornecido por meio do valor JSON em uma mensagem de 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, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir demonstra como ler e atualizar um único documento do Azure Cosmos DB a partir 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 da "Id": "{Query.Id}" ligaçã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, procure ID a partir de dados de rota

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

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 de 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 ligação, que incluem o sqlQueryarquivo . A instrução SQL fornecida à sqlQuery propriedade 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 único documento especificando um valor de ID de várias fontes:

• Gatilho de fila, ID de pesquisa de JSON
• Gatilho HTTP, ID de pesquisa da cadeia de caracteres de consulta
• Gatilho HTTP, procure ID a partir de dados de rota
• Gatilho de fila, obter vários documentos, usando SqlQuery

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

Gatilho de fila, ID de pesquisa de JSON

O exemplo a seguir mostra uma associação de entrada do Azure Cosmos DB. A função lê um único documento 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 ligaçã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 de 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, ID de pesquisa da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função que recupera um único documento. A função é acionada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

v2

Nenhuma amostra equivalente para 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, procure ID a partir de dados de rota

O exemplo a seguir mostra uma função que recupera um único documento. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o ID e o valor da chave de partição a serem pesquisados. Esse ID e o valor da chave de partição são usados para recuperar um ToDoItem documento do banco de dados e da coleção especificados.

v2

Nenhuma amostra equivalente para 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 de fila, obter vários documentos, usando SqlQuery

O exemplo a seguir mostra uma função Python de vinculação de entrada do Azure Cosmos DB que usa a ligaçã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 fila fornece um parâmetro departmentId. Uma mensagem de fila de { "departmentId" : "Finance" } retornaria todos os registros para o departamento financeiro.

v2

Nenhuma amostra equivalente para v2 no momento.

v1

Aqui estão os dados de ligaçã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# do processo de trabalho em processo e isoladas usam atributos para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Extensão 4.x+

Propriedade Attribute	Description
Ligação	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo consultada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
Nome do contêiner	O nome do contêiner que está sendo monitorado.
PartitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de vinculação. É necessário para pesquisas em contêineres particionados .
ID	A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
SqlQuery	Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

Funções 2.x+

Propriedade Attribute	Description
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 monitorada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com a coleção 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 vinculação. É necessário para pesquisas em coleções particionadas .
ID	A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, toda a coleção será recuperada.
SqlQuery	Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, toda a coleção será recuperada.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Extensão 4.x+

Propriedade Attribute	Description
Ligação	O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar à conta do Azure Cosmos DB que está sendo consultada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
Nome do contêiner	O nome do contêiner que está sendo monitorado.
PartitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de vinculação. É necessário para pesquisas em contêineres particionados .
ID	A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
SqlQuery	Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

Funções 2.x+

Propriedade Attribute	Description
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 monitorada. Para obter mais informações, consulte Conexões.
Nome do Banco de Dados	O nome do banco de dados do Azure Cosmos DB com a coleção 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 vinculação. É necessário para pesquisas em coleções particionadas .
ID	A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, toda a coleção será recuperada.
SqlQuery	Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as Id propriedades e SqlQuery . Se você não definir nenhum deles, toda a coleção será recuperada.
Locais preferidos	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, "Leste dos EUA, Centro-Sul dos EUA, Norte da Europa".

Decoradores

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

As funções Python v2 são definidas usando o cosmos_db_input decorador, que suporta estas propriedades, dependendo da versão da extensão:

Extensão 4.x+

Property	Description
arg_name	O nome da variável usada no código da função que representa a lista de documentos com alterações.
database_name	O nome do banco de dados do Azure Cosmos DB com a coleção sendo monitorada.
container_name	O nome da coleção do Azure Cosmos DB que está sendo monitorada.
connection	A cadeia de conexão do Azure Cosmos DB que está 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.

Funções 2.x+

Property	Description
arg_name	O nome da variável usada no código da função que representa a lista de documentos com alterações.
database_name	O nome do banco de dados do Azure Cosmos DB com a coleção sendo monitorada.
collection_name	O nome da coleção do Azure Cosmos DB que está sendo monitorada.
connection_string_setting	A cadeia de conexão do Azure Cosmos DB que está 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 Python definidas usando function.json, consulte a seção Configuração .

Anotações

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

• Designação
• connectionStringSetting
• Nome do banco de dados
• collectionName
• Tipo de dados
• id
• partitionKey
• sqlQuery

Configuração

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

Modelo v4

A tabela a seguir explica as propriedades que você pode definir no options objeto passado para o input.cosmosDB() método. As typepropriedades , 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 definidas no arquivo function.json, onde as propriedades diferem de acordo com a versão da extensão:

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

Extensão 4.x+

function.json propriedade	Description
type	Deve ser definido como cosmosDB.
direção	Deve ser definido como in.
Designação	O nome da variável usada no código da função que representa a lista de documentos com alterações.
conexão	O nome de uma configuração de aplicativo ou contêiner de configuração que especifica como se conectar à conta do Azure Cosmos DB que está sendo monitorada. Para obter mais informações, consulte Conexões.
Nome do banco de dados	O nome do banco de dados do Azure Cosmos DB com o contêiner sendo monitorado.
containerName	O nome do contêiner que está sendo monitorado.
partitionKey	Especifica o valor da chave de partição para a pesquisa. Pode incluir parâmetros de vinculação. É necessário para pesquisas em contêineres particionados .
id	A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as id propriedades e sqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
sqlQuery	Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as id propriedades e sqlQuery . Se você não definir nenhum deles, todo o contêiner será recuperado.
preferredLocations	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

Funções 2.x+

function.json propriedade	Description
type	Deve ser definido como cosmosDBTrigger.
direção	Deve ser definido como in.
Designação	O nome da variável usada no código da 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 monitorada. Para obter mais informações, consulte Conexões.
Nome do banco de dados	O nome do banco de dados do Azure Cosmos DB com a coleção 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 vinculação. É necessário para pesquisas em coleções particionadas .
id	A ID do documento a ser recuperado. Esta propriedade suporta expressões de ligação. Não defina as id propriedades e sqlQuery . Se você não definir nenhum deles, toda a coleção será recuperada.
sqlQuery	Uma consulta SQL do Azure Cosmos DB usada para recuperar vários documentos. A propriedade suporta associações de tempo de execução, como neste exemplo: SELECT * FROM c where c.departmentId = {departmentId}. Não defina as id propriedades e sqlQuery . Se você não definir nenhum deles, toda a coleção será recuperada.
preferredLocations	(Opcional) Define locais preferenciais (regiões) para contas de banco de dados replicadas geograficamente no serviço Azure Cosmos DB. Os valores devem ser separados por vírgula. Por exemplo, East US,South Central US,North Europe.

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

Utilização

Extensão 4.x+

Quando a função é encerrada com êxito, todas as alterações feitas no documento de entrada são automaticamente persistidas.

Funções 2.x+

Quando a função é encerrada com êxito, todas as alterações feitas no documento de entrada são automaticamente persistidas.

Extensão 4.x+

Quando a função é encerrada com êxito, todas as alterações feitas no documento de entrada são automaticamente persistidas.

Funções 2.x+

Quando a função é encerrada com êxito, todas as alterações feitas no documento de entrada são automaticamente persistidas.

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

Extensão 4.x+

Consulte Tipos de vinculação para obter uma lista de tipos suportados.

Funções 2.x+

Consulte Tipos de vinculação para obter uma lista de tipos suportados.

Extensão 4.x+

Quando você deseja que a função processe um único documento, a associação de entrada do Cosmos DB pode se vincular aos seguintes tipos:

Tipo	Description
Tipos serializáveis JSON	As funções tentam desserializar os dados JSON do documento em um tipo de objeto CLR antigo (POCO).

Quando você deseja que a função processe vários documentos de uma consulta, a associação de entrada do Cosmos DB pode se vincular aos seguintes tipos:

Tipo	Description
IEnumerable<T>onde T é um tipo serializável JSON	Uma enumeração de entidades retornadas pela consulta. Cada entrada representa um documento.
CosmosClient1	Um cliente conectado à conta do Cosmos DB.
Base de dados1	Um cliente conectado ao banco de dados do Cosmos DB.
Contentor1	Um cliente conectado ao contêiner do Cosmos DB.

1 Para usar esses tipos, você precisa fazer referência a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 ou posterior e às dependências comuns para associações de tipo SDK.

Funções 2.x+

Consulte Tipos de vinculação para obter uma lista de tipos suportados.

Na biblioteca de tempo de execução de funções Java, a anotação @CosmosDBInput expõe os dados do Azure Cosmos DB à função. Essa anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando Optional<T>.

Modelo v4

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

Modelo v3

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

As atualizações de 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. Consulte o exemplo do PowerShell para obter mais detalhes.

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

Ligações

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

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

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

Connection string

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

Conexões baseadas em identidade

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

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

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

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

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

Conceder permissão à identidade

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

Importante

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

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

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

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

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

Próximos passos

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