Общие сведения о триггере Azure Cosmos DB и привязках в службе "Функции Azure" 2.x и более поздних версий

• Версия 1
• Версия 2 и более поздние версии

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

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

Примечание.

Эта информация относится к службе "Функции Azure" 2.x и более поздних версий. Для получения дополнительных сведений об использовании Функций версии 1.x см. раздел Функции 1.х.

Эта привязка называлась DocumentDB. В Функции Azure версии 2.x и выше триггер, привязки и пакет называются Azure Cosmos DB.

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

Привязки Azure Cosmos DB поддерживаются только для использования с Azure Cosmos DB для NoSQL. Поддержка Azure Cosmos DB для таблицы предоставляется с помощью привязок хранилища таблиц, начиная с расширения 5.x. Для всех других API Azure Cosmos DB необходимо получить доступ к базе данных из функции с помощью статического клиента для API, включая Azure Cosmos DB для MongoDB, Azure Cosmos DB для Cassandra и Azure Cosmos DB для Apache Gremlin.

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

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

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

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

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

Внимание

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

Функции выполняются в том же процессе, что и хост-процесс функций. Дополнительные сведения см. в статье Разработка функций библиотеки классов C# с помощью службы "Функции Azure".

В варианте этой модели функции можно запускать с помощью скриптов C#, которая поддерживается главным образом для редактирования портала C#. Информацию о том, как обновить существующие расширения привязки для приложений скриптов C#, выполняемых на портале, не переиздавая приложение-функцию, см. в разделе Обновление расширений.

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

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

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

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

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

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

Функции 2.x+

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

Для работы с триггером и привязками требуется ссылка на соответствующий пакет NuGet. Установите пакет NuGet версии 3.x.

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

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

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

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

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

Функции 2.x+

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

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

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

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

Пакет версии 4.x

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

Эту версию расширения можно добавить из предварительной версии пакета расширений 4. Для этого необходимо добавить или заменить следующий код в файле host.json:

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

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

Пакет версии 2.x и версии 3.x

Эту версию расширения можно установить в приложении-функции, зарегистрировав пакет расширений версии 2.x или 3.x.

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

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

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

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

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

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

Библиотека внутрипроцессных классов — это скомпилированная функция C#, которая выполняется в том же процессе, что и среда выполнения Функций.

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

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

Расширение 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).

Функции 2.x+

Более ранние версии расширения предоставляют типы из нерекомендуемого пространства имен Microsoft.Azure.Documents . Новые типы из Microsoft.Azure.Cosmos являются эксклюзивными для расширения 4.x и выше.

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

Изолированный рабочий процесс поддерживает типы параметров в соответствии с таблицами ниже. Поддержка привязки к типам из 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	Перечисление сущностей, возвращаемых запросом. Каждая запись представляет один документ.
CosmosClient1	Клиент, подключенный к учетной записи Cosmos DB.
База данных1	Клиент, подключенный к базе данных Cosmos DB.
Контейнер1	Клиент, подключенный к контейнеру 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".

Функции 2.x+

Более ранние версии расширений в изолированном рабочем процессе поддерживают привязку только к сериализуемым типам JSON. Дополнительные параметры доступны для расширения 4.x и более поздних версий.

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

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

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

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

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

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

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

Функции 2.x+

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

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

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

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