Windows (ローカル) エミュレーターのコマンドラインと PowerShell リファレンス

[アーティクル]
09/13/2023

適用対象: NoSQL MongoDB Cassandra Gremlin Table

Azure Cosmos DB エミュレーターは、ローカル開発目的で Azure Cosmos DB サービスをエミュレートするローカル環境を提供します。エミュレーターのインストール後、コマンドラインと PowerShell コマンドでエミュレーターを制御できます。この記事では、コマンドラインと PowerShell コマンドを使用してエミュレーターを起動、停止し、オプションを構成し、その他の操作を実行する方法について説明します。インストール場所からコマンドを実行する必要があります。

重要

この記事には、Windows ローカルエミュレーターのコマンドライン引数のみが含まれています。

コマンドライン構文を使用してエミュレーターを管理する

Microsoft.Azure.Cosmos.Emulator.exe 
    [/Shutdown] [/DataPath] [/Port] [/MongoPort] 
    [/DirectPorts] [/Key] [/EnableRateLimiting] 
    [/DisableRateLimiting] [/NoUI] [/NoExplorer] 
    [/EnableMongoDbEndpoint] 
    [/?]

パラメーターの一覧を表示するには、コマンドプロンプトで「Microsoft.Azure.Cosmos.Emulator.exe /?」と入力します。

