Входная привязка Azure Cosmos DB для Функций Azure 2.x и более поздних версий

Входная привязка Azure Cosmos DB извлекает один или несколько документов из Azure Cosmos DB и передает их входному параметру функции через API SQL. Идентификатор документа или параметры запроса можно определить по триггеру, который вызывает функцию.

Сведения об установке и настройке см. в обзорной статье.

Примечание.

Если коллекция секционирована, операции поиска должны также указывать значение ключа раздела.

Внимание

В этой статье используются вкладки для поддержки нескольких версий модели программирования Node.js. Модель версии 4 общедоступна и предназначена для более гибкого и интуитивно понятного интерфейса для разработчиков JavaScript и TypeScript. Дополнительные сведения о том, как работает модель версии 4, см. в руководстве разработчика по Функции Azure Node.js. Дополнительные сведения о различиях между версиями 3 и 4 см. в руководстве по миграции.

Функции Azure поддерживает две модели программирования для Python. Способ определения привязок зависит от выбранной модели программирования.

версия 2

Модель программирования Python версии 2 позволяет определять привязки с помощью декораторов непосредственно в коде функции Python. Дополнительные сведения см. в руководстве разработчика Python.

версия 1

Модель программирования Python версии 1 требует определения привязок в отдельном файле function.json в папке функции. Дополнительные сведения см. в руководстве разработчика Python.

Эта статья поддерживает обе модели программирования.

Пример

Если не указано иное, примеры в этой статье предназначены для расширения Azure Cosmos DB версии 3.x. Для использования с расширением версии 4.x необходимо изменить строку collection в именах свойств и атрибутов на container.

Функцию C# можно создать с помощью одного из следующих режимов C#:

• Изолированная рабочая модель: скомпилированная функция C#, которая выполняется в рабочем процессе, изолированном от среды выполнения. Изолированный рабочий процесс необходим для поддержки функций C#, работающих в LTS и не LTS-версиях .NET и платформа .NET Framework. Расширения для изолированных рабочих процессов используют Microsoft.Azure.Functions.Worker.Extensions.* пространства имен.
• Модель внутрипроцессного процесса: скомпилированная функция C#, которая выполняется в том же процессе, что и среда выполнения Функций. В варианте этой модели функции можно запускать с помощью скриптов C#, которая поддерживается главным образом для редактирования портала C#. Расширения для функций в процессе используют Microsoft.Azure.WebJobs.Extensions.* пространства имен.

Внимание

Поддержка будет завершена для модели в процессе 10 ноября 2026 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.

Изолированная рабочая модель

В этом разделе приведены примеры, для которых требуется расширение Azure Cosmos DB версии 3.x и расширение служба хранилища Azure версии 5.x. Если ее еще нет в вашем приложении-функции, добавьте ссылку на следующие пакеты NuGet:

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

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

• Триггер очереди, поисковый идентификатор из JSON

В примерах используется 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}");
    }
}

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана функция, которая получает один документ. Функция активируется сообщением JSON в очереди хранилища. Триггер очереди анализирует JSON в объект типа ToDoItemLookup, который содержит идентификатор и значение ключа раздела для получения. Эти идентификатор и значение ключа раздела используются для получения документа 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}");
    }
}

Модель внутрипроцессного процесса

Этот раздел содержит следующие примеры использования внутрипроцессных функций библиотеки классов C# с расширением версии 3.x:

• Триггер очереди, поисковый идентификатор из JSON
• Триггер HTTP, поисковый идентификатор из строки запроса
• Триггер HTTP, поисковый идентификатор из данных маршрута
• Триггер HTTP, поисковый идентификатор из данных маршрута, используется SqlQuery
• Триггер HTTP, получение нескольких документов, используется SqlQuery
• Триггер HTTP, получение нескольких документов, используется DocumentClient
• триггер HTTP, получение нескольких документов, использование CosmosClient (расширение версии 4).

