次の方法で共有

Azure Functions の Azure Cosmos DB トリガーとバインドの概要

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

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

重要

このバージョンの Azure Cosmos DB バインド拡張機能では、 Azure Functions バージョン 4.x がサポートされています。 アプリで Functions ランタイムのバージョン 1.x が引き続き使用されている場合は、代わりに Azure Functions 1.x の Azure Cosmos DB バインドを参照してください。 Functions v1.x ランタイムでは、このバインディングはもともと DocumentDB という名前でした。

サポート対象 API

次の表は、関数コードからさまざまな Azure Cosmos DB API に接続する方法を示しています。

API 勧告
Azure Cosmos DB (NoSQL) Azure Cosmos DB バインド拡張機能を使用する
Azure Cosmos DB for MongoDB (仮想コア) Azure Cosmos DB for MongoDB バインド拡張機能を使用します。これは現在プレビュー段階です。
Azure Cosmos DB for Table バージョン 5.x 以降の Azure Tables バインディング拡張機能を使用します。
Azure Cosmos DB for Apache Cassandra ネイティブ クライアント SDK を使用します。
Azure Cosmos DB for Apache Gremlin (Graph API) ネイティブ クライアント SDK を使用する
PostgreSQL 用 Azure Cosmos DB ネイティブ クライアント SDK を使用します。

拡張機能のインストール

インストールする拡張機能 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

バンドルのインストール

アプリでこのバインド拡張機能を使用できるようにするには、プロジェクトのルートにある host.json ファイルに次の extensionBundle 参照が含まれていることを確認します。

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

この例では、versionの[4.0.0, 5.0.0)値は、少なくとも4.0.0が5.0.0未満のバンドル バージョン (4.x のすべての潜在的なバージョンを含む) を使用するように Functions ホストに指示します。 この表記は、v4.x 拡張機能バンドルの利用可能な最新のマイナー バージョンでアプリを効果的に維持します。

可能であれば、最新の拡張機能バンドルメジャー バージョンを使用し、ランタイムが最新のマイナー バージョンを自動的に維持できるようにする必要があります。 最新のバンドルの内容は、 拡張機能バンドルのリリース ページで確認できます。 詳細については、 Azure Functions 拡張機能バンドルに関するページを参照してください。

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

バインドの種類

.NET でサポートされるバインドの種類は、拡張機能のバージョンと C# 実行モードの両方によって異なります。これは次のいずれかになります。

分離ワーカー プロセス クラス ライブラリでコンパイルされた C# 関数は、ランタイムから分離されたプロセスで実行されます。

バージョンを選択すると、モードとバージョンのバインドの種類の詳細が表示されます。

分離ワーカー プロセスでは、下の表に従ってパラメーターの型がサポートされています。 Microsoft.Azure.Cosmos から型へのバインドのサポートは、プレビュー段階です。

Cosmos DB トリガー

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

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

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

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

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

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

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

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

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

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

Cosmos DB の出力バインド

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

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

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

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

その他の出力シナリオでは、 CosmosClientMicrosoft.Azure.Cosmos の他の型と共に を直接作成して使用します。 依存関係の挿入を使用して Azure SDK からクライアントの種類を作成する例については Azure クライアントの登録に関するページを参照してください。

SDK バインドの種類

Azure Cosmos の SDK の種類のサポートはプレビュー段階です。 Python での Cosmos 用 SDK の種類の使用を開始するには、CosmosDB 用の Python SDK バインドのサンプルに従います。

重要

SDK の型バインドを使用するには、 Python v2 プログラミング モデルが必要です。

バインド パラメーターの種類 サンプル
CosmosDB 入力 ContainerProxy、
CosmosClient、
DatabaseProxy
 ContainerProxy,
CosmosClient,
DatabaseProxy

例外とリターン コード

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

host.json 設定

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

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
プロパティ 既定値 説明
connectionMode Gateway Azure Cosmos DB サービスに接続する際に関数で使用される接続モード。 オプション: Direct は TCP 経由でバックエンド レプリカに直接接続し、待機時間を短縮でき、 Gateway は HTTPS 経由でフロントエンド ゲートウェイ経由で要求をルーティングします。 詳細については、 Azure Cosmos DB SDK の接続モードに関するページを参照してください。
userAgentSuffix 該当なし 指定された文字列値を、このサービスへのトリガーまたはバインディングによって作成されたすべての要求に追加します。 これにより、特定の関数アプリや User Agent によるフィルター処理に基づいて、Azure Monitor でのアクティビティを追跡することが簡単になります。

次のステップ