パラメーター	説明	コマンドの例
[引数なし]	既定の設定でエミュレーターを起動します。	Microsoft.Azure.Cosmos.Emulator.exe
[Help]	サポートされるコマンドライン引数の一覧を表示します。	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	エミュレーターの状態を取得します。各終了コードは、`1` = 開始中、`2` = 実行中、`3` = 停止済みの状態を示します。負の終了コードは、エラーが発生したことを示します。その他の出力は生成されません。	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	エミュレーターをシャットダウンします。	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	データファイルを格納するパスを指定します。既定値は `%LocalAppdata%\CosmosDBEmulator` です。	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	エミュレーターで使用するポート番号を指定します。既定値は `8081` です。	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	コンピューティング相互運用ゲートウェイサービスに使用するポート番号を指定します。ゲートウェイの HTTP エンドポイントプローブポートのポート番号は、`ComputePort + 79` を加えた値として計算されます。このため、`ComputePort` と `ComputePort + 79` は、開いて利用可能な状態にしておく必要があります。既定値は `8900` です。	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	MongoDB バージョン 3.2 の API を有効にします。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	MongoDB バージョン 3.6 の API を有効にします。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	MongoDB バージョン 4.0 の API を有効にします。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	MongoDB 用 API で使用するポート番号を指定します。既定値は `10255` です。	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	Apache Cassandra 用 API を有効にします。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	Cassandra エンドポイント用 API で使用するポート番号を指定します。既定値は `10350` です。	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	Apache Gremlin 用 API を有効にします。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	Apache Gremlin エンドポイント用 API に使用するポート番号です。既定値は `8901` です。	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	Table 用 API を有効にします。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	Table エンドポイント用 API に使用するポート番号です。既定値は `8902` です。	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	指定されたファイルから承認キーを読み取ります。キーファイルの生成には、`/GenKeyFile` オプションを使用します。	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	指定されたパスにある全部のファイルを、再帰的に削除します。パスを指定しない場合、既定値は `%LOCALAPPDATA%\CosmosDbEmulator` です。	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	LOGMAN を使用して、デバッグトレースログの収集を開始します。	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	LOGMAN を使用して、デバッグトレースログの収集を停止します。	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	Windows パフォーマンス記録ツールを使用したデバッグトレースログの収集を開始します。	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	Windows パフォーマンス記録ツールを使用したデバッグトレースログの収集を停止します。	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	証明書の SAN にエミュレーターのホストのドメイン名、ローカル IP アドレス (v4)、`localhost`、および `127.0.0.1` が含まれていない場合、既定では、エミュレーターにより自己署名 TLS/SSL 証明書が再生成されます。このオプションを設定すると、その代わりにエミュレーターが起動に失敗します。その後は `/GenCert` オプションを使って新しい自己署名 TLS/SSL 証明書を作成およびインストールする必要があります。	`Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch`
`GenCert`	新しい自己署名 TLS/SSL 証明書を生成およびインストールします。オプションで、ネットワーク経由でエミュレーターにアクセスするための追加の DNS 名を列挙したコンマ区切りリストを含めることもできます。	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	直接接続に使用するポートを指定します。既定値は、`10251`、`10252`、`10253`、および `10254` です。	`Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700`
`Key`	エミュレーターの承認キーです。キーは、64 バイトベクトルの Base 64 エンコーディングが施されている必要があります。	`Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`EnableRateLimiting`	要求レート制限の動作の有効化を指定します。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	要求レート制限の動作の無効化を指定します。	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	エミュレーターのユーザーインターフェイスを表示しません。	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	起動時にデータエクスプローラーを表示しません。	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	パーティション分割されたコンテナーの最大数を指定します。詳細については、「コンテナーの数を変更する」を参照してください。既定値は `25` です。最大許容値は `250` です。	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	パーティション分割されたコンテナーの既定のパーティション数を指定します。既定値は `25` です。	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	ネットワーク上でのエミュレーターへのアクセスを有効にします。ネットワークアクセスを有効にするには、`/Key=<key_string>` または /`KeyFile=<file_name>` も渡す必要があります。	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	`/AllowNetworkAccess` オプションが使用されているときは、ファイアウォール規則を調整しないでください。	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	新しい承認キーを生成し、指定したファイルに保存します。生成されたキーは、`/Key` または `/KeyFile` オプションで使用できます。	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	アカウントの既定の一貫性レベルを設定します。既定値は Session です。	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	ヘルプメッセージを表示します。

PowerShell コマンドレットでエミュレーターを管理する

エミュレーターには、サービスの開始、停止、アンインストール、状態の取得のための PowerShell モジュールが付属しています。この PowerShell モジュールを使用するには、次のコマンドレットを実行します。

Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"

このほか、PSModulePath に PSModules ディレクトリを追加したうえで、次のコマンドを使用してインポートする方法もあります。

$env:PSModulePath += ";$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules"
Import-Module Microsoft.Azure.CosmosDB.Emulator

PowerShell からエミュレーターを制御するためのコマンドの概要を次に示します。

`Get-CosmosDbEmulatorStatus`

エミュレーターの状態を取得します。 ServiceControllerStatus 値は次のいずれかを返します。

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

エラーが発生した場合、値は返されません。

構文

Get-CosmosDbEmulatorStatus 
    [[-AlternativeInstallLocation] <String>] 
    [<CommonParameters>]

パラメーター

名前	Type	説明
`AlternativeInstallLocation`	`String`

例

D:\SomeFolder\AzureCosmosDBEmulator フォルダーにインストールされているエミュレーターの状態を取得します。
```
@parameters = {
    AlternativeInstallLocation = "D:\SomeFolder\AzureCosmosDBEmulator"
}
Get-CosmosDbEmulatorStatus @parameters
```

`Start-CosmosDbEmulator`

ローカルコンピューターでエミュレーターを起動します。既定では、このコマンドは、エミュレーターで要求を受け付ける準備ができるまで待ちます。エミュレーターを起動したらすぐにコマンドレットから戻るようにする場合は、-NoWait オプションを使用します。 NoSQL ポート、ダイレクトポート、MongoDB ポート番号などのオプションを指定するには、Start-CosmosDbEmulator のパラメーターを使用します。

構文

Start-CosmosDbEmulator [-AllowNetworkAccess]
    [-AlternativeInstallLocation <String>] [-CassandraPort <UInt16>]
    [-ComputePort <UInt16>] [-Consistency <String>] [-Credential
    <PSCredential>] [-DataPath <String>] [-DefaultPartitionCount
    <UInt16>] [-DirectPort <UInt16[]>] [-EnableMongoDb]
    [-EnableCassandra] [-EnableGremlin] [-EnableTable]
    [-EnableSqlCompute] [-EnablePreview]
    [-FailOnSslCertificateNameMismatch] [-GremlinPort <UInt16>]
    [-TablePort <UInt16>] [-SqlComputePort <UInt16>] [-Key <String>]
    [-MongoPort <UInt16>] [-MongoApiVersion <String>] [-NoFirewall]
    [-NoTelemetry] [-NoUI] [-NoWait] [-PartitionCount <UInt16>] [-Port
    <UInt16>] [-SimulateRateLimiting] [-Timeout <UInt32>] [-Trace]
    [<CommonParameters>]

パラメーター

名前	Type	説明
`AllowNetworkAccess`	`SwitchParameter`	エミュレータのホストに割り当てられているすべての IP アドレスからのアクセスを許可します。ネットワークアクセスを許可するには、Key または KeyFile の値も指定する必要があります。
`AlternativeInstallLocation`	`String`	エミュレーター実行可能ファイルへの別の場所パス。
`CassandraPort`	`UInt16`	Cassandra 用 API に使用するポート番号。既定のポートは `10350` です。
`ComputePort`	`UInt16`	Compute Interop Gateway サービスに使用するポート。ゲートウェイの HTTP エンドポイントプローブポートのポート番号は、`ComputePort + 79` を加えた値として計算されます。このため、`ComputePort` と `ComputePort + 79` は、開いて利用可能な状態にしておく必要があります。既定のポートは、`8900`、`8979` です。
`Consistency`	`String`	エミュレーターの既定の整合性レベルを Session、Strong、Eventual、または BoundedStaleness に設定します。既定レベルは Session です。
`Credential`	`PSCredential`	この処理を実行するアクセス許可を持つユーザーアカウントを指定します。 `User01` や `Domain01\User01` などのユーザー名を使用するか、`Get-Credential` コマンドレットのような `PSCredential` オブジェクトを入力します。既定では、コマンドレットは現在のユーザーの資格情報を使用します。
`DataPath`	`String`	データファイルを格納するパス。データファイルの既定の場所は `$env:LocalAppData\CosmosDbEmulator` です。
`DefaultPartitionCount`	`UInt16`	パーティション分割コレクションごとに予約するパーティションの数。既定値は 25 です。これは、合計パーティション数の既定値と同じです。
`DirectPort`	`UInt16`	エミュレーターのバックエンドへの直接接続に使用する 4 つのポートの一覧。既定のリストは、`10251`、`10252`、`10253`、`10254` です。
`EnableMongoDb`	`SwitchParameter`	MongoDB エンドポイント用 API が有効になっていることを指定します。既定値は false です。
`EnableCassandra`	`SwitchParameter`	Apache Cassandra エンドポイント用 API が有効になっていることを指定します。既定値は false です。
`EnableGremlin`	`SwitchParameter`	Apache Gremlin エンドポイント用 API が有効になっていることを指定します。既定値は false です。
`EnableTable`	`SwitchParameter`	Table エンドポイント用 API が有効になっていることを指定します。既定値は false です。
`EnableSqlCompute`	`SwitchParameter`	NoSQL エンドポイント用 API が有効になっていることを指定します。既定値は false です。
`EnablePreview`	`SwitchParameter`	プレビュー段階であり、完全に成熟していないエミュレーター機能を既定で有効にします。
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	証明書の SAN にエミュレーターのホストのドメイン名、ローカル IP アドレス (v4)、`localhost`、および `127.0.0.1` が含まれていない場合、既定では、エミュレーターにより自己署名 TLS/SSL 証明書が再生成されます。このオプションを設定すると、代わりに起動時にエミュレーターが失敗します。その後は `New-CosmosDbEmulatorCertificate` オプションを使って新しい自己署名 TLS/SSL 証明書を作成およびインストールする必要があります。
`GremlinPort`	`UInt16`	Apache Gremlin 用 API に使用するポート番号。既定のポート番号は `8901` です。
`TablePort`	`UInt16`	Table 用 API に使用するポート番号。既定のポート番号は `8902` です。
`SqlComputePort`	`UInt16`	NoSQL 用 API に使用するポート番号。既定のポート番号は `8903` です。
`Key`	`String`	エミュレーターの承認キーです。この値は、64 バイトベクトルの Base 64 エンコードが施されている必要があります。
`MongoPort`	`UInt16`	MongoDB 用 API に使用するポート番号。既定のポート番号は `10250` です。
`MongoApiVersion`	`String`	MongoDB 用 API に使用するバージョンを指定します。既定のバージョンは `4.0` です。
`NoFirewall`	`SwitchParameter`	エミュレーターホストのファイアウォールに受信ポート規則を追加しないことを指定します。
`NoTelemetry`	`SwitchParameter`	コマンドレットが現在のエミュレーターセッションのデータを収集しないように指定します。
`NoUI`	`SwitchParameter`	コマンドレットがユーザーインターフェイスまたはタスクバーアイコンを表示しないことを指定します。
`NoWait`	`SwitchParameter`	エミュレーターの起動が開始されるとすぐに、コマンドレットが戻る必要があることを指定します。既定では、コマンドレットは、起動が完了し、エミュレーターが要求を受信できるようになるまで待機してから戻ります。
`PartitionCount`	`UInt16`	エミュレーターによって割り当てられたパーティションの合計数。
`Port`	`UInt16`	エミュレーターゲートウェイサービスと Web UI のポート番号。既定のポート番号は `8081` です。
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

例

エミュレーターを起動し、完全に開始され、要求を受け入れる準備ができるまで待ちます。
```
Start-CosmosDbEmulator
```
パーティション分割されたコレクションごとに 5 つのパーティションが予約された状態でエミュレーターを起動します。パーティションの合計数は、既定値の 25 に設定されます。そのため、作成できるパーティションコレクションの合計数は 5 = 25 partitions / 5 partitions/collection です。パーティション分割された各コレクションは、50 GB = 5 partitions * 10 GB / partiton に制限されます。
```
@parameters = {
    DefaultPartitionCount = 5
}
Start-CosmosDbEmulator @parameters
```

代替ポート番号を使用してエミュレーターを起動します。

@parameters = {
    Port = 443 
    MongoPort = 27017 
    DirectPort = 20001,20002,20003,20004
}
Start-CosmosDbEmulator @parameters

`Stop-CosmosDbEmulator`

エミュレーターを停止します。既定では、このコマンドは、エミュレーターが完全に停止するまで待ちます。エミュレーターが停止し始めたらすぐにコマンドレットから戻るようにする場合は、-NoWait オプションを使用します。

構文

Stop-CosmosDbEmulator 
    [[-AlternativeInstallLocation] <String>]
    [-NoWait] [[-Timeout] <UInt32>] [-Trace] 
    [<CommonParameters>]

パラメーター

名前	Type	説明
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	シャットダウンが開始されるとすぐにコマンドレットを返すように指定します。
`Trace`	`SwitchParameter`

例

@parameters = {
    NoWait = $true
}
Stop-CosmosDbEmulator @parameters

`Uninstall-CosmosDbEmulator`

エミュレーターをアンインストールし、オプションで $env:LOCALAPPDATA\CosmosDbEmulator のすべての内容を削除します。このコマンドレットは、アンインストールする前にエミュレーターが停止されたことを確認します。

構文

Uninstall-CosmosDbEmulator 
    [-RemoveData] 
    [<CommonParameters>]

パラメーター

名前	Type	説明
`RemoveData`	`SwitchParameter`	エミュレーターを削除した後、コマンドレットですべてのデータを削除するように指定します。

例

@parameters = {
    RemoveData = $false
}
Uninstall-CosmosDbEmulator @parameters

既定のコンテナー数を変更する

エミュレーターで作成できるコンテナーの数の既定値は、固定サイズのコンテナーであれば 25 個 (Azure Cosmos DB SDK を使用した場合にのみサポート)、容量無制限のコンテナーであれば 5 個までです。 PartitionCount の値を変更すると、固定サイズのコンテナーであれば 250 個、容量無制限のコンテナーであれば 50 個まで作成できるようになります。この 2 つの組み合わせは、固定サイズのコンテナー 250 個分を超えない範囲であれば、自由に決めることができます (容量無制限のコンテナーは、1 個につき固定サイズのコンテナー 5 個分として計算されます)。ただし、固定サイズのコンテナーが 200 個以上の状態でエミュレーターを実行する設定にはしないことをお勧めします。これは、ディスクの IO 操作にオーバーヘッドが加わり、エンドポイント API の使用中に予測し得ないタイムアウトが発生する原因となるためです。

現在のパーティション数を超えた後にコンテナーを作成しようとすると、次のメッセージと共に ServiceUnavailable 例外がスローされます。

Sorry, we are currently experiencing high demand in this region, and cannot fulfill your request at this time. We work continuously to bring more and more capacity online, and encourage you to try again.
ActivityId: 12345678-1234-1234-1234-123456789abc

エミュレーターで利用可能なコンテナーの数を変更する手順は次のとおりです。

システムトレイのエミュレーター アイコンを右クリックしてすべてのローカルのエミュレーターデータを削除し、[データのリセット…] をクリックします。
フォルダー %LOCALAPPDATA%\CosmosDBEmulator にあるエミュレーターのデータをすべて削除します。
システムトレイのエミュレーター アイコンを右クリックし、開いているすべてのインスタンスを終了して、[終了] をクリックします。すべてのインスタンスが終了するまでしばらく時間がかかる場合があります。
最新バージョンのエミュレーターをインストールします。
PartitionCount フラグの値を 250 以下に設定して、エミュレーターを起動します。 (例: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100)。

Windows (ローカル) エミュレーターのコマンドラインと PowerShell リファレンス

コマンドライン構文を使用してエミュレーターを管理する

PowerShell コマンドレットでエミュレーターを管理する

`Get-CosmosDbEmulatorStatus`

構文

パラメーター

例

`Start-CosmosDbEmulator`

構文

パラメーター

例

`Stop-CosmosDbEmulator`

構文

パラメーター

例

`Uninstall-CosmosDbEmulator`

構文

パラメーター

例

既定のコンテナー数を変更する

次のステップ

その他のリソース