В примерах используется 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; }
    }
}

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана функция C#, которая получает один документ. Функция активируется сообщением из очереди, который содержит объект JSON. Триггер очереди анализирует JSON в объект типа ToDoItemLookup, который содержит идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

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

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показана функция C#, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

Примечание.

Параметры строки запроса HTTP задаются с учетом регистра.

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

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция C#, которая получает один документ. Функция активируется HTTP-запросом, который использует данные маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

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

Триггер HTTP, поисковый идентификатор из данных маршрута, используется SqlQuery

В следующем примере показана функция C#, которая получает один документ. Функция инициируется HTTP-запросом, в котором с помощью данных маршрута указывается идентификатор для поиска. Этот идентификатор используется для получения ToDoItem документа из указанной базы данных и коллекции.

В примере показано, как использовать выражение привязки в параметре SqlQuery. Вы можете передать данные маршрута в параметр SqlQuery, как показано здесь, но сейчас невозможно передать значения строки запроса.

Примечание.

Если необходимо выполнить запрос только по идентификатору, рекомендуется использовать поиск, как в предыдущих примерах, так как будет потребляться меньше единиц запроса. Операции чтения точки (GET) более эффективны, чем запросы по идентификатору.

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, получение нескольких документов, используется SqlQuery

В следующем примере показана функция C#, которая получает список документов. Функция активируется с помощью HTTP-запроса. Запрос указывается в свойстве атрибута 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();
        }
    }
}

Триггер HTTP, получение нескольких документов, используется DocumentClient

В следующем примере показана функция C#, которая получает список документов. Функция активируется с помощью HTTP-запроса. Код использует экземпляр DocumentClient, предоставленный привязкой Azure Cosmos DB для считывания списка документов. Экземпляр DocumentClient может также использоваться для операций записи.

Примечание.

Вы также можете использовать интерфейс IDocumentClient для упрощения тестирования.

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, получение нескольких документов, использование CosmosClient

В следующем примере показана функция C#, которая получает список документов. Функция активируется с помощью HTTP-запроса. Код использует экземпляр CosmosClient, предоставленный привязкой Azure Cosmos DB, которая доступна в расширении версии 4.x для считывания списка документов. Экземпляр CosmosClient может также использоваться для операций записи.

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

Этот раздел содержит следующие примеры.

• Триггер HTTP, поисковый идентификатор из строки запроса — строковый параметр
• Триггер HTTP, поисковый идентификатор из строки запроса — параметр POJO
• Триггер HTTP, поисковый идентификатор из данных маршрута
• Триггер HTTP, поисковый идентификатор из данных маршрута, используется SqlQuery
• Триггер HTTP, получение нескольких документов из данных маршрута, используется SqlQuery

В примерах используется 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 + "}";
  }
}

Триггер HTTP, поисковый идентификатор из строки запроса — строковый параметр

В следующем примере показана функция Java, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа из указанной базы данных и коллекции в формате 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();
        }
    }
}

В библиотеке среды выполнения функций Java используйте заметку @CosmosDBInput для параметров функции, значение которых будет поступать из Azure Cosmos DB. Эта заметка может использоваться с собственными типами Java, объектами POJO или значениями, допускающими значения NULL, используя Optional<T>.

Триггер HTTP, поисковый идентификатор из строки запроса — параметр POJO

В следующем примере показана функция Java, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела использовались для получения документа из указанной базы данных и коллекции. Затем документ преобразуется в ранее созданный экземпляр POJO ToDoItem и передается функции в качестве аргумента.

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

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция Java, которая получает один документ. Функция активируется HTTP-запросом, который использует параметр маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа из указанной базы данных и коллекции, возвращая его как 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();
        }
    }
}

Триггер HTTP, поисковый идентификатор из данных маршрута, используется SqlQuery

В следующем примере показана функция Java, которая получает один документ. Функция инициируется HTTP-запросом, в параметре маршрута которого указан идентификатор для поиска. Этот идентификатор используется для получения документа из указанной базы данных и коллекции. При этом результирующий набор преобразуется в ToDoItem[], так как может быть возвращено несколько документов в зависимости от критериев запроса.

