Azure Event Hubs 에뮬레이터를 사용하여 로컬로 테스트

2025-05-01

이 문서에서는 Azure Event Hubs 에뮬레이터를 사용하여 로컬로 개발하고 테스트하는 단계를 요약합니다.

필수 조건

Docker 데스크톱
최소 하드웨어 요구 사항:
- 2GB RAM
- 5GB의 디스크 공간
WSL(Linux용 Windows 하위 시스템) 구성(Windows에만 해당):
- WSL 설치
- WSL을 사용하도록 Docker 구성

참고 항목

이 문서의 단계를 계속하기 전에 Docker Desktop이 백그라운드에서 작동하는지 확인합니다.

에뮬레이터 실행

Event Hubs 에뮬레이터를 실행하려면 자동화된 스크립트 또는 Linux 컨테이너를 사용할 수 있습니다.

자동화된 스크립트
Docker(Linux 컨테이너)

자동화된 스크립트를 실행하기 전에 에뮬레이터의 GitHub 설치 관리자 리포지 토리를 로컬로 복제합니다.

윈도우즈

다음 단계를 사용하여 Windows에서 Event Hubs 에뮬레이터를 로컬로 실행합니다.

PowerShell을 열고를 사용하여 cd 스크립트 폴더가 복제된 디렉터리로 이동합니다.
```
cd <path to your common scripts folder> # Update this path
```
이 디렉터리에서 WSL을 열려면 wsl 명령을 실행합니다.
```
wsl
```
설치 스크립트를 실행합니다./LaunchEmulator.sh 스크립트를 실행하면 Event Hubs 에뮬레이터와 Azurite(에뮬레이터에 대한 종속성)라는 두 개의 컨테이너가 표시됩니다.
```
./Launchemulator.sh
```

Linux 및 macOS

Linux 또는 macOS에서 Event Hubs 에뮬레이터를 로컬로 실행하려면 다음을 수행합니다.

설치 스크립트 LaunchEmulator.sh 실행합니다. 스크립트를 실행하면 Event Hubs 에뮬레이터와 Azurite(에뮬레이터에 대한 종속성)라는 두 개의 컨테이너가 표시됩니다.

에뮬레이터를 시작하려면 사용하려는 엔터티에 대한 구성을 제공합니다. 다음 JSON 파일을 config.json 로컬로 저장합니다.

{
    "UserConfig": {
        "NamespaceConfig": [
        {
            "Type": "EventHub",
            "Name": "emulatorNs1",
            "Entities": [
            {
                "Name": "eh1",
                "PartitionCount": "2",
                "ConsumerGroups": [
                {
                    "Name": "cg1"
                }
                ]
            }
            ]
        }
        ], 
        "LoggingConfig": {
            "Type": "File"
        }
    }
}

Event Hubs 에뮬레이터에 대한 컨테이너를 스핀업하려면 다음 .yaml 파일을 docker-compose.yaml로 저장합니다.

name: microsoft-azure-eventhubs
services:
  emulator:
    container_name: "eventhubs-emulator"
    image: "mcr.microsoft.com/azure-messaging/eventhubs-emulator:latest"
    pull_policy: always
    volumes:
      - "${CONFIG_PATH}:/Eventhubs_Emulator/ConfigFiles/Config.json"
    ports:
      - "5672:5672"
      - "9092:9092"
      - "5300:5300"
    environment:
      BLOB_SERVER: azurite
      METADATA_SERVER: azurite
      ACCEPT_EULA: ${ACCEPT_EULA}
    depends_on:
      - azurite
    networks:
      eh-emulator:
        aliases:
          - "eventhubs-emulator"
  azurite:
    container_name: "azurite"
    image: "mcr.microsoft.com/azure-storage/azurite:latest"
    pull_policy: always
    ports:
      - "10000:10000"
      - "10001:10001"
      - "10002:10002"
    networks:
      eh-emulator:
        aliases:
          - "azurite"
networks:
  eh-emulator:

Event Hubs 에뮬레이터에 대한 환경 변수를 선언하는 .env 파일을 만듭니다.
```
# Centralized environment variables store for docker-compose

# 1. CONFIG_PATH: Path to config.json file
CONFIG_PATH="<Replace with path to config.json file>" 

# 2. ACCEPT_EULA: Pass 'Y' to accept license terms. 
ACCEPT_EULA="N"
```
이 인수 ACCEPT_EULA 는 Microsoft 소프트웨어 사용 조건을 확인 합니다. .env 파일을 docker-compose.yaml 파일과 동일한 디렉터리에 배치해야 합니다.

중요합니다

Windows에서 파일 경로를 지정하는 경우 이스케이프 문자와 혼동하지 않도록 단일 백슬라이시\\() 대신 이중 백슬라이시(\)를 사용합니다.
에뮬레이터를 실행하려면 다음 명령을 실행합니다.
```
 docker compose -f <PathToDockerComposeFile> up -d
```

단계가 성공하면 Docker에서 실행되는 컨테이너를 찾을 수 있습니다.

컨테이너에서 실행되는 Event Hubs 에뮬레이터를 보여 주는 스크린샷

에뮬레이터와 상호 작용

기본적으로 에뮬레이터는 config.json 구성 파일을 사용합니다. 구성 파일을 변경하여 엔터티(Event Hubs/Kafka 토픽)를 구성할 수 있습니다. 자세히 알아보려면 구성 변경 작업을 방문 하세요.

다음 연결 문자열 사용하여 Event Hubs 에뮬레이터에 연결할 수 있습니다.

에뮬레이터 컨테이너 및 상호 작용 애플리케이션이 로컬 컴퓨터에서 기본적으로 실행되는 경우 다음 연결 문자열 사용합니다.

"Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

다른 컴퓨터와 동일한 로컬 네트워크의 애플리케이션(컨테이너화/컨테이너화되지 않은)은 컴퓨터의 IPv4 주소를 사용하여 에뮬레이터와 상호 작용할 수 있습니다. 다음 연결 문자열 사용합니다.

"Endpoint=sb://192.168.y.z;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

동일한 브리지 네트워크의 애플리케이션 컨테이너는 별칭 또는 IP를 사용하여 에뮬레이터와 상호 작용할 수 있습니다. 다음 연결 문자열 에뮬레이터 이름에 "eventhubs-emulator"라는 기본값이 있다고 가정합니다.

"Endpoint=sb://eventhubs-emulator;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

다른 브리지 네트워크의 애플리케이션 컨테이너는 "host.docker.internal"를 호스트로 사용하여 에뮬레이터와 상호 작용할 수 있습니다. 다음 연결 문자열 사용합니다.

"Endpoint=sb://host.docker.internal;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

Kafka 사용
AMQP 사용

Kafka와 상호 작용하는 동안 생산자 및 소비자 구성을 다음과 같이 설정해야 합니다.


        {
            BootstrapServers =  //Value of bootstrap servers would depend on kind of connection string being used
            SecurityProtocol = SecurityProtocol.SaslPlaintext,
            SaslMechanism = SaslMechanism.Plain,
            SaslUsername = "$ConnectionString",
            SaslPassword = //Value of connection string would depend on topology
        };

BootstrapServers 및 SaslPassword의 값은 설정 토폴로지에 따라 달라집니다. 자세한 내용은 에뮬레이터와 상호 작용 섹션을 참조하세요.

중요합니다

Kafka를 사용하는 경우 생산자 및 소비자 API만 Event Hubs 에뮬레이터와 호환됩니다.

시작하려면 GitHub의 Event Hubs 에뮬레이터 샘플을 참조하세요.

Azure Event Hubs 에뮬레이터 개요