Programowanie lokalnie przy użyciu emulatora usługi Azure Cosmos DB

  • Artykuł

Typowym przypadkiem użycia emulatora jest użycie jako bazy danych deweloperskich podczas kompilowania aplikacji. Korzystanie z emulatora na potrzeby programowania może ułatwić poznanie cech tworzenia i modelowania danych dla bazy danych, takiej jak Azure Cosmos DB, bez ponoszenia kosztów usług. Ponadto użycie emulatora w ramach przepływu pracy automatyzacji może zapewnić, że można uruchomić ten sam zestaw testów integracji. Możesz mieć pewność, że te same testy są uruchamiane lokalnie na komputerze deweloperskim i zdalnie w ramach zadania ciągłej integracji.

Wymagania wstępne

  • .NET 6 lub nowszy, Node.js LTS lub Python 3.7 lub nowszy
    • Upewnij się, że wszystkie wymagane pliki wykonywalne są dostępne w pliku PATH.
  • Emulator systemu Windows
    • 64-bitowy system Windows Server 2016, 2019, Windows 10 lub Windows 11.
    • Minimalne wymagania sprzętowe:
      • 2 GB pamięci RAM
      • 10 GB dostępnego miejsca na dysku twardym
  • Emulator platformy Docker

Instalowanie emulatora

Istnieje wiele odmian emulatora, a każda odmiana ma stosunkowo bezproblemowy proces instalacji.

Aby rozpocząć, pobierz wariant systemu Linux obrazu kontenera z rejestru Microsoft Container Registry (MCR).

  1. Ściąganie mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator obrazu kontenera systemu Linux z rejestru kontenerów do lokalnego hosta platformy Docker.

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

  2. Upewnij się, że obraz emulatora został ściągnięty do lokalnego hosta platformy Docker.

    docker images

Aby rozpocząć, pobierz wariant systemu Linux obrazu kontenera z rejestru Microsoft Container Registry (MCR).

  1. Ściąganie mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator obrazu kontenera systemu Linux przy użyciu tagu mongodb z rejestru kontenerów do lokalnego hosta platformy Docker.

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

  2. Upewnij się, że obraz emulatora został ściągnięty do lokalnego hosta platformy Docker.

    docker images

Wariant kontenera platformy Docker (Linux lub Windows) emulatora nie obsługuje interfejsu API dla systemu Apache Cassandra, interfejsu API dla języka Apache Gremlin lub interfejsu API dla tabeli.

Uruchamianie emulatora

Po pobraniu uruchom emulator z włączonym określonym interfejsem API.

Wariant kontenera platformy Docker emulatora nie obsługuje interfejsu API dla systemu Apache Cassandra.

Wariant kontenera platformy Docker emulatora nie obsługuje interfejsu API dla języka Apache Gremlin.

Wariant kontenera platformy Docker emulatora nie obsługuje interfejsu API dla tabeli.

  1. Uruchom nowy kontener przy użyciu obrazu kontenera i następującej konfiguracji:

    opis
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Opcjonalnie) Określ liczbę partycji do użycia.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Opcjonalnie) Włącz trwałość danych między przebiegami emulatora.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opcjonalnie) Zastąp domyślny adres IP emulatora. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Przejdź do witryny , https://localhost:8081/_explorer/index.html aby uzyskać dostęp do eksploratora danych.

  1. Uruchom nowy kontener przy użyciu obrazu kontenera i następującej konfiguracji:

    opis
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Określ wersję punktu końcowego bazy danych MongoDB do użycia. Obsługiwane punkty końcowe obejmują: 3.2, lub 3.64.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Opcjonalnie) Określ liczbę partycji do użycia.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Opcjonalnie) Włącz trwałość danych między przebiegami emulatora.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Opcjonalnie) Zastąp domyślny adres IP emulatora. 
    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Przejdź do witryny , https://localhost:8081/_explorer/index.html aby uzyskać dostęp do eksploratora danych.

Importowanie certyfikatu TLS/SSL emulatora

Zaimportuj certyfikat TLS/SSL emulatora do korzystania z preferowanego zestawu SDK dla deweloperów bez wyłączania protokołu TLS/SSL na kliencie.

Wariant kontenera platformy Docker (Linux lub Windows) emulatora nie obsługuje interfejsu API dla systemu Apache Cassandra, interfejsu API dla języka Apache Gremlin lub interfejsu API dla tabeli.

