다음을 통해 공유

Azure Cosmos DB 에뮬레이터를 사용하여 로컬로 개발

  • 아티클

에뮬레이터의 일반적인 사용 사례는 애플리케이션을 빌드하는 동안 개발 데이터베이스 역할을 하는 것입니다. 개발에 에뮬레이터를 사용하면 서비스 비용을 부담하지 않고 Azure Cosmos DB와 같은 데이터베이스에 대한 데이터를 만들고 모델링하는 특성을 학습할 수 있습니다. 또한 에뮬레이터를 자동화 워크플로의 일부로 사용하면 동일한 통합 테스트 도구 모음을 실행할 수 있습니다. 동일한 테스트가 개발 컴퓨터에서 로컬로 실행되고 연속 통합 작업에서 원격으로 실행되도록 할 수 있습니다.

필수 조건

  • .NET 6 이상, Node.js v20 이상 또는 Python 3.7 이상
    • PATH에서 필요한 실행 파일을 모두 사용할 수 있는지 확인합니다.
  • Windows 에뮬레이터
    • 64비트 Windows Server 2016, 2019, Windows 10 또는 Windows 11.
    • 최소 하드웨어 요구 사항:
      • 2GB RAM
      • 10GB의 하드 디스크 여유 공간
  • Docker 에뮬레이터

에뮬레이터 설치

에뮬레이터는 여러 변형이 있으며 각 변형마다 상대적으로 마찰이 없는 설치 프로세스가 있습니다.

시작하려면 MCR(Microsoft Container Registry)컨테이너 이미지의 Linux 변형을 가져옵니다.

  1. 컨테이너 레지스트리에서 로컬 Docker 호스트로 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux 컨테이너 이미지를 끌어옵니다.

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

  2. 에뮬레이터 이미지를 로컬 Docker 호스트에서 사용할 수 있는지 확인합니다.

    docker images

시작하려면 MCR(Microsoft Container Registry)컨테이너 이미지의 Linux 변형을 가져옵니다.

  1. 컨테이너 레지스트리에서 로컬 Docker 호스트로 mongodb 태그를 사용하여 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux 컨테이너 이미지를 끌어옵니다.

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

  2. 에뮬레이터 이미지를 로컬 Docker 호스트에서 사용할 수 있는지 확인합니다.

    docker images

에뮬레이터의 Docker 컨테이너 변형(Linux 또는 Windows)은 Apache Cassandra용 API, Apache Gremlin용 API 또는 Table용 API를 지원하지 않습니다.

에뮬레이터 시작

다운로드를 완료했으면 지정된 API를 사용하도록 설정하여 에뮬레이터를 시작합니다.

에뮬레이터의 Docker 컨테이너 변형은 Apache Cassandra용 API를 지원하지 않습니다.

에뮬레이터의 Docker 컨테이너 변형은 Apache Gremlin용 API를 지원하지 않습니다.

에뮬레이터의 Docker 컨테이너 변형은 Table용 API를 지원하지 않습니다.

  1. 컨테이너 이미지 및 다음 구성을 사용하여 새 컨테이너를 실행합니다.

    설명
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(선택 사항) ‘사용할 파티션 수를 지정합니다.’
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(선택 사항) ‘에뮬레이터 실행 간에 데이터 지속성을 사용하도록 설정합니다.’
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(선택 사항) ‘에뮬레이터의 기본 IP 주소를 재정의합니다.’

    Linux 시스템의 경우 다음을 사용합니다.

    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

    Windows 시스템의 경우 다음을 사용합니다.

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250-10255:10250-10255"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. https://localhost:8081/_explorer/index.html로 이동하여 데이터 탐색기에 액세스합니다.

  1. 컨테이너 이미지 및 다음 구성을 사용하여 새 컨테이너를 실행합니다.

    설명
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT 사용할 MongoDB 엔드포인트의 버전을 지정합니다. 지원되는 엔드포인트는 3.2, 3.6 또는 4.0입니다.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(선택 사항) ‘사용할 파티션 수를 지정합니다.’
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(선택 사항) ‘에뮬레이터 실행 간에 데이터 지속성을 사용하도록 설정합니다.’
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(선택 사항) ‘에뮬레이터의 기본 IP 주소를 재정의합니다.’

    Linux 시스템의 경우 다음을 사용합니다.

    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

    Windows 시스템의 경우 다음을 사용합니다.

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250:10250"
    "--env", "AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. https://localhost:8081/_explorer/index.html로 이동하여 데이터 탐색기에 액세스합니다.

