Azure FunctionsでCosmos DBの変更をきっかけに処理を動かしている場合、最初に確認すべき結論はシンプルです。Azure Cosmos DB trigger for Functions 2.x and higherは、変更フィードを使ってCosmos DBの挿入・更新を検知するトリガーであり、運用上の重要ポイントは「拡張機能4.x以降の設定名」「リースコンテナー」「マネージドID接続」「C#インプロセスモデルの移行」「スケール設定」の5つです。
特に既存のFunction Appを使っている管理者・開発者は、collectionNameからcontainerName、connectionStringSettingからconnectionといった設定名の違い、リースコンテナーの作成方法、IDベース接続時の権限付与を確認しておく必要があります。Azure Cosmos DBトリガーは削除を含まない挿入・更新を検知する仕組みで、挿入か更新かの区別もトリガー側では返されません。業務ロジックで区別が必要な場合は、アプリ側でタイムスタンプや状態フィールドを設計することが重要です。 (Microsoft Learn)
Azure Cosmos DB trigger for Functions 2.x and higherとは
Azure Cosmos DB trigger for Functions 2.x and higherは、Azure Cosmos DBの変更フィードを監視し、ドキュメントが作成または更新されたときにAzure Functionsを起動するトリガーです。キューやポーリング処理を自前で作り込まずに、Cosmos DBのデータ変更をイベントとして扱える点が大きな特徴です。 (Microsoft Learn)
代表的な活用シーンは次のとおりです。
| 活用シーン | 具体例 | 向いている理由 |
|---|---|---|
| データ連携 | Cosmos DBに登録された注文データを別システムへ連携する | DB更新を起点に非同期処理を開始できる |
| 通知処理 | ユーザー情報の更新後にメールやTeams通知を送る | アプリ本体のレスポンスを重くしにくい |
| 集計・分析 | 変更されたデータを別コンテナーや分析基盤へ反映する | 変更分だけを処理できる |
| キャッシュ更新 | マスターデータ変更後にキャッシュを再生成する | 手動更新漏れを防ぎやすい |
| 監査・履歴処理 | 更新内容を監査ログ用コンテナーへ保存する | 更新イベントを処理の入口にできる |
ただし、Azure Cosmos DBトリガーは万能な変更履歴取得機能ではありません。公式情報では、変更フィードは新規および更新された項目を公開し、削除による更新は含まないとされています。また、トリガーは「挿入されたのか、更新されたのか」を示さず、変更後のドキュメント自体を渡します。削除や操作種別が重要な業務では、論理削除フラグ、createdAt、updatedAt、operationTypeのようなフィールドをアプリケーション側で持つ設計が必要です。 (Microsoft Learn)
何が変わるのか：重要な変更点と確認ポイント
今回の公式情報で特に押さえるべき点は、単なるサンプルコードの更新ではなく、Functions 2.x以降でCosmos DBトリガーを安全に運用するための設定体系が、拡張機能のバージョンや言語モデルごとに整理されていることです。
| 確認項目 | 主な内容 | 実務上の影響 |
|---|---|---|
| 拡張機能4.x以降の設定名 | containerName、connection、leaseContainerNameなどを使用 | 古いcollectionNameやconnectionStringSettingのまま移行すると設定ミスになりやすい |
| マネージドID接続 | 接続文字列ではなくMicrosoft Entra IDベースの接続を利用可能 | シークレット管理の負担を下げられるが、Cosmos DB側のRBAC設定が必須 |
| リースコンテナー | トリガーの処理状態を保持する専用コンテナーが必要 | 作成漏れや共有ミスがあるとトリガーが動かない、または一部関数だけが動く |
| C#実行モデル | インプロセスモデルは2026年11月10日にサポート終了予定 | C#アプリは分離ワーカーモデルへの移行計画が必要 |
| Java関数 | Cosmos DB拡張機能4.xではazure-functions-java-library V3.0.0が必要 | Javaプロジェクトでは依存関係の更新が必要 |
| Node.js / Python | Node.js v4モデル、Python v2デコレーターなど、モデルごとに定義方法が異なる | サンプルを流用する際に、実際のプログラミングモデルを確認する必要がある |
Azure Cosmos DB拡張機能4.x以降では、接続名やコンテナー名などの属性名が変わっています。たとえば、従来のcollectionNameではなくcontainerName、connectionStringSettingではなくconnectionを使う構成が示されています。移行時に古い形式と新しい形式を混在させると、Function Appの起動時やデプロイ後の動作確認で原因を追いにくい不具合になりがちです。 (Microsoft Learn)
C#でインプロセスモデルを使っている場合は、より大きな注意が必要です。Microsoft公式情報では、Azure FunctionsのC#インプロセスモデルは2026年11月10日にサポート終了予定とされ、分離ワーカーモデルへの移行が推奨されています。Cosmos DBトリガーだけでなく、Function App全体の実行モデル移行として計画する必要があります。 (Microsoft Learn)
影響を受けやすい環境
Azure Cosmos DB trigger for Functions 2.x and higherの確認が特に必要なのは、次のような環境です。
| 対象 | 確認すべき理由 |
|---|---|
| 既存のCosmos DBトリガーを拡張機能4.x以降へ上げる環境 | 設定名、バインド型、接続方式が変わる可能性がある |
| C#インプロセスモデルのFunction App | サポート終了に向けて分離ワーカー化が必要 |
| 接続文字列をアプリ設定に保存している環境 | マネージドID化の検討余地がある |
| 同じCosmos DBコンテナーを複数の関数で監視している環境 | リースコンテナーまたはリースプレフィックスの競合に注意 |
| 本番と検証でCosmos DBアカウントやリージョンが異なる環境 | preferredLocationsや接続設定の差異を確認する必要がある |
| Consumptionプランで高頻度に変更を処理する環境 | スケール、接続数、maxItemsPerInvocationの調整が必要になる場合がある |
管理者は、Function Appのアプリ設定、マネージドID、RBAC、リースコンテナー、host.jsonを中心に確認します。開発者は、バインディング定義、関数シグネチャ、バッチ処理、例外処理、挿入・更新の判定ロジックを確認します。どちらか一方だけで完結する変更ではないため、移行や展開時はインフラ担当とアプリ担当のチェックリストを分けておくと安全です。
リースコンテナーは必ず確認する
Azure Cosmos DBトリガーで最も失敗しやすいポイントが、リースコンテナーです。トリガーは監視対象コンテナーとは別に、パーティションごとの処理状態を保存するリース用コンテナーを使用します。監視対象コンテナーとリースコンテナーの両方が利用可能でなければ、トリガーは正しく動作しません。 (Microsoft Learn)
リースコンテナーは、複数のAzure Functionsインスタンス間で「どのインスタンスがどの範囲を処理しているか」を管理するためのものです。スケールアウト時にも重要な役割を持つため、本番環境では「なんとなくleasesという名前で自動作成する」だけではなく、作成場所、パーティションキー、スループット、権限、命名規則を決めておくべきです。
同じコンテナーを複数の関数で監視する場合の注意
同じCosmos DBコンテナーに対して複数のAzure Cosmos DBトリガーを設定する場合、各関数は専用のリースコンテナーを使うか、関数ごとに異なるリースプレフィックスを指定する必要があります。そうしないと、関数のうち1つだけがトリガーされる可能性があります。 (Microsoft Learn)
たとえば、注文コンテナーOrdersを監視して、次の2つの関数を動かしたいケースを考えます。
| 関数 | 目的 | 推奨設定 |
|---|---|---|
SendOrderMail | 注文完了メールを送信 | 専用リースコンテナー、またはmail-のようなリースプレフィックス |
UpdateSalesSummary | 売上集計を更新 | 専用リースコンテナー、またはsummary-のようなリースプレフィックス |
両方が同じleasesコンテナーを同じプレフィックスなしで使うと、意図したように両方の関数が起動しないことがあります。設計段階で「監視対象コンテナー」と「リースコンテナー」をセットで一覧化しておくと、後からの機能追加でも事故を防ぎやすくなります。
マネージドID接続では権限設定が重要
拡張機能4.x以降では、接続文字列だけでなく、マネージドIDを使ったIDベース接続を利用できます。Microsoftの公式情報でも、接続文字列には資格情報が含まれるため、セキュリティ向上の観点からマネージドID接続が推奨されています。 (Microsoft Learn)
ユーザー割り当てマネージドIDを使う場合は、たとえば次のようなアプリ設定を用意します。
{
"COSMOS_CONNECTION__accountEndpoint": "https://example.documents.azure.com:443/",
"COSMOS_CONNECTION__credential": "managedidentity",
"COSMOS_CONNECTION__clientId": "00000000-0000-0000-0000-000000000000"
}この場合、トリガー側ではconnection = "COSMOS_CONNECTION"のように、共通プレフィックスを指定します。ここで重要なのは、アプリ設定の名前そのものです。COSMOS_CONNECTIONという完全一致の設定と、COSMOS_CONNECTION__accountEndpointのようなプレフィックス設定が同時に存在する場合、完全一致の設定が優先されます。移行時に古い接続文字列設定を残したままにすると、意図せず接続文字列側が使われる可能性があります。 (Microsoft Learn)
Azure RBACのOwnerだけでは足りない
Cosmos DBのデータ操作では、一般的なAzure RBACの管理ロールだけでは不十分です。公式情報では、Cosmos DBのデータ操作にはCosmos DB組み込みRBACシステムを使う必要があり、Azure RBACのOwnerなどの管理ロールだけでは十分ではないとされています。Cosmos DBトリガーでは、通常運用の例としてCosmos DB Built-in Data Contributorが示されています。 (Microsoft Learn)
運用で確認すべきポイントは次のとおりです。
| 確認項目 | 判断基準 |
|---|---|
| Function AppにマネージドIDが有効化されているか | システム割り当て、またはユーザー割り当てIDを明確にする |
| Cosmos DB側にデータプレーン権限があるか | Azure RBACのOwnerだけで済ませない |
| 権限スコープが広すぎないか | アカウント全体ではなく、必要な範囲に絞れるか確認する |
| リースコンテナーへの書き込み権限があるか | リース更新ができないとトリガーが安定しない |
| コンテナー自動作成を使っていないか | IDベース接続では事前作成を基本にする |
特に注意したいのは、CreateLeaseContainerIfNotExistsをtrueにしている構成です。IDベース接続では、Cosmos DBのコンテナー作成は管理操作として扱われ、トリガーのデータプレーン操作では利用できません。そのため、マネージドID接続で本番運用する場合は、監視対象コンテナーとリースコンテナーを事前に作成してからFunction Appを展開するのが安全です。 (Microsoft Learn)
function.jsonの移行では設定名の違いに注意
JavaScript、PowerShell、Python v1など、function.jsonでバインディングを定義する構成では、拡張機能のバージョン差による設定名の違いが分かりやすく影響します。
従来形式の例では、collectionNameやleaseCollectionName、connectionStringSettingが使われます。
{
"type": "cosmosDBTrigger",
"name": "documents",
"direction": "in",
"leaseCollectionName": "leases",
"connectionStringSetting": "CosmosDBConnection",
"databaseName": "Tasks",
"collectionName": "Items",
"createLeaseCollectionIfNotExists": true
}拡張機能4.x以降の考え方では、次のようにcontainerName、leaseContainerName、connectionを使います。
{
"type": "cosmosDBTrigger",
"name": "documents",
"direction": "in",
"leaseContainerName": "leases",
"connection": "COSMOS_CONNECTION",
"databaseName": "%COSMOS_DATABASE_NAME%",
"containerName": "%COSMOS_CONTAINER_NAME%",
"createLeaseContainerIfNotExists": false
}本番運用では、データベース名やコンテナー名をコードに直書きせず、%COSMOS_DATABASE_NAME%のようなアプリ設定参照にしておくと、環境差分を管理しやすくなります。公式サンプルでも、アプリ設定参照を使った構成が示されています。 (Microsoft Learn)
C#では分離ワーカーモデルへの移行を前提に考える
C#でAzure Functionsを使っている場合、Cosmos DBトリガーの設定だけでなく、実行モデルも確認が必要です。C#には大きく分けて、Functionsランタイムと同じプロセスで動くインプロセスモデルと、ランタイムから分離されたプロセスで動く分離ワーカーモデルがあります。Microsoftはインプロセスモデルのサポート終了予定を示しているため、今後の改修では分離ワーカーモデルを前提にするのが現実的です。 (Microsoft Learn)
分離ワーカーモデルでのトリガー定義は、次のような形になります。
[Function("CosmosTrigger")]
public void Run(
[CosmosDBTrigger(
databaseName: "%COSMOS_DATABASE_NAME%",
containerName: "%COSMOS_CONTAINER_NAME%",
Connection = "COSMOS_CONNECTION",
LeaseContainerName = "leases",
CreateLeaseContainerIfNotExists = false)]
IReadOnlyList<ToDoItem> documents,
FunctionContext context)
{
foreach (var doc in documents)
{
// ここに業務処理を実装
}
}移行時は、属性名だけでなく、依存パッケージ、ロガー、DI、出力バインド、例外処理の書き方も変わる可能性があります。Cosmos DBトリガーのコードだけを機械的に置き換えるのではなく、Function App全体の移行として検証する必要があります。
Java、Node.js、Pythonで確認すべき点
Javaでは、Azure Cosmos DB拡張機能4.xを使用する場合、azure-functions-java-library V3.0.0が必要とされています。既存プロジェクトで古いライブラリを使っている場合、ビルド設定やアノテーションのプロパティを確認してください。 (Microsoft Learn)
Node.jsでは、公式ドキュメントがNode.jsの複数プログラミングモデルに対応しており、v4モデルはJavaScript / TypeScript開発者向けにより柔軟な体験として一般提供されています。サンプルをコピーする前に、自分のFunction AppがNode.js v3モデルなのかv4モデルなのかを確認することが重要です。 (Microsoft Learn)
Pythonでは、v2プログラミングモデルならデコレーターでバインディングを定義でき、v1プログラミングモデルではfunction.jsonに定義します。Python v2の例では、@app.cosmos_db_triggerにdatabase_name、container_name、connection、lease_container_nameなどを指定します。 (Microsoft Learn)
スケール設定はmaxItemsPerInvocationを軸に確認する
Azure Cosmos DBトリガーは、ConsumptionプランやPremium系プランでスケール判断の対象になります。ターゲットベーススケーリングでは、Azure Cosmos DBの設定としてMaxItemsPerInvocationが関数レベルの属性として扱われ、既定値として100が示されています。 (Microsoft Learn)
MaxItemsPerInvocationは、1回の関数呼び出しで受け取る最大アイテム数を指定する設定です。値を大きくすると1回の処理量は増えますが、関数内の処理時間、メモリ使用量、下流サービスへの負荷も増えます。逆に小さくすると1回の処理は軽くなりますが、呼び出し回数が増えやすくなります。
| ワークロード | 設定の考え方 |
|---|---|
| 1件ごとの処理が軽い | MaxItemsPerInvocationをやや大きめにしてバッチ効率を高める |
| 外部API呼び出しが多い | 下流APIのレート制限を見ながら小さめにする |
| 処理時間が長い | タイムアウトやリトライを考慮し、小さめから検証する |
| 変更量が急増する | スケールアウト上限、物理パーティション数、下流サービス負荷を合わせて確認する |
Azure Cosmos DBはパーティション化されたワークロードであるため、ターゲットインスタンス数は物理パーティション数の影響を受けます。単純にFunction Appの最大スケール数を上げれば処理が無限に速くなるわけではありません。 (Microsoft Learn)
host.jsonで確認する接続モードとログ設定
Cosmos DBトリガーの高度な構成では、host.jsonも重要です。公式情報では、Cosmos DBバインドのhost.json設定としてconnectionModeやuserAgentSuffixが示されています。connectionModeの既定はGatewayで、DirectはTCP経由で接続し低レイテンシを狙える一方、接続数が増えやすい点に注意が必要です。 (Microsoft Learn)
例として、監視で識別しやすいユーザーエージェントを付ける場合は次のように設定します。
{
"version": "2.0",
"extensions": {
"cosmosDB": {
"connectionMode": "Gateway",
"userAgentSuffix": "order-functions-prod"
}
}
}高性能化を狙ってDirect / Tcpを使う場合は、プランの制限を確認してください。公式情報では、Consumptionプランでは各インスタンスが維持できるソケット接続数に制限があり、Direct/TCPモードでは接続数が増えて制限に達する可能性があるため、Gatewayモードに戻す、Premiumプランや専用プランを使うといった選択肢が示されています。 (Microsoft Learn)
トラブルシューティングでは、Host.Triggers.CosmosDBカテゴリのログを有効化すると、変更フィード処理、リース取得、負荷分散、接続問題などを追跡しやすくなります。Application Insightsでログを確認する場合も、このカテゴリを基準に絞り込むと調査しやすくなります。 (Microsoft Learn)
展開前チェックリスト
本番展開前には、次の順序で確認すると抜け漏れを減らせます。
| 手順 | 確認内容 | 担当の目安 |
|---|---|---|
| 1 | 現在のFunctionsランタイム、Cosmos DB拡張機能、言語モデルを確認する | 開発者 |
| 2 | function.jsonや属性の設定名を拡張機能のバージョンに合わせる | 開発者 |
| 3 | 監視対象コンテナーとリースコンテナーを一覧化する | 開発者・管理者 |
| 4 | リースコンテナーのパーティションキー、RU、命名規則を確認する | 管理者 |
| 5 | 接続文字列からマネージドIDへ移行するか判断する | 管理者 |
| 6 | Cosmos DB組み込みRBACの権限を付与する | 管理者 |
| 7 | CreateLeaseContainerIfNotExistsを本番で使うか見直す | 管理者 |
| 8 | MaxItemsPerInvocationとスケール上限を検証する | 開発者・管理者 |
| 9 | Application InsightsとHost.Triggers.CosmosDBログを確認する | 管理者 |
| 10 | ステージング環境で挿入・更新・大量更新・リトライをテストする | 開発者 |
特に本番環境では、CreateLeaseContainerIfNotExistsを安易にtrueにするより、IaCやデプロイスクリプトでリースコンテナーを明示的に作成する方が安全です。環境ごとの差分を減らせるうえ、権限不足でFunction Appが起動しない問題も見つけやすくなります。
よくある失敗と対処法
| 症状 | よくある原因 | 対処 |
|---|---|---|
| トリガーが起動しない | リースコンテナーが存在しない、または接続できない | 監視対象コンテナーとリースコンテナーの両方を確認する |
| 一部の関数だけ起動する | 同じコンテナーを複数関数で監視し、同じリースを共有している | 関数ごとにリースコンテナーまたはリースプレフィックスを分ける |
| マネージドIDで接続できない | Azure RBACのOwnerだけを付与している | Cosmos DB組み込みRBACのデータ権限を付与する |
| デプロイ後に古い接続文字列が使われる | connection名と完全一致する古いアプリ設定が残っている | 完全一致設定とプレフィックス設定を整理する |
| リースコンテナーを自動作成できない | IDベース接続でCreateLeaseContainerIfNotExistsを使っている | リースコンテナーを事前作成する |
| 削除イベントが処理されない | 変更フィードが削除を含まない前提で設計されていない | 論理削除や状態フィールドを設計する |
| 挿入と更新を区別できない | トリガーが操作種別を返さない | createdAt、updatedAtなどを持たせる |
startFromBeginningが効かない | 既にリースが作成されチェックポイントが保存されている | 再処理用に別リースコンテナーや別プレフィックスを使う |
startFromBeginningは、変更履歴の最初から読み始めるための設定ですが、初回起動時にのみ意味があります。すでにリースが作成されている場合、チェックポイントが保存されているため、後からtrueにしても期待どおりに再処理されません。再処理や検証をしたい場合は、既存リースに影響しない別のリースコンテナーやリースプレフィックスを使う設計が現実的です。 (Microsoft Learn)
開発者が実装時に意識すべき設計ポイント
Azure Cosmos DBトリガーの実装では、関数が起動することだけを確認して終わらせないことが重要です。実務では、次の観点を最初から設計に入れておくと、運用後のトラブルを減らせます。
処理は冪等にする
Cosmos DBトリガーに限らず、イベント駆動処理では、同じデータが再処理されても業務上の不整合が起きないように設計することが重要です。たとえば、通知送信済みフラグ、処理履歴ID、外部連携のリクエストIDなどを使い、重複実行に備えます。
例外でバッチ全体を止めない
複数ドキュメントをバッチで受け取る場合、1件の処理エラーで全体が止まると、後続の正常データまで処理できません。公式サンプルでも、各ドキュメント処理内で例外を捕捉し、残りのドキュメント処理を継続する考え方が示されています。 (Microsoft Learn)
下流サービスの負荷を考える
Cosmos DB側の変更量が増えたとき、Functionsはスケールして処理を増やせます。しかし、メール配信API、外部SaaS、別DBなどの下流サービスが同じ速度で処理できるとは限りません。MaxItemsPerInvocation、Function Appのスケール上限、キューの併用、レート制限を組み合わせて設計しましょう。
削除を検知したい場合は論理削除を検討する
通常のAzure Cosmos DBトリガーでは削除を直接の処理対象として期待しない方が安全です。削除時に後続処理が必要な場合は、物理削除ではなくisDeleted: trueのような論理削除にして、その更新をトリガーで処理する設計が実務では扱いやすくなります。
管理者と開発者が次に取るべき行動
Azure Cosmos DB trigger for Functions 2.x and higherを使っている、またはこれから使う場合は、まず現在のFunction Appを棚卸ししてください。確認する順番は、拡張機能のバージョン、言語モデル、接続方式、リースコンテナー、スケール設定です。
既存環境では、古いcollectionName系の設定が残っていないか、同じリースコンテナーを複数関数で競合させていないか、接続文字列をいつまで使い続けるのかを確認します。新規構築では、拡張機能4.x以降、マネージドID、事前作成したリースコンテナー、監視ログ、冪等な処理設計を標準にすると、後からの移行負担を抑えられます。
最後に、C#インプロセスモデルを使っている場合は、Cosmos DBトリガーの修正だけでなく、分離ワーカーモデルへの移行計画を早めに立ててください。設定名の置き換え、権限付与、リース設計、スケール検証を一体で進めることが、Azure FunctionsとAzure Cosmos DBを安定して運用するための近道です。
コメント