Certyfikat emulatora jest dostępny w ścieżce _explorer/emulator.pem uruchomionego kontenera. Użyj polecenia curl , aby pobrać certyfikat z uruchomionego kontenera na komputer lokalny.

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

Certyfikat emulatora jest dostępny w ścieżce _explorer/emulator.pem uruchomionego kontenera.

  1. Użyj polecenia curl , aby pobrać certyfikat z uruchomionego kontenera na komputer lokalny.

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

    Uwaga

    Może być konieczne zmianę hosta (lub adresu IP) i numeru portu, jeśli wcześniej zmodyfikowano te wartości.

  2. Zainstaluj certyfikat zgodnie z procesem zwykle używanym dla systemu operacyjnego. Na przykład w systemie Linux należy skopiować certyfikat do ścieżki /usr/local/share/ca-certificates/ .

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

  3. Zaktualizuj certyfikaty urzędu certyfikacji i ponownie wygeneruj pakiet certyfikatów przy użyciu odpowiedniego polecenia dla dystrybucji systemu Linux.

    W przypadku systemów opartych na debianie (np. Ubuntu) użyj:

    sudo update-ca-certificates

    W przypadku systemów opartych na systemie Red Hat (np. CentOS, Fedora) użyj:

    sudo update-ca-trust

    Aby uzyskać bardziej szczegółowe instrukcje, zapoznaj się z dokumentacją specyficzną dla dystrybucji systemu Linux.

Połączenie do emulatora z zestawu SDK

Każdy zestaw SDK zawiera klasę klienta zwykle używaną do łączenia zestawu SDK z kontem usługi Azure Cosmos DB. Korzystając z poświadczeń emulatora, można zamiast tego połączyć zestaw SDK z wystąpieniem emulatora.

Użyj interfejsu API usługi Azure Cosmos DB dla zestawu .NET SDK noSQL, aby nawiązać połączenie z emulatorem z poziomu aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Microsoft.Azure.Cosmos Dodaj pakiet z narzędzia NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Otwórz plik Program.cs.

  5. Usuń dowolną istniejącą zawartość w pliku.

  6. Dodaj blok using dla Microsoft.Azure.Cosmos przestrzeni nazw.

    using Microsoft.Azure.Cosmos;

  7. Utwórz nowe wystąpienie CosmosClient przy użyciu poświadczeń emulatora.

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

  8. Utwórz nową bazę danych i kontener przy użyciu narzędzi CreateDatabaseIfNotExistsAsync i CreateContainerIfNotExistsAsync.

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

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

  9. Utwórz nowy element w kontenerze przy użyciu polecenia UpsertItemAsync.

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

await container.UpsertItemAsync(item);

  10. Uruchom aplikację .NET.

    dotnet run

    Ostrzeżenie

    Jeśli wystąpi błąd SSL, może być konieczne wyłączenie protokołu TLS/SSL dla aplikacji. Dzieje się tak często, jeśli programujesz na komputerze lokalnym przy użyciu emulatora usługi Azure Cosmos DB w kontenerze i nie zaimportował certyfikatu SSL kontenera. Aby rozwiązać ten problem, skonfiguruj opcje klienta, aby wyłączyć walidację protokołu TLS/SSL przed utworzeniem klienta:

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

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

Napiwek

Zapoznaj się z przewodnikiem dla deweloperów platformy .NET, aby uzyskać więcej operacji, które można wykonać przy użyciu zestawu .NET SDK.

Użyj sterownika .NET bazy danych MongoDB, aby nawiązać połączenie z emulatorem z poziomu aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. MongoDB.Driver Dodaj pakiet z narzędzia NuGet.

    dotnet add package MongoDB.Driver

  4. Otwórz plik Program.cs.

  5. Usuń dowolną istniejącą zawartość w pliku.

  6. Dodaj blok using dla MongoDB.Driver przestrzeni nazw.

    using MongoDB.Driver;

  7. Utwórz nowe wystąpienie MongoClient przy użyciu poświadczeń emulatora.

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

  8. Pobierz bazę danych i kontener przy użyciu polecenia GetDatabase i GetCollection<>.

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

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

  9. Utwórz nowy element w XXX przy użyciu polecenia InsertOneAsync.

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

await collection.InsertOneAsync(item);

  10. Uruchom aplikację .NET.

    dotnet run

