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

  • Статья

В этой серии статей описано, как использовать привязки 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# в изолированном рабочем процессе.

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

Эта версия расширения привязок 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

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

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

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

Эта версия пакета содержит версию 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)"
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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