Programowanie lokalne przy użyciu emulatora Azure Cosmos DB

  • Dotyczy: ✅ NoSQL

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, takich 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.

Prerequisites

Instalowanie emulatora

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

Aby rozpocząć, pobierz wariant Linux obrazu kontenera z 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 jest dostępny na lokalnym hoście platformy Docker.

    docker images

Aby rozpocząć, pobierz wariant Linux obrazu kontenera z 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:latest

  2. Upewnij się, że obraz emulatora jest dostępny na lokalnym hoście platformy Docker.

    docker images

Wariant kontenera platformy Docker (Linux lub Windows) emulatora nie obsługuje interfejsu API dla platformy 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 emulatora w kontenerze Docker nie obsługuje API Apache Gremlin.

Wariant kontenera Docker emulatora nie obsługuje interfejsu API dla tabeli (Table).

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

    Description
    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.

    W przypadku systemów Linux użyj:

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

    W przypadku systemów Windows należy użyć:

    $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. 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:

    Description
    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.

    W przypadku systemów Linux użyj:

    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

    W przypadku systemów Windows należy użyć:

    $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. 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 platformy 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.

  1. Pobierz certyfikat z uruchomionego kontenera.

    W przypadku systemów Linux użyj:

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

    W przypadku systemów Windows należy użyć:

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

  2. Wygeneruj ponownie pakiet certyfikatów przy użyciu odpowiedniego polecenia dla systemu operacyjnego.

    W przypadku systemów Linux opartych na debianie (na przykład Ubuntu) użyj:

    sudo update-ca-certificates

    W przypadku systemów Linux opartych na systemie Red Hat (na przykład CentOS, Fedora) użyj:

    sudo update-ca-trust

    W przypadku systemów Windows należy użyć:

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

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

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

  1. Pobierz certyfikat z uruchomionego kontenera na komputer lokalny.

    W przypadku systemów Linux użyj:

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

    W przypadku systemów Windows należy użyć:

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

    Uwaga / Notatka

    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/ .

    W przypadku systemów Linux użyj:

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

    W przypadku systemów Windows należy użyć:

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

  3. W przypadku systemów Linux ponownie wygeneruj pakiet certyfikatów przy użyciu odpowiedniego polecenia dla dystrybucji systemu Linux.

    W przypadku systemów Linux opartych na debianie (na przykład Ubuntu) użyj:

    sudo update-ca-certificates

    W przypadku systemów Linux opartych na systemie Red Hat (na przykład CentOS, Fedora) użyj:

    sudo update-ca-trust

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

Nawiązywanie połączenia z emulatorem z zestawu SDK

Każdy zestaw SDK zawiera klasę klienta zwykle używaną do łączenia zestawu SDK z kontem 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 Azure Cosmos DB dla zestawu SDK NoSQL .NET aby nawiązać połączenie z emulatorem z aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Dodaj pakiet Microsoft.Azure.Cosmos z 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 przestrzeni nazw Microsoft.Azure.Cosmos.

    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

    Warning

    Jeśli wystąpi błąd SSL, może być konieczne wyłączenie protokołu TLS/SSL dla aplikacji. Dzieje się to często, jeśli programujesz na komputerze lokalnym, używając emulatora Azure Cosmos DB w kontenerze i nie zaimportowałeś 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
);

Wskazówka

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

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

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Dodaj pakiet MongoDB.Driver z 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 przestrzeni nazw MongoDB.Driver.

    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 Apache Cassandra .NET aby nawiązać połączenie z emulatorem z aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Dodaj pakiet CassandraCSharpDriver z NuGet.

    dotnet add package CassandraCSharpDriver

  4. Otwórz plik Program.cs.

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

  6. Dodaj blok using dla przestrzeni nazw Cassandra.

    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żna

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 Apache Gremlin .NET aby nawiązać połączenie z emulatorem z aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Dodaj pakiet Gremlin.Net z 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 przestrzeni nazw Gremlin.Net.Driver.

    using Gremlin.Net.Driver;

  7. Utwórz nowe wystąpienie GremlinServer oraz GremlinClient używając poświadczeń emulatora.

    var server = new GremlinServer(
    hostname: "localhost",
    port: 65400,
    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 SDK Azure Tables dla .NET, aby nawiązać połączenie z emulatorem z aplikacji .NET.

  1. Rozpocznij w pustym folderze.

  2. Tworzenie nowej aplikacji konsolowej .NET

    dotnet new console

  3. Dodaj pakiet Azure.Data.Tables z 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 przestrzeni nazw Azure.Data.Tables.

    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 do utworzenia nowej instancji TableClient z nazwą 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 UpsertEntityAsync oraz trybu 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

Użyj emulatora w przepływie pracy CI na GitHub Actions

Aby uruchomić obciążenie ciągłej integracji, które automatycznie weryfikuje aplikację, użyj emulatora Azure Cosmos DB z wybranym zestawem testów. Emulator Azure Cosmos DB jest wstępnie zainstalowany w wersji windows-latest hostowanych środowisk uruchomieniowych GitHub Actions.

Uruchom zestaw testów przy użyciu wbudowanego sterownika testowego dla .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 Azure Cosmos DB przy użyciu programu PowerShell i uruchomić pakiet 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 / Notatka

    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ępne kroki

Przejrzyj informacje o wersji emulatora

  • Last updated on