次の方法で共有

関数アプリを Azure Cosmos DB 拡張機能バージョン 3.x からバージョン 4.x に移行する

この記事では、Azure Cosmos DB 拡張機能バージョン 3.x を使用する既存の Azure Functions アプリケーションを、新しい拡張機能バージョン 4.x を使用するようにアップグレードするときの考慮事項について説明します。 Azure Cosmos DB 拡張機能のバージョン 3.x からバージョン 4.x に移行すると、アプリケーションに重大な変更が発生します。

重要

2024 年 8 月 31 日に、Azure Cosmos DB 拡張機能 バージョン 3.x は廃止されます。 拡張機能と、拡張機能を使用するすべてのアプリケーションは引き続き機能しますが、Azure Cosmos DB は、この拡張機能の今後のメンテナンスとサポートを停止します。 拡張機能の最新のバージョン 4.x に移行することをお勧めします。

この記事では、Azure Cosmos DB 拡張機能のバージョン 4.x で実行するように関数アプリを移行するプロセスについて説明します。 プロジェクトのアップグレード手順は言語に依存するため、記事の上部にあるセレクターから開発言語を選択してください。

項目 ID 生成の変更

Extension で項目 ID が自動的に設定されなくなりました。 そのため、項目の作成に出力バインドを使っていた場合は、項目 ID には生成された ID を明示的に含める必要があります。 以前のバージョンと同じ動作を維持するために、ランダムな GUID を ID プロパティとして割り当てることができます。

拡張機能のバージョンを更新する

.NET 関数は、プロジェクトに NuGet パッケージとしてインストールされているバインドを使用します。 Functions プロセス モデルに応じて、更新する NuGet パッケージは異なります。

Functions プロセス モデル Azure Cosmos DB の拡張機能 推奨されるバージョン
インプロセス モデル Microsoft.Azure.WebJobs.Extensions.CosmosDB 4.3.0 以上
分離ワーカー モデル Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.1 以上

プロセス モデルに対する最新の拡張機能バージョンを使用するように .csproj プロジェクト ファイルを更新します。 次の .csproj ファイルは、Azure Cosmos DB 拡張機能のバージョン 4 を使用します。

<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>

拡張機能バンドルを更新する

既定では、拡張機能バンドルは、.NET 以外の関数アプリがバインド拡張機能をインストールするために使用します。 Azure Cosmos DB バージョン 4 拡張機能は、Microsoft Azure Functions バージョン 4 拡張機能バンドルの一部です。

最新の拡張機能バンドルを使用するようにアプリケーションを更新するには、host.json を更新します。 次の host.json ファイルは、Microsoft Azure Functions 拡張機能バンドルのバージョン 4 を使用します。

