Бөлісу құралы:

Перенос приложений-функций из расширения Azure Cosmos DB версии 3.x в версию 4.x

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

Внимание

31 августа 2024 г. расширение Azure Cosmos DB версии 3.x будет прекращено. Расширение и все приложения, использующие расширение, будут продолжать функционировать, но Azure Cosmos DB перестанет предоставлять дальнейшее обслуживание и поддержку этого расширения. Мы рекомендуем перейти к последней версии 4.x расширения.

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

Изменения в создании идентификаторов элементов

Идентификатор элемента больше не заполняется в расширении автоматически. Таким образом, идентификатор элемента должен в частности включать созданный идентификатор для случаев, когда вы использовали выходную привязку для создания элементов. Чтобы сохранить то же поведение, что и предыдущая версия, можно назначить случайный GUID в качестве свойства идентификатора.

Обновление версии расширения

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

Модель процесса функций Расширение Azure Cosmos DB Рекомендуемая версия
Модель внутрипроцессного процесса Microsoft.Azure.WebJobs.Extensions.CosmosDB >= 4.3.0
Изолированная рабочая модель Microsoft.Azure.Functions.Worker.Extensions.CosmosDB >= 4.4.1

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.CosmosDB" Version="4.6.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

Обновление пакета расширений

По умолчанию пакеты расширений используются приложениями-функциями non-.NET для установки расширений привязки. Расширение Azure Cosmos DB версии 4 является частью пакета расширений Microsoft Функции Azure версии 4.

Чтобы обновить приложение, чтобы использовать последний пакет расширений, обновите приложение host.json. host.json Следующий файл использует версию 4 пакета расширений Microsoft Функции Azure.

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

Переименование атрибутов привязки

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

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

Свойство атрибута версии 3 Свойство атрибута версии 4 Описание атрибута версии 4
ConnectionStringSetting Соединение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
Имя коллекции Имя контейнера Имя отслеживаемого контейнера.
LeaseConnectionStringSetting LeaseConnection (Необязательно) Имя параметра или коллекции параметров приложения, указывающее, как подключиться к учетной записи Azure Cosmos DB, содержащей контейнер аренды.

Если значение не задано, используется значение Connection. Этот параметр задается автоматически при создании привязки на портале. Строка подключения для контейнера аренд должна иметь разрешения на запись.
LeaseCollectionName LeaseContainerName (Необязательно.) Имя контейнера, используемого для хранения аренд. Если значение не задано, используется значение leases.
СоздатьКоллекциюАрендЕслиНеСуществует CreateLeaseContainerIfNotExists (Необязательно.) Если задано значение true, контейнер аренд создается автоматически, если он еще не создан. Значение по умолчанию — false. При использовании удостоверений Microsoft Entra, если задано значение true, создание контейнеров не является разрешенной операцией , и функция не сможет запуститься.
LeasesCollectionThroughput LeasesContainerThroughput (Необязательно.) Определяет количество единиц запроса для назначения при создании контейнера аренд. Этот параметр используется, только если для CreateLeaseContainerIfNotExists задано значение true. Этот параметр задается автоматически при создании привязки с помощью портала.
LeaseCollectionPrefix LeaseContainerPrefix (Необязательно.) Если этот параметр задан, значение добавляется в качестве префикса к арендам, созданным в контейнере аренд для этой функции. Использование префикса позволяет двум отдельным Функциям Azure совместно применять один контейнер аренд с помощью разных префиксов.
UseMultipleWriteLocations Удалено Этот атрибут больше не требуется, так как он обнаруживается автоматически.
UseDefaultJsonSerialization Удалено Этот атрибут больше не нужен, так как вы можете полностью настроить сериализацию с помощью встроенной поддержки в пакете SDK для .NET для Azure Cosmos DB версии 3.
Контрольная точка интервал Удалено Этот атрибут был удален в расширении версии 4.
КонтрольнаяТочкаКоличествоДокументов Удалено Этот атрибут был удален в расширении версии 4.