Примечание.

Если необходимо выполнить запрос только по идентификатору, рекомендуется использовать поиск, как в предыдущих примерах, так как будет потребляться меньше единиц запроса. Операции чтения точки (GET) более эффективны, чем запросы по идентификатору.

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, получение нескольких документов из данных маршрута, используется SqlQuery

В следующем примере показана функция Java, которая извлекает один документ. Эта функция инициируется HTTP-запросом, в параметре маршрута desc которого указана строка для поиска в поле description. Поисковый запрос используется для получения коллекции документов из указанной базы данных и коллекции. При этом результирующий набор преобразуется в ToDoItem[] и передается функции в качестве аргумента.

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

В этом разделе содержатся следующие примеры, в которых один документ считывается при указании значения идентификатора из разных источников:

• Триггер очереди, поисковый идентификатор из JSON
• Триггер HTTP, поисковый идентификатор из строки запроса
• Триггер HTTP, поисковый идентификатор из данных маршрута
• Триггер очереди, получение нескольких документов, используется SqlQuery

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана функция TypeScript, которая считывает один документ и обновляет текстовое значение документа.

Модель версии 4

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

Модель версии 3

Примеры TypeScript не документируются для модели версии 3.

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показана функция TypeScript, извлекающая один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

Модель версии 4

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

Модель версии 3

Примеры TypeScript не документируются для модели версии 3.

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция TypeScript, извлекающая один документ. Функция активируется HTTP-запросом, который использует данные маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

Модель версии 4

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

Модель версии 3

Примеры TypeScript не документируются для модели версии 3.

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показана функция TypeScript, которая извлекает несколько документов, указанных sql-запросом, с помощью триггера очереди для настройки параметров запроса.

Триггер очереди предоставляет параметр departmentId. Сообщение из очереди { "departmentId" : "Finance" } возвратит все записи для финансового отдела.

Модель версии 4

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

Модель версии 3

Примеры TypeScript не документируются для модели версии 3.

В этом разделе содержатся следующие примеры, в которых один документ считывается при указании значения идентификатора из разных источников:

• Триггер очереди, поисковый идентификатор из JSON
• Триггер HTTP, поисковый идентификатор из строки запроса
• Триггер HTTP, поисковый идентификатор из данных маршрута
• Триггер очереди, получение нескольких документов, используется SqlQuery

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана функция JavaScript, которая считывает один документ и обновляет текстовое значение документа.

Модель версии 4

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

Модель версии 3

Данные привязки в файле 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"
}

В разделе Конфигурация описываются эти свойства.

Ниже показан код 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!";
    };

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показана функция JavaScript, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

Модель версии 4

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}`,
            };
        }
    },
});

Модель версии 3

Ниже показан файл 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
}

Ниже показан код 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);
    }
};

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция JavaScript, которая получает один документ. Функция активируется HTTP-запросом, который использует данные маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

Модель версии 4

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}`,
            };
        }
    },
});

Модель версии 3

Ниже показан файл 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
}

Ниже показан код 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);
    }
};

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показана функция JavaScript, которая извлекает несколько документов, указанных sql-запросом, с помощью триггера очереди для настройки параметров запроса.

Триггер очереди предоставляет параметр departmentId. Сообщение из очереди { "departmentId" : "Finance" } возвратит все записи для финансового отдела.

Модель версии 4

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

Модель версии 3

Данные привязки в файле function.json:

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

В разделе Конфигурация описываются эти свойства.

Ниже показан код JavaScript.

module.exports = async function (context, input) {
  var documents = context.bindings.documents;
  for (const document of documents) {
    // operate on each document
  }
};