{
  "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 アカウントへの接続方法を指定するアプリの設定または設定のコレクションの名前。 詳細については、「接続」を参照してください。
CollectionName ContainerName 監視対象のコンテナーの名前。
LeaseConnectionStringSetting LeaseConnection (省略可能) リース コンテナーを保持する Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定コレクションの名前。

この値を設定しない場合、Connection という値が使用されます。 このパラメーターは、ポータルでバインドが作成されるときに自動で設定されます。 リース コンテナーの接続文字列には書き込みアクセス許可が必要です。
LeaseCollectionName LeaseContainerName (省略可能) リースの格納に使用するコンテナーの名前。 この値を設定しない場合、leases という値が使用されます。
CreateLeaseCollectionIfNotExists CreateLeaseContainerIfNotExists（存在しない場合はリースコンテナを作成） (省略可能) true に設定すると、リース コンテナーが存在していない場合に自動的に作成します。 既定値は false です。 Microsoft Entra ID を使用する場合にこの値を true に設定すると、コンテナーの作成は、許可される操作ではなくなり、関数を起動できなくなります。
leasesCollectionThroughput LeasesContainerThroughput (省略可能) リース コンテナーの作成時に割り当てる要求ユニットの数を定義します。 この設定は、CreateLeaseContainerIfNotExists が true に設定されている場合のみ使用できます。 このパラメーターは、ポータルを使用してバインドを作成するときに自動的に設定されます。
LeaseCollectionPrefix LeaseContainerPrefix (省略可能) 設定すると、この関数のリース コンテナーで作成されたリースへのプレフィックスとして値が追加されます。 プレフィックスを使用すると、異なるプレフィックスを使用して、2 つの別の Azure 関数が同じリース コンテナーを共有できるようになります。
複数の書き込み場所を使用する 削除済み この属性は自動的に検出されるため、もう必要ありません。
UseDefaultJsonSerialization（デフォルトのJSONシリアル化を使用） 削除済み Azure Cosmos DB バージョン 3 .NET SDK の組み込みサポートを使用してシリアル化を完全にカスタマイズできるため、この属性はもう必要ありません。
CheckpointInterval 削除済み この属性は、バージョン 4 拡張機能で削除されました。
CheckpointDocumentCount 削除済み この属性は、バージョン 4 拡張機能で削除されました。

バインド属性の名前を変更する

function.json ファイル内のバインド構成プロパティを更新します。

次の表には、バージョン 3.x の拡張機能から変更されたか、削除された属性のみが含まれています。 バージョン 4 拡張機能で使用できる属性の全一覧については、属性リファレンスを参照してください。

バージョン 3 の属性プロパティ バージョン 4 の属性プロパティ バージョン 4 の属性の説明
connectionStringSetting 接続 監視対象の Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定のコレクションの名前。 詳細については、「接続」を参照してください。
collectionName containerName 監視対象のコンテナーの名前。
leaseConnectionStringSetting leaseConnection (省略可能) リース コンテナーを保持する Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定コレクションの名前。

この値を設定しない場合、connection という値が使用されます。 このパラメーターは、ポータルでバインドが作成されるときに自動で設定されます。 リース コンテナーの接続文字列には書き込みアクセス許可が必要です。
leaseCollectionName リースコンテナ名 (省略可能) リースの格納に使用するコンテナーの名前。 この値を設定しない場合、leases という値が使用されます。
createLeaseCollectionIfNotExists リースコンテナが存在しない場合は作成する (省略可能) true に設定すると、リース コンテナーが存在していない場合に自動的に作成します。 既定値は false です。 Microsoft Entra ID を使用する場合にこの値を true に設定すると、コンテナーの作成は、許可される操作ではなくなり、関数を起動できなくなります。
leasesCollectionThroughput leasesContainerThroughput (省略可能) リース コンテナーの作成時に割り当てる要求ユニットの数を定義します。 この設定は、createLeaseContainerIfNotExists が true に設定されている場合のみ使用できます。 このパラメーターは、ポータルを使用してバインドを作成するときに自動的に設定されます。
leaseCollectionPrefix leaseContainerPrefix (省略可能) 設定すると、この関数のリース コンテナーで作成されたリースへのプレフィックスとして値が追加されます。 プレフィックスを使用すると、異なるプレフィックスを使用して、2 つの別の Azure 関数が同じリース コンテナーを共有できるようになります。
useMultipleWriteLocations（複数の書き込み場所を使用） 削除済み この属性は自動的に検出されるため、もう必要ありません。
チェックポイント間隔 削除済み この属性は、バージョン 4 拡張機能で削除されました。
checkpointDocumentCount 削除済み この属性は、バージョン 4 拡張機能で削除されました。

関数コードを変更する

Azure Functions 拡張機能バージョン 4 は、Document クラスのサポートが削除された Azure Cosmos DB .NET SDK バージョン 3 の上に構築されています。 関数呼び出しごとに 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 使用時) などの動的な型を使用できます。

さらに、出力バインドを使用している場合は、項目 ID 生成の変更を確認して、追加のコード変更が必要かどうかを確認してください。

関数コードを変更する

正しい拡張バンドル バージョンを使用するように host.json を更新し、正しい属性名を使用するように function.json を変更したら、入力バインドまたはトリガーを使用している場合、それ以上コードの変更は必要ありません。 出力バインドを使用している場合は、項目 ID 生成の変更を確認して、追加のコード変更が必要かどうかを確認してください。

次のステップ