--- title: "Azure Cosmos DB エミュレーターの使い方｜vNextのDocker起動とWindows版の選び方" url: "https://www.issoh.co.jp/tech/details/6259/" published: 2025-04-11 updated: 2026-09-27 categories: ["Azure"] publisher: "株式会社一創" --- # Azure Cosmos DB エミュレーターの使い方｜vNextのDocker起動とWindows版の選び方 Azure Cosmos DB エミュレーターは、Azureのサブスクリプションも課金も無しにCosmos DBをローカルで動かすための開発用ツールです。現在は「Windows版」「旧Linux版（Docker）」「vNext（Docker）」の3系統が並んでおり、どれを選ぶかで対応APIや動くCPU、CIでの組み方が変わります。この記事では、2026年9月時点のMicrosoft Learnとコンテナレジストリの内容をもとに、系統ごとの違いから起動・接続の手順、CIへの組み込み方までを説明します。 ## まとめ｜Cosmos DB エミュレーターの選び方と要点 - **Mac（Apple Silicon）やARMマシンで使うならvNext一択**です。イメージは `mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest` で、2026年6月2日にGAが発表され、x64とARM64の両方で動きます。 - vNextが対応するのはAPI for NoSQLのゲートウェイモードだけです。MongoDB・Cassandra・Gremlin・TableのAPIを試すならWindows版、MongoDB APIだけなら旧Linux版の `mongodb` タグを使います。 - vNextは既定でHTTPで起動します。.NETとJavaのSDKはHTTPモードに対応していないため、`--protocol https` を付けて起動します。 - エンドポイントは `localhost:8081`、キーは既定では共通の公開キーで、起動時に独自キーを指定することもできます。エミュレーターは開発・テスト用で、本番用途には適しません。 - RUの計測、ストアドプロシージャ・トリガー・UDF、カスタムインデックスの効果はvNextでは確認できません。これらの確認はクラウドのアカウントで行います。 - GitHub Actionsでは、`windows-latest` ランナーにWindows版が入っているほか、`ubuntu-latest` ではvNextをサービスコンテナとして起動できます。 ## エミュレーター3系統の違いと選び方 Microsoft Learnの[エミュレーター概要](https://learn.microsoft.com/ja-jp/azure/cosmos-db/emulator)・[Linuxベースのエミュレーター（vNext）](https://learn.microsoft.com/ja-jp/azure/cosmos-db/emulator-linux)と、Microsoft Artifact Registry（MCR）のタグ一覧を突き合わせると、2026年9月時点で配布されている系統は次の3つです。 | 項目 | Windows版（ローカル） | 旧Linux版（Docker） | vNext（Docker） | | ------------- | ------------------------------------- | ---------------------------------- | --------------------- | | 入手先 | aka.ms/cosmosdb-emulator（MSI） | :latest / :mongodb タグ | :vnext-latest タグ | | CPU | x64（Windows） | amd64のみ | amd64・arm64 | | 対応API | NoSQL・MongoDB・Cassandra・Gremlin・Table | NoSQL・MongoDB | NoSQLのみ | | 接続モード | ゲートウェイ・直接 | ゲートウェイ・直接 | ゲートウェイのみ | | 既定のプロトコル | HTTPS | HTTPS | HTTP | | Data Explorer | https://localhost:8081/\_explorer/ | https://localhost:8081/\_explorer/ | http://localhost:1234 | 選び方の基準は「動かすマシン」と「使うAPI」の2つです。公式の概要ページには「Linuxベースのエミュレーターは、Apple siliconやMicrosoftのARMチップを搭載した開発マシンをサポートしない」という注意書きがあります。これは旧Linux版の話で、MCRの `latest` タグは現在もamd64のマニフェストしか持っていません。一方、`vnext-latest` はamd64とarm64のマルチアーキテクチャイメージです。Apple SiliconでNoSQLをローカル開発する場合はvNextを選びます。ただし、Intel MacでMongoDB APIを検証する場合など、旧Linux版が選択肢になる用途もあります。 Cassandra・Gremlin・Tableのエンドポイントを起動できるのはWindows版だけで、Docker版はこの3つに非対応と明記されています。 ## vNextをDockerで起動する手順 ### docker runの基本形とポート8081・8080・1234 公式ドキュメントどおりの起動コマンドは次のとおりです。以降のHTTPS版・永続化版は別の起動例なので、切り替える前に、この例で起動したコンテナを停止して同じホストポートを空けてください。 ``` docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest docker run --detach \ --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 \ mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest ``` 3つのポートはそれぞれ役割が違います。 - **8081**：Cosmos DBのゲートウェイエンドポイント（SDKの接続先） - **8080**：ヘルスプローブ。`/alive`・`/ready`・`/status` の3つを返します - **1234**：Data Explorer（ブラウザで開く管理画面） 起動完了の判定には、ログの「System is now fully ready to accept requests」ではなく `http://localhost:8080/ready` を使います。このログ文言は互換性のために残されているだけで、将来削除される可能性があると公式に書かれています。Data Explorerはゲートウェイより数秒遅れて立ち上がります。 ### HTTPSモードと証明書の扱い vNextは既定でHTTPで起動します。PythonやNode.jsのSDKは `http://localhost:8081` にそのまま接続できますが、.NETとJavaのSDKはHTTPモードに対応していません。この2言語で使う場合は起動引数でHTTPSに切り替えます。 ``` docker run --detach \ --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 \ mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest --protocol https ``` Javaではさらに、エミュレーターの自己署名証明書をJDKのトラストストアに登録する必要があります。`openssl s_client -connect localhost:8081 cosmos_emulator.cert` で証明書をファイルに保存し、`keytool -cacerts -importcert -alias cosmos_emulator -file 証明書ファイル` で取り込みます（パスワードの既定値は `changeit`）。データボリュームを永続化したままHTTPSで起動すると、証明書は起動のたびに自動で再生成されます。 旧Linux版は証明書を `https://localhost:8081/_explorer/emulator.pem` で配布しています。`curl --insecure` で取得し、Ubuntuなら `update-ca-certificates`、Windowsなら `certutil -f -addstore "Root"` で登録するのが公式の手順です。 ### vNextの設定項目とデータの永続化 vNextの設定は起動引数か環境変数で渡します。よく使うものを抜き出しました。 | 環境変数 | 引数 | 既定値 | 用途 | | ----------------------- | ------------------ | ----- | ----------------------------- | | PROTOCOL | –protocol | http | http / https / https-insecure | | PORT | –port | 8081 | ゲートウェイのポート | | DATA\_PATH | –data-path | /data | データの保存先 | | KEY\_FILE | –key-file | 固定キー | 独自キーをファイルで指定 | | ENABLE\_EXPLORER | –enable-explorer | true | Data Explorerの起動 | | QUERY\_BUFFER\_SIZE\_KB | –query-buffer-size | 4096 | クエリ結果バッファ（最大65536） | | ENABLE\_INIT\_DATA | –enable-init-data | false | 起動時にシードスクリプトを実行 | | ENABLE\_TELEMETRY | –enable-telemetry | true | Microsoftへの利用データ送信 | コンテナを止めてもデータを残すには、ホストのディレクトリを `/data` にマウントします。 ``` mkdir -p ./cosmos-data docker run --rm -p 8081:8081 \ -v "$(pwd)/cosmos-data:/data" \ mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest ``` `ENABLE_INIT_DATA=true` を付けると、`/init` 直下の `.csh` ファイルが名前順に実行され、データベース・コンテナ・初期データを作ってからリクエストを受け付けます。ファイル名に `01-` のような連番を付けて順序を固定し、既に `/data` にデータがあれば初期化は省略されます。検索でよく引かれる `AZURE_COSMOS_EMULATOR_PARTITION_COUNT`・`AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE`・`AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE` は**旧Linux版の環境変数**で、vNextの設定表には載っていません。vNextで永続化したい場合は、これらではなく上記のマウントを使います。 ## Windows版のインストールと起動オプション ### Windows版のダウンロード先と配布バージョン Windows版は `https://aka.ms/cosmosdb-emulator` からMSIを取得してインストールします。対応OSは64ビット版のWindows 10・Windows 11・Windows Server 2019で、RAM 2GBと空きディスク10GBが最低要件です。インストール先は `%ProgramFiles%\Azure Cosmos DB Emulator` で、スタートメニューから起動すると `https://localhost:8081/_explorer/index.html` のData Explorerが開きます。ローカル版は証明書を自動でインポートするため、追加の設定は不要です。 バージョンの確認では注意が必要です。公式リリースノートの「Latest version」は2024年11月18日の `2.14.21` のまま更新されていません。一方、同じ `aka.ms/cosmosdb-emulator` からMSIを入れているGitHubホストランナーのイメージ一覧（windows-2025／windows-2022、2026年9月7日版）には「Azure CosmosDb Emulator 2.14.28.0」と記載されています。サポート対象は最新版だけと明記されているので、リリースノートの番号ではなく、配布元から取得した実物のバージョンで判断してください。 ### コマンドライン引数とPowerShellモジュール 実行ファイル `Microsoft.Azure.Cosmos.Emulator.exe` に引数を渡すと、起動方法を変えられます（全引数は[Windowsエミュレーターのコマンドライン リファレンス](https://learn.microsoft.com/ja-jp/azure/cosmos-db/emulator-windows-arguments)を参照）。CIや検証でよく使うのは次の引数です。 | 引数 | 内容 | | -------------------------- | ---------------------------- | | /NoUI、/NoExplorer | トレイUIとData Explorerを開かない | | /GetStatus | 終了コード 1=起動中 2=稼働中 3=停止 | | /Shutdown | エミュレーターを停止 | | /Port=65000 | NoSQLのポート変更（既定8081） | | /PartitionCount=N | パーティション分割コンテナの上限（既定25・最大250） | | /EnableMongoDbEndpoint=4.0 | MongoDB API（3.2 / 3.6 / 4.0） | | /EnableCassandraEndpoint | Cassandra API（既定ポート10350） | | /EnableGremlinEndpoint | Gremlin API（既定ポート8901） | | /EnableTableEndpoint | Table API（既定ポート8902） | | /Consistency=Strong | 既定の整合性レベル（既定Session） | | /ResetDataPath | データフォルダを初期化 | スクリプトから扱う場合は、同梱のPowerShellモジュールを読み込みます。`Start-CosmosDbEmulator` は既定で受付可能になるまで待機し、`-NoWait` を付けると起動直後に戻ります。 ``` Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator" Start-CosmosDbEmulator -NoUI Get-CosmosDbEmulatorStatus ``` データの保存先は既定で `%LOCALAPPDATA%\CosmosDBEmulator` です。コンテナが壊れた、パーティション数を変えたい、といった場合は `/ResetDataPath` で初期化してから起動し直します。保存済みのデータはすべて消えるため、必要なデータは先に退避してください。 ## SDKからの接続と固定キー エミュレーターには固定のアカウントが1つだけ用意されており、既定ではこの資格情報以外では接続できません。 ``` エンドポイント: https://localhost:8081/ キー: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== ``` このキーは公開情報ですが、コードに直接書くと本番の接続先との切り替えで事故が起きやすくなります。接続文字列は環境変数から読み込みます。次のコードは、MicrosoftのGitHub Actions用サンプル（Python）と同じ書き方です。 ``` import os from azure.cosmos import CosmosClient, PartitionKey # vNext（HTTP）の例: # AccountEndpoint=http://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== client = CosmosClient.from_connection_string(os.environ["COSMOSDB_CONNECTION_STRING"]) database = client.create_database_if_not_exists(id="appdb") container = database.create_container_if_not_exists( id="users", partition_key=PartitionKey(path="/id"), ) container.upsert_item({"id": "42", "email": "user42@example.com"}) ``` HTTPS版（旧Linux版・Windows版・vNextのHTTPS起動）に接続するとき、証明書を登録していないとSSLエラーになります。SDKの検証を無効にする前に、上の手順で証明書を登録してください。Pythonの仮想環境では、OSの証明書ストアではなく `certifi` の `cacert.pem` が参照されている場合があります。vNextはゲートウェイモードしか提供しないため、.NETやJavaのSDKで直接モードを既定にしている場合は、接続モードをゲートウェイに変更してください。Cosmos DBのデータ操作そのものは[Azure Cosmos DBで行うCRUD操作](/tech/details/7511/)で詳しく扱っています。 ## クラウド版との差分とエミュレーターで検証できないこと エミュレーターで通ったテストが、クラウドでも同じように動くとは限りません。公式ドキュメントが挙げている差分は次のとおりです。 - **スループットはプロビジョニング型のみ**で、サーバーレスは再現できません。 - インスタンスは1つだけで、複数リージョンへのレプリケーションやスケールアウトはできません。 - Windows版は、400 RU/sの固定サイズコンテナなら10個、無制限サイズなら5個までを想定しています。これを超えても作成はできますが、性能が落ちることがあります。 - Windows版の整合性レベルはSessionとStrongだけで、しかも実際の整合性制御は行わず、設定値を記録するだけです。 - Windows版ではアイテムのidが254文字までに制限されます。1クエリあたりのJOINは最大5つです。 vNextはさらに対応範囲が狭くなります。機能表を見ると、**Request Units**・コンテナのスループット取得／変更・パーティションをまたぐ並列クエリは「未実装」です。**ストアドプロシージャ・トリガー・UDF**は「対応予定なし」となっています。カスタムインデックスポリシーとコンテナ更新は「No-op」で、リクエストは成功を返しますが、実際には何も実行されません。インデックスポリシーを書き換えても、クエリは速くなりません。既知の制限として、.NET SDKのバルク実行にも対応していません。 検証内容に応じて、vNext・Windows版・クラウドを次のように使い分けます。 - **RU消費量の見積もりやパーティションキー設計の性能評価**：vNextはRUを返さず、Windows版もクラウドの物理パーティション構成を再現しません。 - **ストアドプロシージャに依存する処理のテスト**：vNextでは動かないため、Windows版かクラウドで確認します。 - **整合性レベルの違いによる挙動の検証**：エミュレーターは設定値を記録するだけで、実際の整合性制御は行いません。 これらは、検証用のCosmos DBアカウントで確かめます。RU課金やAPIの選び方は[Azure Cosmos DB for NoSQLとは｜API選定・RU料金・整合性・ベクトル検索](/tech/details/4678/)にまとめています。 ## CI/CDパイプラインでの使い方 ### GitHub Actions（ubuntuのサービスコンテナとwindows-latest） Linuxランナーでは、vNextをサービスコンテナにすると、コンテナの起動とジョブ終了時の破棄をGitHub Actionsに任せられます。Microsoftの公式サンプル（[AzureCosmosDB/cosmosdb-linux-emulator-github-actions](https://github.com/AzureCosmosDB/cosmosdb-linux-emulator-github-actions)）は、`ubuntu-latest` と `ubuntu-24.04-arm` のマトリクスでこの構成を採用しています。以下のLinux版・Windows版のYAMLはジョブ部分の抜粋です。使用する方を `.github/workflows/test.yml` に保存し、最上位に `on: [push, pull_request]` を追加します。Linux版には `/ready` の待機処理を加えています。実行対象のpytestまたは.NETのテストは、リポジトリに用意しておきます。 ``` jobs: test: runs-on: ubuntu-latest services: cosmosdb: image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest ports: - 8081:8081 - 8080:8080 env: COSMOSDB_CONNECTION_STRING: "AccountEndpoint=http://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==" steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - name: Wait for emulator run: | for i in $(seq 1 60); do curl -sf http://localhost:8080/ready && exit 0 sleep 2 done exit 1 - run: pip install azure-cosmos pytest - run: pytest -v ``` サービスコンテナには、`services.cosmosdb.command` で起動引数を渡せます。.NETやJavaでHTTPSが必要な場合は、`services.cosmosdb.env` に `PROTOCOL: https` を指定します。サービスコンテナはLinuxランナー専用なので、Windowsランナーでは使えません。 Windows版を使う場合は、`windows-latest` に最初から入っているエミュレーターをPowerShellで起動します。 ``` jobs: test: runs-on: windows-latest steps: - uses: actions/checkout@v4 - name: Start Azure Cosmos DB emulator run: | Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator" Start-CosmosDbEmulator - run: dotnet test ``` 上の例はNoSQL用です。MongoDB・Gremlin・Table APIをテストする場合は、起動コマンドにそれぞれ `-EnableMongoDb`・`-EnableGremlin`・`-EnableTable` を付けて対象APIを有効にします。NoSQLのストアドプロシージャを含むテストもWindows版で実行できます。 ### Azure DevOps（ビルドタスク廃止後の構成） Azure DevOpsのCosmos DB Emulatorビルドタスクは、Windows 2016ホストエージェントが2022年4月1日に削除された時点でサポートが終わっています。公式チュートリアルでは代わりに、`windows-2019` エージェントでPowerShellタスクを実行する方法を案内しています。ただし、Azure Pipelinesの `windows-2019` イメージは2025年12月31日に退役済みで、チュートリアルのYAMLをそのまま使うと動きません。 現在は `vmImage: windows-2022` または `windows-2025` を指定し、PowerShellタスクで `Start-CosmosDbEmulator -NoFirewall -NoUI` を実行します。Microsoftホストエージェントのイメージは、GitHub Actionsと同じ actions/runner-images リポジトリで作られています。両イメージのソフトウェア一覧には、どちらもエミュレーター2.14.28.0が記載されています。セルフホストエージェントの場合は、`aka.ms/cosmosdb-emulator` のMSIを `msiexec` でサイレントインストールしてから、同じスクリプトを実行します。 ### Testcontainersの言語別モジュールと既定イメージ テストコードの中でコンテナを起動・破棄したい場合は、Testcontainersのモジュールが使えます。2026年9月時点の配布物で確認したクラス名は次のとおりです。 | 言語 | パッケージ（版） | クラス | | ------ | ---------------------------------------------- | ----------------------------------- | | .NET | Testcontainers.CosmosDb（4.15.0） | CosmosDbBuilder / CosmosDbContainer | | Java | org.testcontainers:testcontainers-azure（2.0.5） | CosmosDBEmulatorContainer | | Python | testcontainers\[cosmosdb\]（4.15.0） | CosmosDBNoSQLEndpointContainer | Python版の既定イメージは旧Linux版の `azure-cosmos-emulator:latest`（amd64のみ）で、環境変数 `AZURE_COSMOS_EMULATOR_IMAGE` で差し替えられます。Apple Silicon上では既定イメージがネイティブに動かない点に注意してください。Testcontainers全般の仕組みと2.0系の移行点は[Testcontainersとは？Dockerで作る使い捨てテスト環境と2.0系の移行点](/tech/details/4629/)を参照してください。 ## 起動・接続トラブルの原因と対処 - **Macで旧イメージが起動しない、または極端に遅い**：`:latest` はamd64専用です。`:vnext-latest` に切り替えます。 - **.NET／JavaのSDKがvNextに接続できない**：`--protocol https` を付けて起動し直します。直接モードを使う設定になっていれば、ゲートウェイモードに変更します。 - **SSL証明書エラー**：証明書をOSやランタイムのストアに登録します（手順はHTTPSモードの節を参照）。 - **大きなクエリでHTTP 500が返る**：vNextの `QUERY_BUFFER_SIZE_KB`（既定4096、最大65536）を増やします。 - **テスト開始直後だけ接続に失敗する**：起動完了を待たずにテストが走っています。`http://localhost:8080/ready` が200を返すまで待機します。 - **Windows版でコンテナを作りすぎて遅い、または作成に失敗する**：`/PartitionCount` を見直し、`/ResetDataPath` で初期化してから起動し直します。初期化すると保存済みデータは消えます。 ## よくある質問 ### Azure Cosmos DB エミュレーターはMac（M1/M2/M3）で使えますか？ vNext（`vnext-latest` タグ）なら使えます。arm64のイメージが提供されており、Docker Desktopなどでそのまま起動できます。旧Linux版の `latest` タグはamd64専用のため、Apple Siliconでは使えません。Docker Desktopの導入は[Docker Desktopの導入手順とライセンス境界](/tech/details/17442/)を参照してください。 ### エミュレーターの利用は無料ですか？ 無料です。Azureのサブスクリプションを作らずに、ローカルで開発とテストができます。ただし、エミュレーターは本番ワークロードでの利用が推奨されていません。 ### コンテナを停止するとデータは消えますか？ vNextは、`docker run --rm` で起動したままコンテナを止めるとデータが消えます。残したい場合は、ホストのディレクトリを `/data` にマウントします。Windows版は `%LOCALAPPDATA%\CosmosDBEmulator` にデータを保存します。 ### エミュレーターのキーは変更できますか？ 起動中のエミュレーターではキーを再生成できません。別のキーを使う場合は、起動時に指定します。Windows版は `/Key` や `/KeyFile`、vNextは `KEY_FILE` で指定します。Windows版でネットワーク越しにアクセスさせる `/AllowNetworkAccess` を使う場合は、キーの指定が必須です。 ### エミュレーターでRU（要求ユニット）を計測できますか？ vNextでは、Request Unitsは未実装です。RU消費量の見積もりは、検証用のCosmos DBアカウントで行ってください。 ## 関連記事 - [Azure Cosmos DB for NoSQLとは｜API選定・RU料金・整合性・ベクトル検索](/tech/details/4678/) - [Azure Cosmos DBで行うCRUD操作：データの挿入・取得・更新・削除の方法](/tech/details/7511/) - [Testcontainersとは？Dockerで作る使い捨てテスト環境と2.0系の移行点](/tech/details/4629/) - [Docker Desktopの導入手順とライセンス境界｜4.89系の要件と無料代替](/tech/details/17442/) - [LocalStackとは？AWSをローカルで動かす手順と有料化後の料金・判断基準](/tech/details/17634/) --- 出典: [Azure Cosmos DB エミュレーターの使い方｜vNextのDocker起動とWindows版の選び方]()（株式会社一創）