• Триггер очереди, поисковый идентификатор из JSON
• Триггер HTTP, поисковый идентификатор из строки запроса
• Триггер HTTP, поисковый идентификатор из данных маршрута
• Триггер очереди, получение нескольких документов, используется SqlQuery

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показано, как считывать и обновлять один документ Azure Cosmos DB. Уникальный идентификатор документа предоставляется через значение JSON в сообщении очереди.

Входная привязка Azure Cosmos DB сначала отображается в списке привязок, найденных в файле конфигурации функции (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"
}

Файл run.ps1 содержит код PowerShell, который считывает входящий документ и выводит изменения.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document  

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показано, как считывать и обновлять один документ Azure Cosmos DB из веб-API. Уникальный идентификатор документа предоставляется через параметр QueryString в HTTP-запросе, как определено в свойстве "Id": "{Query.Id}" привязки.

Входная привязка Azure Cosmos DB сначала отображается в списке привязок, найденных в файле конфигурации функции (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 
} 

Файл run.ps1 содержит код PowerShell, который считывает входящий документ и выводит изменения.

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

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показано, как считывать и обновлять один документ Azure Cosmos DB из веб-API. Уникальный идентификатор документа предоставляется с помощью параметра маршрута. Параметр маршрута определен в свойстве привязки HTTP-запроса и указан в свойстве привязки route Azure Cosmos DB "Id": "{Id}" .

Входная привязка Azure Cosmos DB сначала отображается в списке привязок, найденных в файле конфигурации функции (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 
} 

Файл run.ps1 содержит код PowerShell, который считывает входящий документ и выводит изменения.

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

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показано, как считывать несколько документов Azure Cosmos DB. Файл конфигурации функции (function.json) определяет свойства привязки, включающие sqlQuery. Инструкция SQL, предоставляемая в свойство sqlQuery, выбирает набор документов, предоставленных в функцию.

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

Файл run1.ps1 содержит код PowerShell, который считывает входящие документы.

param($QueueItem, $Documents, $TriggerMetadata)

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

В этом разделе содержатся следующие примеры, в которых один документ считывается при указании значения идентификатора из разных источников:

• Триггер очереди, поисковый идентификатор из JSON
• Триггер HTTP, поисковый идентификатор из строки запроса
• Триггер HTTP, поисковый идентификатор из данных маршрута
• Триггер очереди, получение нескольких документов, используется SqlQuery

Примеры зависят от того, используется ли модель программирования Python версии 1 или версии 2.

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана входная привязка Azure Cosmos DB. Функция считывает один документ и обновляет текстовое значение в документе.

версия 2

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

версия 1

Данные привязки в файле 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"
}

В разделе Конфигурация описываются эти свойства.

Ниже приведен код 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

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показана функция, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

версия 2

В настоящее время нет эквивалентного примера для версии 2.

версия 1

Ниже показан файл 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"
}

Ниже приведен код 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'

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция, которая получает один документ. Функция активируется HTTP-запросом, который использует данные маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

версия 2

В настоящее время нет эквивалентного примера для версии 2.

версия 1

Ниже показан файл 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"
}

Ниже приведен код 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'

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показана функция входной привязки Python Для Azure Cosmos DB, которая использует привязку. Функция извлекает несколько документов, указанных SQL-запросом, используя триггер очереди для настройки параметров запроса.

Триггер очереди предоставляет параметр departmentId. Сообщение из очереди { "departmentId" : "Finance" } возвратит все записи для финансового отдела.

версия 2

В настоящее время нет эквивалентного примера для версии 2.

версия 1

Данные привязки в файле function.json:

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

Атрибуты

Библиотеки C# в процессе и изолированном рабочем процессе используют атрибуты для определения функции. Вместо этого скрипт C# использует файл конфигурации function.json, как описано в руководстве по скриптам C#.

Расширение 4.x+

