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

Внимание

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

Пример

Если не указано иное, примеры в этой статье предназначены для расширения Azure Cosmos DB версии 3.x. Для использования с расширением версии 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> параметра. В этом примере аннотацию @CosmosDBOutput необходимо добавить к параметру outputItem, а не к подписи функции. Использование 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> параметра. В этом примере аннотация @CosmosDBOutput добавлена к параметру outputItem, а не к подписи функции. Выходной параметр 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 в качестве выходных данных функции. Пример зависит от того, используется ли модель программирования Python версии 1 или версии 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#.

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

Декораторы

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

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

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

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

Заметки

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

Настройка

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

Для других сценариев выходных данных напрямую создайте и используйте типы из Microsoft.Azure.Cosmos .

Связи

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

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

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

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

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

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

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

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