Переименование атрибутов привязки

Обновите свойства конфигурации привязки function.json в файле.

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

Свойство атрибута версии 3 Свойство атрибута версии 4 Описание атрибута версии 4
connectionStringSetting Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
collectionName containerName Имя отслеживаемого контейнера.
leaseConnectionStringSetting leaseConnection (Необязательно) Имя параметра или коллекции параметров приложения, указывающее, как подключиться к учетной записи Azure Cosmos DB, содержащей контейнер аренды.

Если значение не задано, используется значение connection. Этот параметр задается автоматически при создании привязки на портале. Строка подключения для контейнера аренд должна иметь разрешения на запись.
leaseCollectionName арендаНазваниеКонтейнера (Необязательно.) Имя контейнера, используемого для хранения аренд. Если значение не задано, используется значение leases.
создатьКоллекциюАрендыЕслиНеСуществует создатьКонтейнерАрендыЕслиНеСуществует (Необязательно.) Если задано значение true, контейнер аренд создается автоматически, если он еще не создан. Значение по умолчанию — false. При использовании удостоверений Microsoft Entra, если задано значение true, создание контейнеров не является разрешенной операцией , и функция не сможет запуститься.
leasesCollectionThroughput leasesContainerThroughput (Необязательно.) Определяет количество единиц запроса для назначения при создании контейнера аренд. Этот параметр используется, только если для createLeaseContainerIfNotExists задано значение true. Этот параметр задается автоматически при создании привязки с помощью портала.
leaseCollectionPrefix leaseContainerPrefix (Необязательно.) Если этот параметр задан, значение добавляется в качестве префикса к арендам, созданным в контейнере аренд для этой функции. Использование префикса позволяет двум отдельным Функциям Azure совместно применять один контейнер аренд с помощью разных префиксов.
useMultipleWriteLocations Удалено Этот атрибут больше не требуется, так как он обнаруживается автоматически.
интервалКонтрольнойТочки Удалено Этот атрибут был удален в расширении версии 4.
контрольная точкаКоличествоДокументов Удалено Этот атрибут был удален в расширении версии 4.

Изменение кода функции

Расширение Функции Azure версии 4 построено на основе пакета SDK для .NET для Azure Cosmos DB версии 3, который удалил поддержку классаDocument. Вместо получения списка Document объектов с каждым вызовом функции, который затем необходимо десериализировать в собственный тип объекта, теперь можно получить список объектов собственного типа.

Этот пример относится к простому типу ToDoItem.

namespace CosmosDBSamples
{
    // Customize the model with your own desired properties
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

При определении функции необходимо вносить изменения в имена атрибутов непосредственно в коде.

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

namespace CosmosDBSamples
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "databaseName",
            containerName: "containerName",
            Connection = "CosmosDBConnectionSetting",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> input, ILogger log)
        {
            if (input != null && input.Count > 0)
            {
                log.LogInformation("Documents modified " + input.Count);
                log.LogInformation("First document Id " + input[0].id);
            }
        }
    }
}

Примечание.

Если сценарий зависит от динамической Document природы типа для идентификации различных схем и типов событий, можно использовать базовый абстрактный тип с общими свойствами для типов или динамических типов, таких как JObject (при использовании Microsoft.Azure.WebJobs.Extensions.CosmosDB) и JsonNode (при использовании Microsoft.Azure.Functions.Worker.Extensions.CosmosDB), которые позволяют получить доступ к свойствам, как Document это было.

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

Изменение кода функции

После обновления host.json правильной версии пакета расширений и изменения function.json правильных имен атрибутов нет дополнительных изменений кода, необходимых для случаев, когда вы используете входные привязки или триггер. Если вы используете выходную привязку, просмотрите изменения в создании идентификатора элемента, чтобы проверить, требуются ли дополнительные изменения кода.

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