Windows(로컬) 에뮬레이터에 대한 명령줄 및 PowerShell 참조
적용 대상: NoSQL MongoDB Cassandra Gremlin 테이블
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 /?
을(를) 입력합니다.
매개 변수 | Description | 예제 명령 |
---|---|---|
[인수 없음] | 기본 설정으로 에뮬레이터를 시작합니다. | Microsoft.Azure.Cosmos.Emulator.exe |
[도움말] | 지원되는 명령줄 인수 목록을 표시합니다. | 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 |
컴퓨팅 interop 게이트웨이 서비스에 사용할 포트 번호를 지정합니다. 게이트웨이의 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 엔드포인트에 사용할 포트 번호를 지정합니다. 기본값은 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 |
테이블용 API를 사용하도록 설정합니다. | Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint |
TablePort |
테이블 엔드포인트용 API에 사용할 포트 번호입니다. 기본값은 8902 여야 합니다. |
Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500 |
KeyFile |
지정된 파일에서 권한 부여 키를 읽어옵니다. 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 cmdlets을 사용하여 에뮬레이터 관리
에뮬레이터는 서비스를 시작, 중지, 제거, 검색하고 상태를 검색할 수 있는 PowerShell 모듈과 함께 제공 됩니다. 다음 cmdlet을 실행하여 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>]
매개 변수
속성 | 형식 | Description |
---|---|---|
AlternativeInstallLocation |
String |
예제
D:\SomeFolder\AzureCosmosDBEmulator
폴더에 설치된 에뮬레이터의 상태 가져옵니다.@parameters = { AlternativeInstallLocation = "D:\SomeFolder\AzureCosmosDBEmulator" } Get-CosmosDbEmulatorStatus @parameters
Start-CosmosDbEmulator
로컬 컴퓨터에서 에뮬레이터를 시작합니다. 기본적으로 이 명령은 에뮬레이터가 요청을 수락할 준비가 될 때까지 대기합니다. 에뮬레이터가 시작하자 마자 cmdlet을 반환하고자 하는 경우 -NoWait
옵션을 사용하십시오. Start-CosmosDbEmulator
의 매개 변수를 사용하여 NoSQL 포트, 직접 포트 및 MongoDB 포트 번호와 같은 옵션을 지정합니다.
구문
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>]
매개 변수
이름 | 형식 | Description |
---|---|---|
AllowNetworkAccess |
SwitchParameter |
에뮬레이터의 호스트에 할당된 모든 IP 주소에서 액세스를 허용합니다. 또한 네트워크 액세스를 허용하려면 Key 또는 KeyFile에 대한 값을 지정해야 합니다. |
AlternativeInstallLocation |
String |
에뮬레이터 실행 파일의 대체 위치 경로입니다. |
CassandraPort |
UInt16 |
Cassandra용 API에 사용할 포트 번호입니다. 기본 포트는 10350 입니다. |
ComputePort |
UInt16 |
컴퓨팅 interop 게이트웨이 서비스에 사용할 포트입니다. 게이트웨이의 HTTP 엔드포인트 프로브 포트는 ComputePort + 79 (으)로 계산됩니다. 따라서 ComputePort 및 ComputePort + 79 이(가) 열리고 사용할 수 있어야 합니다. 기본 포트는 8900 , 8979 입니다. |
Consistency |
String |
에뮬레이터의 기본 일관성 수준을 Session, Strong, Eventual 또는 BoundedStaleness로 설정합니다. 기본 수준은 Session입니다. |
Credential |
PSCredential |
이 작업을 수행할 권한이 있는 사용자 계정을 지정합니다. 사용자 이름(예: User01 또는 Domain01\User01 )을 사용하거나 Get-Credential cmdlet의 개체와 같은 PSCredential 개체를 입력합니다. 기본적으로 이 cmdlet은 현재 사용자의 자격 증명을 사용합니다. |
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 |
테이블 엔드포인트용 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 |
테이블용 API에 사용할 포트 번호입니다. 기본 포트 번호는 8902 입니다. |
SqlComputePort |
UInt16 |
NoSQL용 API에 사용할 포트 번호입니다. 기본 포트 번호는 8903 입니다. |
Key |
String |
에뮬레이터에 대한 권한 부여 키입니다. 이 값은 64바이트 벡터의 기본 64인코딩이어야 합니다. |
MongoPort |
UInt16 |
MongoDB용 API에 사용할 포트 번호입니다. 기본 포트 번호는 10250 입니다. |
MongoApiVersion |
String |
MongoDB용 API에 사용할 버전을 지정합니다. 기본 버전은 4.0 입니다. |
NoFirewall |
SwitchParameter |
에뮬레이터 호스트의 방화벽에 인바운드 포트 규칙을 추가하지 않음을 지정합니다. |
NoTelemetry |
SwitchParameter |
cmdlet이 현재 에뮬레이터 세션에 대한 데이터를 수집해서는 안 되도록 지정합니다. |
NoUI |
SwitchParameter |
cmdlet에 사용자 인터페이스 또는 작업 표시줄 아이콘이 표시되지 않도록 지정합니다. |
NoWait |
SwitchParameter |
에뮬레이터가 시작되는 즉시 cmdlet이 반환되도록 지정합니다. 기본적으로 cmdlet은 시작이 완료되고 에뮬레이터가 반환하기 전에 요청을 받을 준비가 될 때까지 기다립니다. |
PartitionCount |
UInt16 |
에뮬레이터에서 할당한 총 파티션 수입니다. |
Port |
UInt16 |
에뮬레이터 게이트웨이 서비스 및 웹 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
에뮬레이터를 중지합니다. 기본적으로 이 명령은 에뮬레이터가 완전히 종료할 때까지 대기합니다. 에뮬레이터가 종료를 시작하자 마자 cmdlet을 반환하고자 하는 경우 -NoWait 옵션을 사용하십시오.
구문
Stop-CosmosDbEmulator
[[-AlternativeInstallLocation] <String>]
[-NoWait] [[-Timeout] <UInt32>] [-Trace]
[<CommonParameters>]
매개 변수
이름 | 형식 | Description |
---|---|---|
AlternativeInstallLocation |
String |
|
Timeout |
UInt32 |
|
NoWait |
SwitchParameter |
종료가 시작되는 즉시 cmdlet이 반환되도록 지정합니다. |
Trace |
SwitchParameter |
예제
@parameters = {
NoWait = $true
}
Stop-CosmosDbEmulator @parameters
Uninstall-CosmosDbEmulator
에뮬레이터를 제거하고 $env:LOCALAPPDATA\CosmosDbEmulator
의 전체 콘텐츠를 선택적으로 제거합니다. Cmdlet는 에뮬레이터가 제거되기 전에 중지되도록 합니다.
구문
Uninstall-CosmosDbEmulator
[-RemoveData]
[<CommonParameters>]
매개 변수
이름 | 형식 | Description |
---|---|---|
RemoveData |
SwitchParameter |
cmdlet이 에뮬레이터를 제거한 후 모든 데이터를 삭제할 것을 지정합니다. |
예제
@parameters = {
RemoveData = $false
}
Uninstall-CosmosDbEmulator @parameters
기본 컨테이너 수 변경
기본적으로 고정 크기 컨테이너를 25개까지 만들거나(Azure Cosmos DB SDK를 통해서만 지원됨) 에뮬레이터를 사용하여 무제한 컨테이너 5개를 만들 수 있습니다. PartitionCount 값을 수정하여 최대 250개의 고정 크기 컨테이너나 50개의 무제한 컨테이너를 만들거나 250개의 고정 크기 컨테이너를 초과하지 않는 범위에서 두 가지 조합을 만들 수 있습니다(무제한 컨테이너 1개 = 고정 크기 컨테이너 5개). 단, 200개를 초과하는 고정 크기 컨테이너로 실행되도록 에뮬레이터를 설정하는 것은 권장하지 않습니다. 디스크 IO 작업에 추가되는 오버헤드로 인해, 엔드포인트 API를 사용할 때 예기치 않은 시간 초과가 발생합니다.
현재 파티션 수가 초과된 후에 컨테이너를 만들려고 하면 에뮬레이터에서 다음 메시지와 함께 ServiceUnavailable 예외를 throw합니다.
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
폴더의 에뮬레이터 데이터를 모두 삭제합니다.시스템 트레이에서 에뮬레이터 아이콘을 마우스 오른쪽 단추로 클릭한 다음 마침을 클릭하여 열려 있는 모든 인스턴스를 종료합니다. 모든 인스턴스를 종료하는 데는 1분 정도 걸립니다.
최신 버전의 에뮬레이터를 설치합니다.
250 이하의 값을 설정하여 PartitionCount 플래그로 에뮬레이터를 시작합니다. 예:
C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100