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(으)로 계산됩니다. 따라서 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 엔드포인트에 사용할 포트 번호를 지정합니다. 기본값은 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), localhost127.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, 1025310254 입니다. 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"

또는 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>]

매개 변수

속성 형식 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(으)로 계산됩니다. 따라서 ComputePortComputePort + 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, 1025310254입니다.
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), localhost127.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

에뮬레이터에서 사용 가능한 컨테이너 수를 변경하려면 다음 단계를 수행합니다.

  1. 시스템 트레이에서 에뮬레이터 아이콘을 마우스 오른쪽 단추로 클릭한 다음 데이터 초기화...를 클릭하여 모든 로컬 에뮬레이터 데이터를 삭제합니다.

  2. %LOCALAPPDATA%\CosmosDBEmulator 폴더의 에뮬레이터 데이터를 모두 삭제합니다.

  3. 시스템 트레이에서 에뮬레이터 아이콘을 마우스 오른쪽 단추로 클릭한 다음 마침을 클릭하여 열려 있는 모든 인스턴스를 종료합니다. 모든 인스턴스를 종료하는 데는 1분 정도 걸립니다.

  4. 최신 버전의 에뮬레이터를 설치합니다.

  5. 250 이하의 값을 설정하여 PartitionCount 플래그로 에뮬레이터를 시작합니다. 예: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100

다음 단계