Обзор триггеров и привязок Azure Cosmos DB для функций Azure

В этом наборе статей объясняется, как работать с привязками Azure Cosmos DB в Функциях Azure. Служба "Функции Azure" поддерживает привязки триггера, а также входные и выходные привязки для Azure Cosmos DB.

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

Внимание

Эта версия расширения привязки Azure Cosmos DB поддерживает функции Azure версии 4.x. Если приложение по-прежнему использует среду выполнения Функций версии 1.x, вместо этого см. привязки Azure Cosmos DB для Функций Azure 1.x. В среде выполнения Functions версии 1.x эта привязка была первоначально названа DocumentDB.

Поддерживаемые API

В этой таблице показано, как подключиться к различным API Azure Cosmos DB из кода функции:

API	Recommendation
Azure Cosmos DB для работы с NoSQL	Использование расширения привязки Azure Cosmos DB
Azure Cosmos DB для MongoDB (vCore)	Используйте расширение привязки Azure Cosmos DB для MongoDB, которое в настоящее время находится в предварительной версии.
Azure Cosmos DB для таблицы	Используйте расширение привязки таблиц Azure версии 5.x или более поздней.
Azure Cosmos DB для Apache Cassandra	Используйте собственный клиентский пакет SDK.
Azure Cosmos DB для Apache Gremlin (API Graph)	Использование собственного клиентского пакета SDK
Azure Cosmos DB для PostgreSQL	Используйте собственный клиентский пакет SDK.

Установка расширения

Устанавливаемый пакет расширения NuGet зависит от режима C#, который используется в приложении-функции:

Изолированная рабочая модель
Модель внутрипроцессного процесса

Функции выполняются в изолированном рабочем процессе C#. Дополнительные сведения см. в руководстве по запуску Функции Azure C# в изолированном рабочем процессе.

Процесс установки расширения зависит от версии расширения:

В этом разделе описывается использование библиотеки классов. Для сценариев C# необходимо установить пакет расширений версии 4.x.

Эта версия расширения привязок Azure Cosmos DB представляет возможность подключения с помощью удостоверения вместо секрета. Руководство по настройке приложений-функций с помощью управляемых удостоверений см. в руководстве по созданию приложения-функции с подключениями на основе удостоверений.

Эта версия также изменяет типы, к которым можно осуществлять привязку, заменив типы из пакета SDK версии 2 Microsoft.Azure.DocumentDB на более новые типы из пакета SDK Microsoft.Azure.Cosmos версии 3. Узнайте подробнее о том, чем отличаются эти новые типы и как перенести их из руководства по миграции пакета SDK, примеров триггера, входной привязки и выходной привязки.

Эта версия расширения доступна в виде пакета NuGet версии 4.x.

Добавьте расширение в проект, установив пакет NuGet версии 4.x.

Если вы пишете приложение с помощью F#, необходимо также настроить это расширение в рамках конфигурации запуска приложения. В вызове ConfigureFunctionsWorkerDefaults() или ConfigureFunctionsWebApplication()добавьте делегат, принимающее IFunctionsWorkerApplication параметр. Затем в теле этого делегата вызовите ConfigureCosmosDBExtension() объект:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Установка пакета

Чтобы использовать это расширение привязки в приложении, убедитесь, что файл host.json в корне проекта содержит следующую extensionBundle ссылку:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

В этом примере значение указывает узлу version функций использовать версию пакета, которая по крайней мере [4.0.0, 5.0.0) меньше4.0.0, чем , которая включает все потенциальные версии 4.x.5.0.0 Эта нотация эффективно поддерживает ваше приложение в последней доступной дополнительной версии пакета расширений версии 4.x.

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

Из-за изменений схемы в пакете SDK для Azure Cosmos DB версии 4.x расширения Azure Cosmos DB требуется azure-functions-java-library версии 3.0.0 для функций Java.

Типы привязки