에뮬레이터의 TLS/SSL 인증서 가져오기

에뮬레이터의 TLS/SSL 인증서를 가져와 클라이언트에서 TLS/SSL을 사용하지 않도록 설정하지 않고 기본 설정 개발자 SDK와 함께 에뮬레이터를 사용합니다.

에뮬레이터의 Docker 컨테이너 변형(Linux 또는 Windows)은 Apache Cassandra용 API, Apache Gremlin용 API 또는 Table용 API를 지원하지 않습니다.

에뮬레이터에 대한 인증서는 실행 중인 컨테이너의 _explorer/emulator.pem 경로에서 사용할 수 있습니다. curl을 사용하여 실행 중인 컨테이너에서 로컬 컴퓨터로 인증서를 다운로드합니다.

  1. 실행 중인 컨테이너에서 인증서를 가져옵니다.

    Linux 시스템의 경우 다음을 사용합니다.

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    Windows 시스템의 경우 다음을 사용합니다.

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

  2. 운영 체제에 적절한 명령을 사용하여 인증서 번들을 다시 생성합니다.

    Debian 기반 Linux 시스템(예: Ubuntu)의 경우 다음을 사용합니다.

    sudo update-ca-certificates

    Red Hat 기반 Linux 시스템(예: CentOS, Fedora)의 경우 다음을 사용합니다.

    sudo update-ca-trust

    Windows 시스템의 경우 다음을 사용합니다.

    certutil -f -addstore "Root" ~/emulatorcert.crt

    자세한 지침은 운영 체제와 관련된 설명서를 참조하세요.

에뮬레이터에 대한 인증서는 실행 중인 컨테이너의 /_explorer/emulator.pem 경로에서 사용할 수 있습니다.

  1. 실행 중인 컨테이너에서 로컬 컴퓨터로 인증서를 다운로드합니다.

    Linux 시스템의 경우 다음을 사용합니다.

    curl --insecure https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    Windows 시스템의 경우 다음을 사용합니다.

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

    참고 항목

    이전에 해당 값을 수정한 경우 호스트(또는 IP 주소) 및 포트 번호를 변경해야 할 수 있습니다.

  2. 운영 체제에서 일반적으로 사용되는 프로세스에 따라 인증서를 설치합니다. 예를 들어 Linux에서는 인증서를 /usr/local/share/ca-certificates/ 경로에 복사합니다.

    Linux 시스템의 경우 다음을 사용합니다.

    cp ~/emulatorcert.crt /usr/local/share/ca-certificates/

    Windows 시스템의 경우 다음을 사용합니다.

    $parameters = @{
    FilePath = 'emulatorcert.crt'
    CertStoreLocation = 'Cert:\CurrentUser\Root'
}
Import-Certificate @parameters

  3. Linux 시스템의 경우 Linux 배포에 적절한 명령을 사용하여 인증서 번들을 다시 생성합니다.

    Debian 기반 Linux 시스템(예: Ubuntu)의 경우 다음을 사용합니다.

    sudo update-ca-certificates

    Red Hat 기반 Linux 시스템(예: CentOS, Fedora)의 경우 다음을 사용합니다.

    sudo update-ca-trust

    자세한 지침은 운영 체제와 관련된 설명서를 참조하세요.

SDK에서 에뮬레이터에 연결

각 SDK에는 일반적으로 SDK를 Azure Cosmos DB 계정에 연결하는 데 사용되는 클라이언트 클래스가 포함되어 있습니다. 에뮬레이터의 자격 증명 사용하여 SDK를 에뮬레이터 인스턴스에 대신 연결할 수 있습니다.

