次の方法で共有


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

適用対象: 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 を加えた値として計算されます。 このため、ComputePortComputePort + 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 直接接続に使用するポートを指定します。 既定値は、102511025210253、および 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"

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

$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 を加えた値として計算されます。 このため、ComputePortComputePort + 79 は、開いて利用可能な状態にしておく必要があります。 既定のポートは、89008979 です。
Consistency String エミュレーターの既定の整合性レベルを SessionStrongEventual、または BoundedStaleness に設定します。 既定レベルは Session です。
Credential PSCredential この処理を実行するアクセス許可を持つユーザー アカウントを指定します。 User01Domain01\User01 などのユーザー名を使用するか、Get-Credential コマンドレットのような PSCredential オブジェクトを入力します。 既定では、コマンドレットは現在のユーザーの資格情報を使用します。
DataPath String データ ファイルを格納するパス。 データ ファイルの既定の場所は $env:LocalAppData\CosmosDbEmulator です。
DefaultPartitionCount UInt16 パーティション分割コレクションごとに予約するパーティションの数。 既定値は 25 です。これは、合計パーティション数の既定値と同じです。
DirectPort UInt16 エミュレーターのバックエンドへの直接接続に使用する 4 つのポートの一覧。 既定のリストは、10251102521025310254 です。
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

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

  1. システム トレイのエミュレーター アイコンを右クリックしてすべてのローカルのエミュレーター データを削除し、[データのリセット…] をクリックします。

  2. フォルダー %LOCALAPPDATA%\CosmosDBEmulator にあるエミュレーターのデータをすべて削除します。

  3. システム トレイのエミュレーター アイコンを右クリックし、開いているすべてのインスタンスを終了して、[終了] をクリックします。 すべてのインスタンスが終了するまでしばらく時間がかかる場合があります。

  4. 最新バージョンのエミュレーターをインストールします。

  5. PartitionCount フラグの値を 250 以下に設定して、エミュレーターを起動します。 (例: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100)。

次のステップ