Типы привязки, поддерживаемые для .NET, зависят от версии расширения и режима выполнения C#, что может быть одним из следующих типов:

Изолированная рабочая модель
Модель внутрипроцессного процесса

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

Выберите версию, чтобы просмотреть сведения о типе привязки для режима и версии.

Расширение Azure Cosmos DB поддерживает типы параметров в соответствии с таблицей ниже.

Сценарий привязки	Типы параметров
Триггер Cosmos DB (один документ)	Сериализуемые типы^{JSON 1}
Триггер Cosmos DB (пакет документов)	`IEnumerable<T>`где `T` является сериализуемый тип^{JSON 1}
Входные данные Cosmos DB (один документ)	Сериализуемые типы^{JSON 1}
Входные данные Cosmos DB (запрос, возвращающий несколько документов)	CosmosClient `IEnumerable<T>` где `T` является сериализуемый тип^{JSON 1}
Выходные данные Cosmos DB (один документ)	Сериализуемые типы^{JSON 1}
Выходные данные Cosmos DB (несколько документов)	`ICollector<T>` или `IAsyncCollector<T>` где `T` находится сериализуемый тип^{JSON 1}

¹ Документы, содержащие данные JSON, можно десериализировать в известные типы объектов CLR (POCO).

Изолированный рабочий процесс поддерживает типы параметров в соответствии с таблицами ниже. Поддержка привязки к типам из Microsoft.Azure.Cosmosдоступна в предварительной версии.

Триггер Cosmos DB

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

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

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

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

Входная привязка Cosmos DB

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

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

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

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

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

Выходная привязка Cosmos DB

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

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

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

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

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

Типы привязки ПАКЕТА SDK

Поддержка типов ПАКЕТА SDK для Azure Cosmos доступна в предварительной версии. Выполните привязки пакета SDK для Python для CosmosDB, чтобы приступить к работе с типами пакетов SDK для Cosmos в Python.

Внимание

Для привязок типов SDK требуется модель программирования Python версии 2.

Привязка	Типы параметров	Образцы
Входные данные CosmosDB	ContainerProxy, CosmosClient, DatabaseProxy	`ContainerProxy`, `CosmosClient`, `DatabaseProxy`

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

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

Параметры файла host.json

В этом разделе описаны параметры конфигурации, доступные для этой привязки в версии 2.x и более поздних версиях. Параметры в файле host.json применяются ко всем функциям в экземпляре приложения-функции. Дополнительные сведения о параметрах конфигурации приложения-функции см. вhost.json справочнике по функциям Azure.

Расширение 4.x+
Функции 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Свойство	По умолчанию	Описание
connectionMode	`Gateway`	Режим подключения, используемый функцией при подключении к службе Azure Cosmos DB. Параметры: `Direct` подключается непосредственно к серверным репликам через TCP и может обеспечить низкую задержку и `Gateway` маршрутизирует запросы через интерфейсный шлюз по протоколу HTTPS. Дополнительные сведения см. в режимах подключения пакета SDK для Azure Cosmos DB.
userAgentSuffix	Н/Д	Добавляет указанное строковое значение ко всем запросам, выполняемым триггером или привязкой к службе. Это упрощает отслеживание действий в Azure Monitor на основе конкретного приложения-функции, а также фильтрацию по `User Agent`.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Свойство	По умолчанию	Описание
connectionMode	`Gateway`	Режим подключения, используемый функцией при подключении к службе Azure Cosmos DB. Параметры: `Direct` подключается непосредственно к серверным репликам через TCP и может обеспечить низкую задержку и `Gateway` маршрутизирует запросы через интерфейсный шлюз по протоколу HTTPS. Дополнительные сведения см. в режимах подключения пакета SDK для Azure Cosmos DB.
протокол	`Https`	Протокол подключения, используемый функцией при подключении к службе Azure Cosmos DB. Здесь можно найти описание обоих режимов.
leasePrefix	Н/Д	Префикс аренды для использования во всех функциях приложения.

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-08-26