Azure Functions 2.x 以降での Azure Cosmos DB のトリガーとバインドの概要

  • [アーティクル]

この一連の記事では、Azure Functions 2.x 以降で Azure Cosmos DB のバインドを操作する方法について説明します。 Azure Functions は、Azure Cosmos DB のトリガー、入力、出力のバインドをサポートしています。

アクション Type
Azure Cosmos DB ドキュメントが作成または変更されたときに関数を実行する トリガー
Azure Cosmos DB ドキュメントを読み込む 入力バインド
Azure Cosmos DB ドキュメントに変更を保存する 出力バインド

Note

このリファレンスは、Azure Functions のバージョン 2.x 以降を対象としています。 Functions 1.x でこれらのバインドを使用する方法については、Azure Functions 1.x の Azure Cosmos DB のバインドに関するページを参照してください。

このバインドの元の名称は DocumentDB でした。 Azure Functions バージョン 2.x 以降では、トリガー、バインド、およびパッケージの名称はすべて、Azure Cosmos DB になっています。

サポート対象 API

Azure Cosmos DB のバインドは、Azure Cosmos DB for NoSQL で使用する場合にのみサポートされます。 Azure Cosmos DB for Table のサポートは、拡張機能 5.x 以降のテーブル ストレージのバインドを使用して提供されます。 他のすべての Azure Cosmos DB API については、Azure Cosmos DB for MongoDB、Azure Cosmos DB for Cassandra、Azure Cosmos DB for Apache Gremlin などの API 用の静的クライアントを使用して、関数からデータベースにアクセスする必要があります。

拡張機能のインストール

インストールする拡張機能 NuGet パッケージは、関数アプリで使用している C# モードによって異なります。

関数は分離された C# ワーカー プロセスで実行されます。 詳しくは、「分離ワーカー プロセスにおける C# Azure Functions の実行のガイド」をご覧ください。

拡張機能をインストールするプロセスは、拡張機能のバージョンによって異なります。

このバージョンの Azure Cosmos DB バインド拡張機能では、シークレットの代わりに ID を使用して接続する機能が導入されています。 マネージド ID を使用して関数アプリを構成するチュートリアルについては、ID ベースの接続を使用した関数アプリの作成に関 するチュートリアルを参照してください。

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 プロジェクト ファイルで指定される拡張機能バンドルの一部です。 このバンドルは、バインドのバージョンを変更するために、またはバンドルがまだインストールされていない場合に変更が必要になることがあります。 詳細については、「拡張機能のバンドル」を参照してください。

Azure Cosmos DB SDK でのスキーマ変更のため、Azure Cosmos DB 拡張機能のバージョン 4.x で Java 関数を使用するには、azure-functions-java-library V3.0.0 が必要になります。

このバージョンのバンドルには、シークレットの代わりに ID を使用して接続する機能を導入するバージョン 4.x の Azure Cosmos DB バインド拡張機能が含まれています。 マネージド ID を使用して関数アプリを構成するチュートリアルについては、ID ベースの接続を使用した関数アプリの作成に関 するチュートリアルを参照してください。

このバージョンの拡張機能は、host.json ファイルで次のコードを追加するか、または置き換えることによって、プレビュー拡張機能バンドル v4 から追加できます。

{
  "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 トリガー

関数で 1 つのドキュメントを処理するとき、Cosmos DB トリガーは次の型にバインドできます。

Type 説明
JSON シリアル化可能な型 Functions は、ドキュメントの JSON データを Cosmos DB 変更フィードから単純な従来の CLR オブジェクト (POCO) 型に逆シリアル化しようとします。

関数でドキュメントのバッチを処理するとき、Cosmos DB トリガーは次の型にバインドできます。

Type 説明
IEnumerable<T> (T は JSON シリアル化可能な型) バッチに含まれるエンティティの列挙型。 各エントリは、Cosmos DB 変更フィードの 1 つのドキュメントを表します。

Azure Cosmos DB 入力バインディング

関数で 1 つのドキュメントを処理するとき、Cosmos DB 入力バインドは次の型にバインドできます。

Type 説明
JSON シリアル化可能な型 Functions はドキュメントの JSON データを単純な従来の CLR オブジェクト (POCO) 型に逆シリアル化しようとします。

関数で 1 つのクエリから得た複数のドキュメントを処理するとき、Cosmos DB 入力バインドは次の型にバインドできます。

Type 説明
IEnumerable<T> (T は JSON シリアル化可能な型) クエリによって返されるエンティティの列挙型。 各エントリは 1 つのドキュメントを表します。
CosmosClient1 Cosmos DB アカウントに接続されているクライアント。
Database1 Cosmos DB データベースに接続されているクライアント。
Container1 Cosmos DB コンテナーに接続されているクライアント。

1 これらの型を使用するには、Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 以降と SDK 型バインドの一般的な依存関係を参照する必要があります。

Cosmos DB の出力バインド

関数で 1 つのドキュメントに書き込む場合、Cosmos DB の出力バインドは次の型にバインドできます。

Type 説明
JSON シリアル化可能な型 ドキュメントの JSON コンテンツを表すオブジェクト。 Functions は、単純な従来の CLR オブジェクト (POCO) 型を JSON データにシリアル化しようとします。

関数で複数のドキュメントに書き込む場合、Cosmos DB の出力バインドは次の型にバインドできます。

Type 説明
T[] (T は JSON シリアル化可能な型) 複数のドキュメントを含む配列。 各エントリは 1 つのドキュメントを表します。

その他の出力シナリオでは、Microsoft.Azure.Cosmos から直接、型を作成して使用します。

例外とリターン コード

バインド リファレンス
Azure Cosmos DB Azure Cosmos DB の HTTP 状態コード

host.json 設定

このセクションでは、バージョン 2.x 以降でこのバインドに使用可能な構成設定について説明します。 host.json ファイルの設定は、関数アプリ インスタンスのすべての関数に適用されます。 次の host.json ファイルの例には、このバインドのバージョン 2.x 以降の設定のみが含まれています。 バージョン 2.x 以降のバージョンでの関数アプリ構成設定の詳細については、「Azure Functions の host.json のリファレンス」を参照してください。

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
プロパティ Default 説明
connectionMode Gateway Azure Cosmos DB サービスに接続する際に関数で使用される接続モード。 オプションは Direct と Gateway です
userAgentSuffix 該当なし 指定された文字列値を、このサービスへのトリガーまたはバインディングによって作成されたすべての要求に追加します。 これにより、特定の関数アプリや User Agent によるフィルター処理に基づいて、Azure Monitor でのアクティビティを追跡することが簡単になります。

次のステップ