Linux 기반 에뮬레이터(미리 보기)

아티클
11/20/2024

차세대 Azure Cosmos DB 에뮬레이터는 전적으로 Linux 기반이며 Docker 컨테이너로 사용할 수 있습니다. 다양한 프로세서 및 운영 체제에서 실행을 지원합니다.

Important

이 버전의 에뮬레이터는 선택한 기능 하위 집합을 사용하여 게이트웨이 모드에서 NoSQL용 API만 지원합니다. 자세한 내용은 기능 지원을 참조하세요.

필수 조건

Docker

설치

를 사용하여 docker pullDocker 컨테이너 이미지를 가져옵니다. 컨테이너 이미지는 Microsoft 아티팩트 레지스트리 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview게시됩니다.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

실행 중

컨테이너를 실행하려면 .를 사용합니다 docker run. 그런 다음 컨테이너가 실행 중인지 확인하는 데 사용합니다 docker ps .

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview  "/bin/bash -c /home/…"   5 seconds ago   Up 5 seconds   0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp   <container-name>

참고 항목

에뮬레이터는 다음 두 가지 구성 요소로 구성됩니다.

데이터 탐색기 - 에뮬레이터의 데이터를 대화형으로 탐색합니다. 기본적으로 포트에서 실행됩니다. 1234
Azure Cosmos DB 에뮬레이터 - Azure Cosmos DB 데이터베이스 서비스의 로컬 버전입니다. 기본적으로 포트에서 8081실행됩니다.

에뮬레이터 게이트웨이 엔드포인트는 일반적으로 주소http://localhost:8081의 포트 8081 에서 사용할 수 있습니다. 데이터 탐색기로 이동하려면 웹 브라우저에서 주소를 http://localhost:1234 사용합니다. 데이터 탐색기를 사용할 수 있는 데 몇 초 정도 걸릴 수 있습니다. 게이트웨이 엔드포인트는 일반적으로 즉시 사용할 수 있습니다.

Important

.NET 및 Java SDK는 에뮬레이터에서 HTTP 모드를 지원하지 않습니다. 이 버전의 에뮬레이터는 기본적으로 HTTP로 시작되므로 컨테이너를 시작할 때 HTTPS를 명시적으로 사용하도록 설정해야 합니다(아래 참조). Java SDK의 경우 인증서도 설치해야 합니다.

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

Docker 명령

다음 표에서는 에뮬레이터를 구성하는 데 사용할 수 있는 Docker 명령을 요약합니다. 이 표에서는 해당 인수, 환경 변수, 허용되는 값, 기본 설정 및 각 명령에 대한 설명을 자세히 설명합니다.