Azure Cosmos DB API for NoSQL .NET SDK를 사용하여 .NET 애플리케이션에서 에뮬레이터에 연결합니다.

  1. 빈 폴더에서 시작합니다.

  2. 새 .NET 콘솔 애플리케이션 만들기

    dotnet new console

  3. NuGet에서 Microsoft.Azure.Cosmos 패키지를 추가합니다.

    dotnet add package Microsoft.Azure.Cosmos

  4. Program.cs 파일을 엽니다.

  5. 파일 내의 기존 콘텐츠를 삭제합니다.

  6. Microsoft.Azure.Cosmos 네임스페이스에 using 블록을 추가합니다.

    using Microsoft.Azure.Cosmos;

  7. 에뮬레이터의 자격 증명을 사용하여 CosmosClient의 새 인스턴스를 만듭니다.

    using CosmosClient client = new(
    accountEndpoint: "https://localhost:8081/",
    authKeyOrResourceToken: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

  8. CreateDatabaseIfNotExistsAsync 및 CreateContainerIfNotExistsAsync를 사용하여 새 데이터베이스 및 컨테이너를 만듭니다.

    Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks",
    throughput: 400
);

Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/id"
);

  9. UpsertItemAsync를 사용하여 컨테이너에 새 항목을 만듭니다.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

await container.UpsertItemAsync(item);

  10. .NET 애플리케이션을 실행합니다.

    dotnet run

    Warning

    SSL 오류가 발생하면 애플리케이션에 대해 TLS/SSL을 사용하지 않도록 설정해야 할 수 있습니다. 이 오류는 일반적으로 컨테이너에서 Azure Cosmos DB 에뮬레이터를 사용하여 로컬 컴퓨터에서 개발하고 컨테이너의 SSL 인증서를 가져오지 않은 경우에 발생합니다. 이 문제를 해결하려면 클라이언트를 만들기 전에 TLS/SSL 유효성 검사를 사용하지 않도록 클라이언트의 옵션을 구성합니다.

    CosmosClientOptions options = new ()
{
    HttpClientFactory = () => new HttpClient(new HttpClientHandler()
    {
        ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    }),
    ConnectionMode = ConnectionMode.Gateway,
};

using CosmosClient client = new(
  ...,
  ...,
  clientOptions: options
);

팁

.NET SDK를 사용하여 수행할 수 있는 추가 작업은 .NET 개발자 가이드를 참조하세요.

MongoDB .NET 드라이버를 사용하여 .NET 애플리케이션에서 에뮬레이터에 연결합니다.

  1. 빈 폴더에서 시작합니다.

  2. 새 .NET 콘솔 애플리케이션 만들기

    dotnet new console

  3. NuGet에서 MongoDB.Driver 패키지를 추가합니다.

    dotnet add package MongoDB.Driver

  4. Program.cs 파일을 엽니다.

  5. 파일 내의 기존 콘텐츠를 삭제합니다.

  6. MongoDB.Driver 네임스페이스에 using 블록을 추가합니다.

    using MongoDB.Driver;

  7. 에뮬레이터의 자격 증명을 사용하여 MongoClient의 새 인스턴스를 만듭니다.

    var client = new MongoClient(
    "mongodb://localhost:C2y6yDjf5%2FR%2Bob0N8A7Cgv30VRDJIWEHLM%2B4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw%2FJw%3D%3D@localhost:10255/admin?ssl=true&retrywrites=false"
);

  8. GetDatabase 및 GetCollection<>을 사용하여 데이터베이스 및 컨테이너를 가져옵니다.

    var database = client.GetDatabase("cosmicworks");

var collection = database.GetCollection<dynamic>("products");

  9. InsertOneAsync를 사용하여 XXX에서 새 항목을 만듭니다.

    var item = new
{
    name = "Kiama classic surfboard"
};

await collection.InsertOneAsync(item);

  10. .NET 애플리케이션을 실행합니다.

    dotnet run

