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

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

중요한

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

필수 조건

Docker

설치

를 사용하여 docker pullDocker 컨테이너 이미지를 가져옵니다. 컨테이너 이미지는 Microsoft 아티팩트 레지스트리.

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실행됩니다.

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

중요한

.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 명령을 요약합니다. 이 표에서는 해당 인수, 환경 변수, 허용되는 값, 기본 설정 및 각 명령에 대한 설명을 자세히 설명합니다.

요구 사항	인수	환경 변수	허용된 값	기본값	설명
컨테이너에서 stdout으로 설정 인쇄	`--help`, `-h`	해당 없음	해당 없음	해당 없음	사용 가능한 구성에 대한 정보 표시
Cosmos 엔드포인트의 포트 설정	`--port [INT]`	포트	INT	8081	컨테이너에 있는 Cosmos 엔드포인트의 포트입니다. 이 포트를 게시해야 합니다(예: `-p 8081:8081`).
Cosmos 엔드포인트에서 사용하는 프로토콜 지정	`--protocol`	프로토콜	`https`, `http`, `https-insecure`	`http`	컨테이너의 Cosmos 엔드포인트 프로토콜입니다.
데이터 탐색기 사용	`--enable-explorer`	탐색기_활성화	`true`, `false`	`true`	동일한 컨테이너에서 Cosmos 데이터 탐색기 실행을 사용하도록 설정합니다.
데이터 탐색기에서 사용하는 포트 설정	`--explorer-port`	EXPLORER_PORT	INT	1234	컨테이너에 있는 Cosmos 데이터 탐색기의 포트입니다. 이 포트를 게시해야 합니다(예: `-p 1234:1234`).
사용자는 탐색기에서 사용하는 프로토콜을 지정할 수 있어야 하며, 그렇지 않으면 Cosmos 엔드포인트에서 사용하는 프로토콜을 기본값으로 지정해야 합니다.	`--explorer-protocol`	EXPLORER_PROTOCOL (탐색기_프로토콜)	`https`, `http`, `https-insecure`	`<the value of --protocol>`	컨테이너에 있는 Cosmos 데이터 탐색기의 프로토콜입니다. Cosmos 엔드포인트의 프로토콜 설정을 기본값으로 사용합니다.
파일을 통해 키 지정	`--key-file [PATH]`	KEY_FILE	경로	`<default secret>`	기본 키를 파일에 지정된 키로 재정의합니다. 이 파일을 컨테이너에 탑재해야 합니다(예: KEY_FILE=/mykey인 경우 docker 실행에 `--mount type=bind,source=./myKey,target=/myKey`다음과 같은 옵션을 추가합니다.)
데이터 경로 설정	`--data-path [PATH]`	DATA_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	경로	`<default cert>`	트래픽을 보호하기 위한 인증서 경로를 지정합니다. 이 파일을 컨테이너에 탑재해야 합니다(예: CERT_PATH=/mycert.pfx인 경우 docker 실행에 `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`다음과 같은 옵션을 추가합니다.)
https에 사용할 인증서 비밀 지정	해당 없음	CERT_SECRET	문자열	`<default secret>`	CERT_PATH에 지정된 인증서의 암호입니다.
로그 수준 설정	`--log-level [LEVEL]`	로그_레벨	`quiet`, `error`, `warn`, `info`, `debugtrace`	`info`	에뮬레이터와 데이터 탐색기에서 생성된 로그의 장황함입니다.
Microsoft로 전송되는 진단 정보 사용	`--enable-telemetry`	원격 측정 활성화	`true`, `false`	`true`	에뮬레이터를 개선하는 데 도움이 되도록 Microsoft에 로그를 보낼 수 있습니다.

기능 지원

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

기능	지원
Batch API	✅ 지원됨
Bulk 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

연속 통합 워크플로에서 사용

특히 데이터베이스와 같은 상태 저장 시스템의 경우 CI/CD 파이프라인에서 Docker 컨테이너를 사용하는 경우 많은 이점이 있습니다. 이는 테스트 도구 모음의 비용 효율성, 성능, 안정성 및 일관성 측면에서 발생할 수 있습니다.

에뮬레이터는 CI/CD 파이프라인의 일부로 통합될 수 있습니다. .NET, Python, Java 및 Go 애플리케이션에서 및 x64 아키텍처를 대상으로 GitHub Actions CI 워크플로의 일부로 에뮬레이터를 사용하는 방법에 대한 예제를 제공하는 이 ARM64를 참조할 수 있습니다 (Linux 러너에 ubuntu를 사용하는 것이 시연됨).

워크플로에서 작업의 일부로 에뮬레이터를 GitHub Actions 서비스 컨테이너 로 구성하는 방법을 보여 주는 GitHub Actions CI 워크플로의 예는 다음과 같습니다. GitHub는 Docker 컨테이너를 시작하고 작업이 완료되면 수동으로 개입할 필요 없이(예: 명령 사용 docker run ) 삭제합니다.

name: CI demo app

on:
  push:
    branches: [main]
    paths:
      - 'java-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'java-app/**'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https
        
    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

    steps:

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          distribution: 'microsoft'
          java-version: '21.0.0'

      - name: Export Cosmos DB Emulator Certificate
        run: |

          sudo apt update && sudo apt install -y openssl

          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert

          cat cosmos_emulator.cert

          $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
      
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run tests
        run: cd java-app && mvn test

이 작업은 Ubuntu 실행기에서 실행되며 Docker 이미지를 서비스 컨테이너로 사용합니다 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview . 환경 변수를 사용하여 연결 문자열, 데이터베이스 이름 및 컨테이너 이름을 구성합니다. 이 경우 작업이 GitHub Actions 실행기 머신에서 직접 실행되므로, 작업의 실행 테스트 단계에서 localhost:8081를 사용하여 8081로 노출된 에뮬레이터 포트에 액세스할 수 있습니다.

Cosmos DB 에뮬레이터 인증서 내보내기 단계는 Azure Cosmos DB Java SDK가 현재 에뮬레이터에서 모드를 지원하지 HTTP 않으므로 Java 애플리케이션과 관련이 있습니다. PROTOCOL 환경 변수는 https 섹션에서 services로 설정되며 이 단계에서는 에뮬레이터 인증서를 내보낸 후 Java 키스토어로 가져옵니다. .NET에도 동일하게 적용됩니다.

문제 신고

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

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-07-21