요건	Arg	Env	허용된 값	기본값	설명
컨테이너에서 stdout으로 설정 인쇄	`--help`, `-h`	해당 없음	해당 없음	해당 없음	사용 가능한 구성에 대한 정보 표시
Cosmos 엔드포인트의 포트 설정	`--port [INT]`	포트	INT	8081	컨테이너에 있는 Cosmos 엔드포인트의 포트입니다. 이 포트를 게시해야 합니다(예: `-p 8081:8081`).
Cosmos 엔드포인트에서 사용하는 프로토콜 지정	`--protocol`	프로토콜	`https`, , `httphttps-insecure`	`http`	컨테이너의 Cosmos 엔드포인트 프로토콜입니다.
데이터 탐색기 사용	`--enable-explorer`	ENABLE_EXPLORER	`true`, `false`	`true`	동일한 컨테이너에서 Cosmos 데이터 탐색기 실행을 사용하도록 설정합니다.
데이터 탐색기에서 사용하는 포트 설정	`--explorer-port`	EXPLORER_PORT	INT	1234	컨테이너에 있는 Cosmos 데이터 탐색기의 포트입니다. 이 포트를 게시해야 합니다(예: `-p 1234:1234`).
사용자는 탐색기에서 사용하는 프로토콜을 지정할 수 있어야 하며, 그렇지 않으면 Cosmos 엔드포인트에서 사용하는 프로토콜을 기본값으로 지정해야 합니다.	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`, , `httphttps-insecure`	`<the value of --protocol>`	컨테이너에 있는 Cosmos 데이터 탐색기의 프로토콜입니다. 기본값은 Cosmos 엔드포인트의 프로토콜 설정입니다.
파일을 통해 키 지정	`--key-file [PATH]`	KEY_FILE	PATH	`<default secret>`	파일에 지정된 키로 기본 키를 재정의합니다. 이 파일을 컨테이너에 탑재해야 합니다(예: KEY_FILE=/mykey인 경우 docker 실행에 `--mount type=bind,source=./myKey,target=/myKey`다음과 같은 옵션을 추가합니다.)
데이터 경로 설정	`--data-path [PATH]`	DATA_PATH	PATH	`/data`	데이터의 디렉터리를 지정합니다. 옵션과 함께 `docker run --mount` 자주 사용됩니다(예: DATA_PATH=/usr/cosmos/data인 경우 Docker 실행에 `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`다음과 같은 옵션을 추가합니다.)
https에 사용할 인증서 경로 지정	`--cert-path [PATH]`	CERT_PATH	PATH	`<default cert>`	트래픽을 보호하기 위한 인증서 경로를 지정합니다. 이 파일을 컨테이너에 탑재해야 합니다(예: CERT_PATH=/mycert.pfx인 경우 docker 실행에 `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`다음과 같은 옵션을 추가합니다.)
https에 사용할 인증서 비밀 지정	해당 없음	CERT_SECRET	string	`<default secret>`	CERT_PATH 지정된 인증서의 비밀입니다.
로그 수준 설정	`--log-level [LEVEL]`	LOG_LEVEL	`quiet`, `error`, `warn`, `info`, `debugtrace`	`info`	에뮬레이터 및 데이터 탐색기에서 내보낸 로그의 세부 정보입니다.
Microsoft로 전송되는 진단 정보 사용	`--enable-telemetry`	ENABLE_TELEMETRY	`true`, `false`	`true`	에뮬레이터를 개선하는 데 도움이 되도록 Microsoft에 로그를 보낼 수 있습니다.

기능 지원

이 에뮬레이터는 현재 개발 및 미리 보기 상태입니다. 따라서 모든 Azure Cosmos DB 기능이 지원되지는 않습니다. 일부 기능은 나중에 지원되지 않습니다. 이 표에는 다양한 기능의 상태와 지원 수준이 포함되어 있습니다.

기능	지원
Batch API	✅ 지원됨
대량 API	✅ 지원됨
변경 피드	⚠️ 아직 구현되지 않음
utf 데이터를 사용하여 문서 만들기 및 읽기	✅ 지원됨
컬렉션 만들기	✅ 지원됨
컬렉션 만들기 두 번 충돌	✅ 지원됨
사용자 지정 인덱스 정책을 사용하여 컬렉션 만들기	⚠️ 아직 구현되지 않음
ttl 만료를 사용하여 컬렉션 만들기	⚠️ 아직 구현되지 않음
데이터베이스 만들기	✅ 지원됨
데이터베이스 만들기 두 번 충돌	✅ 지원됨
문서 만들기	✅ 지원됨
분할된 컬렉션 만들기	⚠️ 아직 구현되지 않음
컬렉션 삭제	✅ 지원됨
데이터베이스 삭제	✅ 지원됨
문서 삭제	✅ 지원됨
컬렉션 성능 가져오기 및 변경	⚠️ 아직 구현되지 않음
큰 문서 삽입	✅ 지원됨
문서 패치	⚠️ 아직 구현되지 않음
분할된 컬렉션을 병렬로 쿼리	⚠️ 아직 구현되지 않음
집계를 사용하여 쿼리	⚠️ 아직 구현되지 않음
쿼리 및 필터링	⚠️ 아직 구현되지 않음
쿼리 및 필터링 및 프로젝션	⚠️ 아직 구현되지 않음
같음 쿼리	✅ 지원됨
ID가 같은 쿼리	✅ 지원됨
조인을 사용하여 쿼리	⚠️ 아직 구현되지 않음
순서를 사용하여 쿼리	✅ 지원됨
분할된 컬렉션에 대한 순서를 사용하여 쿼리	⚠️ 아직 구현되지 않음
숫자로 순서를 사용하여 쿼리	✅ 지원됨
문자열별 순서를 사용하여 쿼리	⚠️ 아직 구현되지 않음
페이징을 사용하여 쿼리	⚠️ 아직 구현되지 않음
범위 연산자 날짜 시간을 사용하여 쿼리	⚠️ 아직 구현되지 않음
숫자의 범위 연산자를 사용하여 쿼리	⚠️ 아직 구현되지 않음
문자열에 범위 연산자를 사용하여 쿼리	⚠️ 아직 구현되지 않음
단일 조인을 사용하여 쿼리	⚠️ 아직 구현되지 않음
문자열 수학 및 배열 연산자를 사용하여 쿼리	⚠️ 아직 구현되지 않음
하위 문서를 사용하여 쿼리	⚠️ 아직 구현되지 않음
두 개의 조인을 사용하여 쿼리	⚠️ 아직 구현되지 않음
두 개의 조인 및 필터를 사용하여 쿼리	⚠️ 아직 구현되지 않음
컬렉션 읽기	✅ 지원됨
컬렉션 피드 읽기	⚠️ 아직 구현되지 않음
데이터베이스 읽기	✅ 지원됨
데이터베이스 피드 읽기	⚠️ 아직 구현되지 않음
문서 읽기	✅ 지원됨
문서 피드 읽기	✅ 지원됨
문서 바꾸기	✅ 지원됨
요청 단위	⚠️ 아직 구현되지 않음
저장 프로시저	❌ 계획되지 않음
트리거	❌ 계획되지 않음
UDF	❌ 계획되지 않음
컬렉션 업데이트	⚠️ 아직 구현되지 않음
문서 업데이트	✅ 지원됨

제한 사항

아직 지원되지 않거나 계획되지 않은 기능 외에도 다음 목록에는 에뮬레이터의 현재 제한 사항이 포함되어 있습니다.

Azure Cosmos DB용 .NET SDK는 에뮬레이터에서 대량 실행을 지원하지 않습니다.
.NET 및 Java SDK는 에뮬레이터에서 HTTP 모드를 지원하지 않습니다.

Java SDK용 인증서 설치

Https 모드에서 이 버전의 에뮬레이터와 함께 Azure Cosmos DB 용 Java SDK를 사용하는 경우 로컬 Java 트러스트 저장소에 인증서를 설치해야 합니다.

인증서 가져오기

창에서 bash 다음을 실행합니다.

# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH

인증서 설치

파일이 있는 cacerts Java 설치의 디렉터리로 이동합니다(아래를 올바른 디렉터리로 바꿉다).

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

인증서를 가져옵니다(암호를 입력하라는 메시지가 표시될 수 있습니다. 기본값은 "changeit").

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

별칭이 이미 있으므로 오류가 발생하면 해당 별칭을 삭제한 다음 위 항목을 다시 실행합니다.

keytool -cacerts -delete -alias cosmos_emulator

문제 보고

이 버전의 에뮬레이터를 사용하는 데 문제가 발생하는 경우 GitHub 리포지토리(https://github.com/Azure/azure-cosmos-db-emulator-docker)에서 문제를 열고 레이블 cosmosEmulatorVnextPreview로 태그를 지정합니다.

다음을 통해 공유