Apache Cassandra .NET 드라이버를 사용하여 .NET 애플리케이션에서 에뮬레이터에 연결합니다.

  1. 빈 폴더에서 시작합니다.

  2. 새 .NET 콘솔 애플리케이션 만들기

    dotnet new console

  3. NuGet에서 CassandraCSharpDriver 패키지를 추가합니다.

    dotnet add package CassandraCSharpDriver

  4. Program.cs 파일을 엽니다.

  5. 파일 내의 기존 콘텐츠를 삭제합니다.

  6. Cassandra 네임스페이스에 using 블록을 추가합니다.

    using Cassandra;

  7. 에뮬레이터의 자격 증명을 사용하여 Cluster의 새 인스턴스를 만듭니다. Connect를 사용하여 새 세션을 만듭니다.

    var options = new SSLOptions(
    sslProtocol: System.Security.Authentication.SslProtocols.Tls12,
    checkCertificateRevocation: true,
    remoteCertValidationCallback: (_, _, _, policyErrors) => policyErrors == System.Net.Security.SslPolicyErrors.None);

using var cluster = Cluster.Builder()
    .WithCredentials(
        username: "localhost",
        password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
    )
    .WithPort(
        port: 10350
    )
    .AddContactPoint(
        address: "localhost"
    )
    .WithSSL(
        sslOptions: options
    )
    .Build();

using var session = cluster.Connect();

  8. PrepareAsync 및 ExecuteAsync를 사용하여 새 데이터베이스 및 컨테이너를 만듭니다.

    var createKeyspace = await session.PrepareAsync("CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'basicclass', 'replication_factor': 1};");
await session.ExecuteAsync(createKeyspace.Bind());

var createTable = await session.PrepareAsync("CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)");
await session.ExecuteAsync(createTable.Bind());

  9. ExecuteAsync를 사용하여 테이블에 새 항목을 만듭니다. Bind를 사용하여 항목에 속성을 할당합니다.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

var createItem = await session.PrepareAsync("INSERT INTO cosmicworks.products (id, name) VALUES (?, ?)");

var createItemStatement = createItem.Bind(item.id, item.name);

await session.ExecuteAsync(createItemStatement);

  10. .NET 애플리케이션을 실행합니다.

    dotnet run

Important

시작하기 전에 Apache Gremlin용 API를 사용하려면 에뮬레이터에서 리소스를 만들어야 합니다. db1이라는 데이터베이스와 coll1이라는 컨테이너를 만듭니다. 처리량 설정은 이 가이드와 관련이 없으며 원하는 만큼 낮게 설정할 수 있습니다.

Apache Gremlin .NET 드라이버를 사용하여 .NET 애플리케이션에서 에뮬레이터에 연결합니다.

  1. 빈 폴더에서 시작합니다.

  2. 새 .NET 콘솔 애플리케이션 만들기

    dotnet new console

  3. NuGet에서 Gremlin.Net 패키지를 추가합니다.

    dotnet add package Gremlin.Net

  4. Program.cs 파일을 엽니다.

  5. 파일 내의 기존 콘텐츠를 삭제합니다.

  6. Gremlin.Net.Driver 네임스페이스에 using 블록을 추가합니다.

    using Gremlin.Net.Driver;

  7. 에뮬레이터의 자격 증명을 사용하여 GremlinServer 및 GremlinClient의 새 인스턴스를 만듭니다.

    var server = new GremlinServer(
    hostname: "localhost",
    port: 8901,
    username: "/dbs/db1/colls/coll1",
    password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

  8. SubmitAsync를 사용하여 그래프를 정리합니다.

    await client.SubmitAsync(
    requestScript: "g.V().drop()"
);

  9. SubmitAsync를 다시 사용하여 지정된 매개 변수로 새 항목을 그래프에 추가합니다.

    await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', prop_id).property('name', prop_name)",
    bindings: new Dictionary<string, object>
    {
        { "prop_id", "68719518371" },
        { "prop_name", "Kiama classic surfboard" }
    }
);

  10. .NET 애플리케이션을 실행합니다.

    dotnet run

