Выходная привязка 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.

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

Функцию 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 в именах свойств и атрибутов и container connection_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>
    }

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

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

• Триггер очереди, запись одного документа
• Триггер очереди, запись одного документа (расширение версии 4)
• Триггер очереди, запись документов с помощью IAsyncCollector

В примерах используется ToDoItem простого типа:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

Триггер очереди, запись одного документа

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

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

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Триггер очереди, запись одного документа (расширение версии 4)

Приложения с расширением Azure Cosmos DB версии 4.x или более поздней версии будут иметь различные свойства атрибута, показанные ниже. В следующем примере показана функция C#, которая добавляет документ в базу данных, используя данные, полученные из сообщения хранилища очередей.

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

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Триггер очереди, запись документов при помощи IAsyncCollector

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

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

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

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

В следующем примере показана функция 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.

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

В следующем примере показана функция 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',
    },
];

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

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

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

В следующем примере показана функция 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',
    },
];

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

В следующем примере показана выходная привязка Azure Cosmos DB в файле function.json и функция 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"
}

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

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

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

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

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

Для массовой вставки сначала создайте объекты, а затем выполните функцию преобразования в строку. Ниже показан код JavaScript.

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "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.

версия 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'

версия 1

Определение привязки указывается в файле function.json, в котором type задан как cosmosDB.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Для записи в базу данных передайте объект документа в метод set параметра базы данных.

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

Атрибуты

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

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

Свойство атрибута	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.

Функции 2.x+

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

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

Свойство атрибута	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.

Функции 2.x+

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

Декораторы

Применяется только к модели программирования 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. Эта заметка поддерживает следующие свойства:

• name
• connectionStringSetting
• databaseName
• collectionName
• createIfNotExists
• dataType
• partitionKey
• preferredLocations
• useMultipleWriteLocations

Настройка

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

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

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

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

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

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

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

Свойство в 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.

Функции 2.x+

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

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

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

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

Примечание.

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

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

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

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

Функции 2.x+

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

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

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

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

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

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

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

Функции 2.x+

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

Связи

Свойства 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	Коды состояния HTTP для Azure Cosmos DB

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

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