Użyj sterownika .NET apache Cassandra, aby nawiązać połączenie z emulatorem z poziomu aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. CassandraCSharpDriver Dodaj pakiet z narzędzia NuGet.

    dotnet add package CassandraCSharpDriver

  4. Otwórz plik Program.cs.

  5. Usuń dowolną istniejącą zawartość w pliku.

  6. Dodaj blok using dla Cassandra przestrzeni nazw.

    using Cassandra;

  7. Utwórz nowe wystąpienie Cluster przy użyciu poświadczeń emulatora. Utwórz nową sesję przy użyciu polecenia 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. Utwórz nową bazę danych i kontener przy użyciu narzędzi PrepareAsync i 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. Utwórz nowy element w tabeli przy użyciu polecenia ExecuteAsync. Służy Bind do przypisywania właściwości do elementu.

    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. Uruchom aplikację .NET.

    dotnet run

Ważne

Przed rozpoczęciem interfejs API dla języka Apache Gremlin wymaga utworzenia zasobów w emulatorze. Utwórz bazę danych o nazwie db1 i kontener o nazwie coll1. Ustawienia przepływności są nieistotne dla tego przewodnika i można je ustawić tak mało, jak chcesz.

Użyj sterownika platformy .NET platformy Apache Gremlin, aby nawiązać połączenie z emulatorem z poziomu aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Gremlin.Net Dodaj pakiet z narzędzia NuGet.

    dotnet add package Gremlin.Net

  4. Otwórz plik Program.cs.

  5. Usuń dowolną istniejącą zawartość w pliku.

  6. Dodaj blok using dla Gremlin.Net.Driver przestrzeni nazw.

    using Gremlin.Net.Driver;

  7. Utwórz nowe wystąpienie i GremlinServerGremlinClient użyj poświadczeń emulatora.

    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. Wyczyść graf przy użyciu polecenia SubmitAsync.

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

  9. Ponownie użyj SubmitAsync polecenia , aby dodać nowy element do grafu z określonymi parametrami.

    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. Uruchom aplikację .NET.

    dotnet run

Użyj zestawu Azure Tables SDK dla platformy .NET , aby nawiązać połączenie z emulatorem z poziomu aplikacji platformy .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Azure.Data.Tables Dodaj pakiet z narzędzia NuGet.

    dotnet add package Azure.Data.Tables

  4. Otwórz plik Program.cs.

  5. Usuń dowolną istniejącą zawartość w pliku.

  6. Dodaj blok using dla Azure.Data.Tables przestrzeni nazw.

    using Azure.Data.Tables;

  7. Utwórz nowe wystąpienie TableServiceClient przy użyciu poświadczeń emulatora.

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

  8. Użyj GetTableClient polecenia , aby utworzyć nowe wystąpienie TableClient obiektu o nazwie tabeli. Następnie upewnij się, że tabela istnieje przy użyciu polecenia CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Utwórz nowy record typ dla elementów.

    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. Utwórz nowy element w tabeli przy użyciu i UpsertEntityAsync tryb.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. Uruchom aplikację .NET.

    dotnet run

Korzystanie z emulatora w przepływie pracy ciągłej integracji funkcji GitHub Actions

Użyj emulatora usługi Azure Cosmos DB z zestawem testów z wybranej platformy, aby uruchomić obciążenie ciągłej integracji, które automatycznie weryfikuje aplikację. Emulator usługi Azure Cosmos DB jest wstępnie zainstalowany w wariantach windows-latest hostowanych modułów uruchamianych w usłudze GitHub Action.

Uruchom zestaw testów przy użyciu wbudowanego sterownika testowego dla platformy .NET i platformy testowej, takiej jak MSTest, NUnit lub XUnit.

  1. Sprawdź, czy zestaw testów jednostkowych dla aplikacji działa zgodnie z oczekiwaniami.

    dotnet test

  2. Utwórz nowy przepływ pracy w repozytorium GitHub w pliku o nazwie .github/workflows/ci.yml.

  3. Dodaj zadanie do przepływu pracy, aby uruchomić emulator usługi Azure Cosmos DB przy użyciu programu PowerShell i uruchomić zestaw testów jednostkowych.

    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

    Uwaga

    Uruchom emulator z wiersza polecenia przy użyciu różnych argumentów lub poleceń programu PowerShell. Aby uzyskać więcej informacji, zobacz argumenty wiersza polecenia emulatora.

Następny krok

Przejrzyj informacje o wersji emulatora