Azure Tables SDK for .NET를 사용하여 .NET 애플리케이션에서 에뮬레이터에 연결합니다.

  1. 빈 폴더에서 시작합니다.

  2. 새 .NET 콘솔 애플리케이션 만들기

    dotnet new console

  3. NuGet에서 Azure.Data.Tables 패키지를 추가합니다.

    dotnet add package Azure.Data.Tables

  4. Program.cs 파일을 엽니다.

  5. 파일 내의 기존 콘텐츠를 삭제합니다.

  6. Azure.Data.Tables 네임스페이스에 using 블록을 추가합니다.

    using Azure.Data.Tables;

  7. 에뮬레이터의 자격 증명을 사용하여 TableServiceClient의 새 인스턴스를 만듭니다.

    var serviceClient = new TableServiceClient(
    connectionString: "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;"
);

  8. GetTableClient를 사용하여 테이블 이름으로 TableClient의 새 인스턴스를 만듭니다. 그런 다음 CreateIfNotExistsAsync를 사용하여 테이블이 존재하는지 확인합니다.

    var client = serviceClient.GetTableClient(
    tableName: "cosmicworksproducts"
);

await client.CreateIfNotExistsAsync();

  9. 항목에 대한 새 record 형식을 만듭니다.

    public record Product : Azure.Data.Tables.ITableEntity
{
    public required string RowKey { get; set; }

    public required string PartitionKey { get; set; }

    public required string Name { get; init; }

    public Azure.ETag ETag { get; set; }

    public DateTimeOffset? Timestamp { get; set; }
}

  10. UpsertEntityAsync를 사용하고 Replace 모드를 사용하여 테이블에 새 항목을 만듭니다.

    var item = new Product
{
    RowKey = "68719518371",
    PartitionKey = "Surfboards",
    Name = "Kiama classic surfboard",
    Timestamp = DateTimeOffset.Now
};

await client.UpsertEntityAsync(
    entity: item,
    mode: TableUpdateMode.Replace
);

  11. .NET 애플리케이션을 실행합니다.

    dotnet run

GitHub Actions CI 워크플로에서 에뮬레이터 사용

애플리케이션의 유효성을 자동으로 검사하는 연속 통합 워크로드를 실행하려면 선택한 프레임워크의 테스트 도구 모음과 함께 Azure Cosmos DB 에뮬레이터를 사용합니다. Azure Cosmos DB 에뮬레이터는 GitHub 작업의 호스트된 실행기의 windows-latest 변형에 미리 설치되어 있습니다.

.NET용 기본 제공 테스트 드라이버와 MSTest, NUnit, XUnit과 같은 테스트 프레임워크를 사용하여 테스트 도구 모음을 실행합니다.

  1. 애플리케이션에 대한 단위 테스트 도구 모음이 예상대로 작동하는지 확인합니다.

    dotnet test

  2. .github/workflows/ci.yml 파일에서 GitHub 리포지토리에 새 워크플로를 만듭니다.

  3. 워크플로에 PowerShell을 사용하여 Azure Cosmos DB 에뮬레이터를 시작하고 단위 테스트 도구 모음을 실행하는 작업을 추가합니다.

    name: Continuous Integration
on:
  push:
    branches:
      - main
jobs:
  unit_tests:
    name: Run .NET unit tests
    runs-on: windows-latest
    steps:
      - name: Checkout (GitHub)
        uses: actions/checkout@v3
      - name: Start Azure Cosmos DB emulator
        run: |
          Write-Host "Launching Cosmos DB Emulator"
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator
      - name: Run .NET tests
        run: dotnet test

    참고 항목

    다양한 인수 또는 PowerShell 명령을 사용하여 명령줄에서 에뮬레이터를 시작합니다. 자세한 내용은 에뮬레이터 명령줄 인수를 참조하세요.

다음 단계

에뮬레이터의 릴리스 정보 검토