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. Способ определения привязок зависит от выбранной модели программирования.

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

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

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

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

Внимание

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

Пример

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

Следующий код определяет тип MyDocument:

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

    public string? Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

В следующем примере тип возвращаемого значения — IReadOnlyList<T> и является списком документов из параметра привязки триггера:

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

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

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

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

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

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

Триггер очереди, сохранение сообщения в базе данных через возвращаемое значение

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

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

Триггер HTTP, сохранение одного документа в базе данных через возвращаемое значение

В следующем примере показана функция Java, подпись которой аннотирована с @CosmosDBOutput и имеет возвращаемое значение типа String. Документ JSON, возвращаемый функцией, автоматически записывается в соответствующую коллекцию Azure Cosmos DB.

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

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

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

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

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

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

        return jsonDocument;
    }

Триггер HTTP, сохранение одного документа в базе данных через OutputBinding

В следующем примере показана функция Java, которая записывает документ в Azure Cosmos DB с помощью параметра вывода OutputBinding<T>. В этом примере аннотацию outputItem необходимо добавить к параметру @CosmosDBOutput, а не к подписи функции. Использование OutputBinding<T> позволяет функции использовать привязку для записи документа в Azure Cosmos DB, а также позволяет возвращать другое значение вызывающему объекту функции, например JSON или XML-документ.

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

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

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

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

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

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

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

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

Триггер HTTP, сохранение нескольких документов в базе данных через OutputBinding

В следующем примере показана функция Java, которая записывает несколько документов в Azure Cosmos DB через выходной параметр OutputBinding<T>. В этом примере аннотация outputItem добавлена к параметру @CosmosDBOutput, а не к подписи функции. Выходной параметр outputItem содержит список объектов ToDoItem в качестве типа параметра шаблона. Использование OutputBinding<T> позволяет функции использовать привязку для записи документов в Azure Cosmos DB, а также позволяет возвращать другое значение вызывающему объекту функции, например JSON или XML-документ.

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

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

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

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

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

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

          items.add(item);
        }

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

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

В библиотеке среды выполнения функций Java используйте заметку @CosmosDBOutput для параметров, записанных в Azure Cosmos DB. Тип параметра заметки должен быть OutputBinding<T>, где T является собственным типом Java или POJO.

В следующем примере показана функция TypeScript, активируемая очередью хранилища для очереди, которая получает JSON в следующем формате:

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

Функция создает Azure Cosmos DB документы в следующем формате для каждой записи:

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

Ниже приведен код TypeScript:

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

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

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

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

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

Чтобы вывести несколько документов, верните массив вместо одного объекта. Например:

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

В следующем примере показана функция JavaScript, активируемая очередью хранилища для очереди, которая получает JSON в следующем формате:

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

Функция создает Azure Cosmos DB документы в следующем формате для каждой записи:

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

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

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

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

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

Чтобы вывести несколько документов, верните массив вместо одного объекта. Например:

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

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

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

В файле run.ps1 объект, возвращенный из функции, сопоставляется с объектом EmployeeDocument, который хранится в базе данных.

param($QueueItem, $TriggerMetadata) 

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

В следующем примере показано, как записать документ в базу данных Azure Cosmos DB в качестве выходных данных функции. Пример зависит от того, используется ли модель программирования v1 или версии Python 2.

import logging
import azure.functions as func

app = func.FunctionApp()

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

Атрибуты

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

Свойство атрибута Описание
Соединение Имя коллекции параметров или параметров приложения, указывающее, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
Имя базы данных Имя базы данных Azure Cosmos DB с отслеживаемой контейнером.
Имя контейнера Имя отслеживаемого контейнера.
CreateIfNotExists Логическое значение, указывающее, будет ли создан контейнер при ее отсутствии. Значение по умолчанию — false, так как контейнеры создаются с использованием зарезервированной пропускной способности, с которой связаны ценовые требования. Дополнительные сведения см. на странице цен.
PartitionKey Если для CreateIfNotExists задано значение true, оно определяет путь к ключу раздела для созданного контейнера. Может включать параметры привязки.
ContainerThroughput Если для CreateIfNotExists задано значение true, оно определяет пропускную способность созданного контейнера.
Предпочитаемые расположения (Необязательно) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

Декораторы

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

Для функций Python версии 2, определенных с помощью декоратора, следующие свойства в cosmos_db_output:

Свойство Описание
arg_name Имя переменной, используемое в коде функции, представляющей список документов с изменениями.
database_name Имя базы данных Azure Cosmos DB с отслеживаемой контейнером.
container_name Имя отслеживаемого контейнера Azure Cosmos DB.
create_if_not_exists Логическое значение, указывающее, следует ли создавать базу данных и коллекцию, если они не существуют.
connection_string_setting Connection string отслеживаемых Azure Cosmos DB.

Сведения о функциях Python, определенных с помощью function.json<>/c0> см. в разделе Configuration.

Заметки

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

Настройка

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

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

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

Свойство в function.json Описание
Подключение Имя коллекции параметров или параметров приложения, указывающее, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
databaseName Имя базы данных Azure Cosmos DB с отслеживаемой контейнером.
containerName Имя отслеживаемого контейнера.
createIfNotExists Логическое значение, указывающее, будет ли создан контейнер при ее отсутствии. Значение по умолчанию — false, так как контейнеры создаются с использованием зарезервированной пропускной способности, с которой связаны ценовые требования. Дополнительные сведения см. на странице цен.
partitionKey Если для createIfNotExists задано значение true, оно определяет путь к ключу раздела для созданного контейнера. Может включать параметры привязки.
пропускная способность контейнера Если для createIfNotExists задано значение true, оно определяет пропускную способность созданного контейнера.
предпочтительный вариантLocations (Необязательно) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

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

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

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

Примечание.

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

Выходной параметр функции должен быть определен как func.Out[func.Document]. Дополнительные сведения см. в примере выходных данных .

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

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

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

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

Тип Описание
T[] где T сериализуемый тип JSON Массив, содержащий несколько документов. Каждая запись представляет один документ.

Для других сценариев вывода создайте и используйте CosmosClient с другими типами из Майкрософт.Azure. Cosmos напрямую. Пример использования внедрения зависимостей для создания типа клиента из Azure SDK см. в разделе Azure клиентов.

Связи

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

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

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

Подсказка

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

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

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

Параметр на основе шаблона Описание Тип идентификации
<CONNECTION_NAME_PREFIX>__accountEndpoint URI конечной точки учетной записи Azure Cosmos DB. Назначаемое системой или назначаемое пользователем
<CONNECTION_NAME_PREFIX>__credential Необходимо задать значение managedidentity. Назначено пользователем
<CONNECTION_NAME_PREFIX>__clientId Идентификатор клиента управляемой идентификации, назначаемой пользователем. Назначено пользователем

Значение, которое вы заменяете <CONNECTION_NAME_PREFIX> , обрабатывается расширением привязки в качестве имени параметра подключения.

Например, если конфигурация привязки задает connection = "CosmosDBConnection" управляемое удостоверение, назначаемое пользователем, настройте следующие параметры приложения:

{
    "CosmosDBConnection__accountEndpoint": "https://mycosmosdb.documents.azure.com:443/",
    "CosmosDBConnection__credential": "managedidentity",
    "CosmosDBConnection__clientId": "00000000-0000-0000-0000-000000000000"
}

Подсказка

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

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

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

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

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

Внимание

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

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

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

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

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

Исключения и коды возврата

Привязка Справочные материалы
Azure Cosmos DB коды состояния HTTP для Azure Cosmos DB

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

  • Last updated on