Свойство атрибута	Description
Соединение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к учетной записи Azure Cosmos DB, к которой отправляются запросы. Дополнительные сведения см. в разделе Соединения.
DatabaseName	Имя базы данных Azure Cosmos DB с отслеживаемым контейнером.
Имя контейнера	Имя отслеживаемого контейнера.
PartitionKey	Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных контейнерах.
Id	Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
SqlQuery	SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
PreferredLocations	(Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

Функции 2.x+

Свойство атрибута	Description
ConnectionStringSetting	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
DatabaseName	Имя базы данных Azure Cosmos DB с отслеживаемой коллекцией.
CollectionName	Имя отслеживаемой коллекции.
PartitionKey	Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных коллекциях.
Id	Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается вся коллекция.
SqlQuery	SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается вся коллекция.
PreferredLocations	(Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, "Восточная часть США,Центрально-южная часть США,Северная Европа".

Расширение 4.x+

Свойство атрибута	Description
Соединение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к учетной записи Azure Cosmos DB, к которой отправляются запросы. Дополнительные сведения см. в разделе Соединения.
DatabaseName	Имя базы данных Azure Cosmos DB с отслеживаемым контейнером.
Имя контейнера	Имя отслеживаемого контейнера.
PartitionKey	Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных контейнерах.
Id	Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
SqlQuery	SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
PreferredLocations	(Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

Функции 2.x+

Свойство атрибута	Description
ConnectionStringSetting	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
DatabaseName	Имя базы данных Azure Cosmos DB с отслеживаемой коллекцией.
CollectionName	Имя отслеживаемой коллекции.
PartitionKey	Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных коллекциях.
Id	Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается вся коллекция.
SqlQuery	SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается вся коллекция.
PreferredLocations	(Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, "Восточная часть США,Центрально-южная часть США,Северная Европа".

Декораторы

Применяется только к модели программирования Python версии 2.

Функции Python версии 2 определяются с помощью cosmos_db_input декоратора, который поддерживает эти свойства в зависимости от версии расширения:

Расширение 4.x+

Свойство	Description
arg_name	Имя переменной, используемое в коде функции, представляющей список документов с изменениями.
database_name	Имя базы данных Azure Cosmos DB с отслеживаемой коллекцией.
container_name	Имя отслеживаемой коллекции Azure Cosmos DB.
connection	Строка подключения отслеживаемой базы данных Azure Cosmos DB.
partition_key	Ключ секции отслеживаемой базы данных Azure Cosmos DB.
id	Идентификатор документа, который нужно получить.

Функции 2.x+

Свойство	Description
arg_name	Имя переменной, используемое в коде функции, представляющей список документов с изменениями.
database_name	Имя базы данных Azure Cosmos DB с отслеживаемой коллекцией.
collection_name	Имя отслеживаемой коллекции Azure Cosmos DB.
connection_string_setting	Строка подключения отслеживаемой базы данных Azure Cosmos DB.
partition_key	Ключ секции отслеживаемой базы данных Azure Cosmos DB.
id	Идентификатор документа, который нужно получить.

Сведения о функциях Python, определенных с помощью function.json, см. в разделе "Конфигурация ".

Заметки

Используйте заметку @CosmosDBInput из библиотеки среды выполнения функций Java для параметров, которые будут выполнять считывание из Azure Cosmos DB. Эта заметка поддерживает следующие свойства:

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

Настройка

Применяется только к модели программирования Python версии 1.

Модель версии 4

В следующей таблице описываются свойства, которые можно задать для options объекта, переданного методу input.cosmosDB() . directionСвойства typeи name свойства не применяются к модели версии 4.

Модель версии 3

В следующей таблице описаны свойства конфигурации привязки, задаваемые в файле function.json, свойства в котором различаются по версии расширения:

В следующей таблице описаны свойства конфигурации привязки, задаваемые в файле function.json, свойства в котором различаются по версии расширения:

Расширение 4.x+

Свойство в function.json	Описание
type	Должен иметь значениеcosmosDB.
direction	Должен иметь значениеin.
name	Имя переменной, используемое в коде функции, представляющей список документов с изменениями.
Подключение	Имя параметра или контейнера параметров приложения, указывающих, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
databaseName	Имя базы данных Azure Cosmos DB с отслеживаемым контейнером.
containerName	Имя отслеживаемого контейнера.
partitionKey	Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных контейнерах.
id	Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства id и sqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
sqlQuery	SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства id и sqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
preferredLocations	(Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

Функции 2.x+

Свойство в function.json	Описание
type	Должен иметь значениеcosmosDBTrigger.
direction	Должен иметь значениеin.
name	Имя переменной, используемое в коде функции, представляющей список документов с изменениями.
connectionStringSetting	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
databaseName	Имя базы данных Azure Cosmos DB с отслеживаемой коллекцией.
collectionName	Имя отслеживаемой коллекции.
partitionKey	Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных коллекциях.
id	Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства id и sqlQuery одновременно. Если не задать ни одного из них, извлекается вся коллекция.
sqlQuery	SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства id и sqlQuery одновременно. Если не задать ни одного из них, извлекается вся коллекция.
preferredLocations	(Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

Подробные примеры см. в разделе Примеры.

Использование

Расширение 4.x+

Любые изменения, внесенные во входной документ, сохраняются автоматически после успешного выхода из функции.

Функции 2.x+

Любые изменения, внесенные во входной документ, сохраняются автоматически после успешного выхода из функции.

Расширение 4.x+

Любые изменения, внесенные во входной документ, сохраняются автоматически после успешного выхода из функции.

Функции 2.x+

Любые изменения, внесенные во входной документ, сохраняются автоматически после успешного выхода из функции.

Тип параметра, поддерживаемый входной привязкой Cosmos DB, зависит от версии среды выполнения Функций, версии пакета расширения и используемой модальности C#.

Расширение 4.x+

Список поддерживаемых типов см. в разделе "Типы привязки".

Функции 2.x+

Список поддерживаемых типов см. в разделе "Типы привязки".

Расширение 4.x+

Если требуется, чтобы функция обрабатывала один документ, входная привязка Cosmos DB может привязаться к следующим типам:

Тип	Описание
Сериализуемые в JSON типы	Функции пытаются десериализировать данные JSON документа в обычный тип объекта CLR (POCO).

Если требуется, чтобы функция обрабатывала несколько документов из запроса, входная привязка Cosmos DB может привязаться к следующим типам:

Тип	Описание
IEnumerable<T>где T является сериализуемым типом JSON	Перечисление сущностей, возвращаемых запросом. Каждая запись представляет один документ.
CosmosClient1	Клиент, подключенный к учетной записи Cosmos DB.
База данных1	Клиент, подключенный к базе данных Cosmos DB.
Контейнер1	Клиент, подключенный к контейнеру Cosmos DB.

¹ Для использования этих типов необходимо ссылаться на Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 или более поздней версии , а также общие зависимости для привязок типов SDK.

Функции 2.x+

Список поддерживаемых типов см. в разделе "Типы привязки".

Из библиотеки среды выполнения функций Java заметка @CosmosDBInput предоставляет данные Azure Cosmos DB функции. Эта заметка может использоваться с собственными типами Java, объектами POJO или значениями, допускающими значения NULL, используя Optional<T>.

Модель версии 4

Доступ к документу с помощью context.extraInputs.get().

Модель версии 3

Доступ к документу с помощью context.bindings.<name> <name> значения, указанного в свойстве name function.json.

При выходе функции не происходит автоматического обновления документов. Для обновления документов в функции используйте выходную привязку. Дополнительные сведения см. в примере PowerShell.

Данные становятся доступными для функции через параметр DocumentList. Изменения, вносимые в документ, не сохраняются автоматически.

Связи

Свойства connectionStringSetting/connection и leaseConnectionStringSetting/leaseConnection являются ссылками на конфигурацию среды, которая указывает, как приложение должно подключаться к Azure Cosmos DB. В них может быть указано следующее:

• Имя параметра приложения, содержащего строку подключения.
• Имя общего префикса для нескольких параметров приложения, а также определение подключения на основе удостоверений. Этот параметр доступен только для версий connection и leaseConnection из версии расширения 4.x или выше.

Если настроенное значение одновременно точно соответствует одному параметру и является префиксом для других параметров, то используется точное совпадение.

Connection string

Строка подключения для учетной записи базы данных должна храниться в параметре приложения с именем, соответствующим значению, которое указано свойством подключения конфигурации привязки.

Подключения на основе удостоверений

Если вы используете расширение версии 4.x или более поздней версии, вместо использования строка подключения с секретом, приложение может использовать удостоверение Microsoft Entra. Для этого необходимо определить параметры с общим префиксом, который соответствует свойству подключения в конфигурации триггера и привязки.

В этом режиме для расширения требуются следующие свойства:

Свойство	Шаблон переменной среды	Description	Пример значения
Конечная точка учетной записи	<CONNECTION_NAME_PREFIX>__accountEndpoint	URI конечной точки учетной записи Azure Cosmos DB.	https://<database_account_name>.documents.azure.com:443/

Для настройки подключения можно задать дополнительные свойства. См. раздел Общие свойства подключений на основе удостоверений.

При размещении в службе "Функции Azure" для подключений на основе удостоверений используется управляемое удостоверение. По умолчанию используется назначаемое системой удостоверение, однако вы можете указать назначаемое пользователем удостоверение с помощью свойств credential и clientID. Обратите внимание, что настройка назначаемого пользователем удостоверения с идентификатором ресурса не поддерживается. При выполнении в других контекстах, например при локальной разработке, вместо этого используется удостоверение разработчика, хотя это можно настроить. См. раздел Локальная разработка с использованием подключений на основе удостоверений.

Предоставление разрешения удостоверению

Любое используемое удостоверение должно иметь разрешения на выполнение предполагаемых действий. Для большинства служб Azure это означает, что необходимо назначить роль в Azure RBAC, используя встроенные или настраиваемые роли, которые предоставляют эти разрешения.

Внимание

Иногда целевая служба может предоставлять разрешения, которые не являются обязательными для всех контекстов. Там, где это возможно, придерживайтесь принципа минимальных привилегий, предоставляя удостоверению лишь самые необходимые привилегии. Например, если приложению требуется только возможность чтения из источника данных, используйте роль, которая имеет разрешение только на чтение. Было бы неуместным назначить роль, которая также разрешает запись в эту службу, так как это разрешение не требуется для операции чтения. Соответственно необходимо еще проверить, что область действия назначенной роли ограничена только теми ресурсами, которые необходимо прочитать.

Cosmos DB не использует Azure RBAC для операций с данными. Вместо этого она использует встроенную систему RBAC Cosmos DB, созданную на основе аналогичных концепций. Вам потребуется создать назначение ролей, которое предоставляет доступ к учетной записи базы данных во время выполнения. Роли управления Azure RBAC, такие как владелец , недостаточно. В следующей таблице показаны встроенные роли, которые рекомендуется использовать при использовании расширения Azure Cosmos DB в обычной работе. Приложению могут потребоваться дополнительные разрешения в зависимости от написанного кода.

Тип привязки	Пример встроенных ролей1
Триггер2	Встроенный участник данных Cosmos DB
Входные привязки	Встроенное средство чтения данных Cosmos DB
Выходные привязки	Встроенный участник данных Cosmos DB

¹ Эти роли нельзя использовать в назначении ролей RBAC Azure. Дополнительные сведения о назначении этих ролей см. в встроенной системной документации по RBAC Cosmos DB.

² При использовании удостоверения Cosmos DB обрабатывает создание контейнера как операцию управления. Он недоступен в качестве операции плоскости данных для триггера. Перед настройкой функции необходимо создать контейнеры, необходимые триггеру (включая контейнер аренды).

Следующие шаги

• Выполнение функции при создании или изменении документа Azure Cosmos DB (триггер)
• Сохранение изменений в документе Azure Cosmos DB (выходная привязка)