Vývoj místně pomocí emulátoru služby Azure Cosmos DB

  • Článek

Běžným případem použití emulátoru je sloužit jako vývojová databáze při vytváření aplikací. Použití emulátoru pro vývoj vám může pomoct naučit se charakteristiky vytváření a modelování dat pro databázi, jako je Azure Cosmos DB, aniž by vám vznikly jakékoli náklady na služby. Kromě toho můžete pomocí emulátoru v rámci pracovního postupu automatizace zajistit, abyste mohli spustit stejnou sadu integračních testů. Můžete zajistit, aby se stejné testy spouštěly místně na vývojovém počítači i vzdáleně v úloze kontinuální integrace.

Požadavky

  • .NET 6 nebo novější, Node.js LTS nebo Python 3.7 nebo novější
    • Ujistěte se, že jsou ve vašem souboru PATHk dispozici všechny požadované spustitelné soubory .
  • Emulátor Windows
    • 64bitová verze Windows Serveru 2016, 2019, Windows 10 nebo Windows 11.
    • Minimální požadavky na hardware:
      • 2 GB paměti RAM
      • 10 GB volného místa na disku
  • Emulátor Dockeru

Instalace emulátoru

Emulátor má několik variant a každá varianta má relativně bezproblémový proces instalace.

Začněte tím, že z Microsoft Container Registry (MCR) získáte linuxovou variantu image kontejneru.

  1. Stáhněte image kontejneru mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linuxu z registru kontejneru do místního hostitele Dockeru.

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

  2. Zkontrolujte, jestli se image emulátoru přetáhla na místního hostitele Dockeru.

    docker images

Začněte tím, že z Microsoft Container Registry (MCR) získáte linuxovou variantu image kontejneru.

  1. Stáhněte image kontejneru mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linuxu pomocí mongodb značky z registru kontejneru do místního hostitele Dockeru.

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

  2. Zkontrolujte, jestli se image emulátoru přetáhla na místního hostitele Dockeru.

    docker images

Varianta kontejneru Dockeru (Linux nebo Windows) emulátoru nepodporuje rozhraní API pro Apache Cassandra, rozhraní API pro Apache Gremlin nebo api for Table.

Spusťte emulátor.

Po stažení spusťte emulátor s povoleným zadaným rozhraním API.

Varianta kontejneru Dockeru emulátoru nepodporuje rozhraní API pro Apache Cassandra.

Varianta kontejneru Dockeru emulátoru nepodporuje rozhraní API pro Apache Gremlin.

Varianta kontejneru Dockeru emulátoru nepodporuje rozhraní API pro tabulku.

  1. Spusťte nový kontejner pomocí image kontejneru a následující konfigurace:

    Popis
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Volitelné) Zadejte počet oddílů, které se mají použít.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Volitelné) Povolte trvalost dat mezi spuštěními emulátoru.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Volitelné) Přepište výchozí IP adresu emulátoru. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Přejděte do https://localhost:8081/_explorer/index.html Průzkumníka dat.

  1. Spusťte nový kontejner pomocí image kontejneru a následující konfigurace:

    Popis
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Zadejte verzi koncového bodu MongoDB, který se má použít. Mezi podporované koncové body patří: 3.2, 3.6nebo 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Volitelné) Zadejte počet oddílů, které se mají použít.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Volitelné) Povolte trvalost dat mezi spuštěními emulátoru.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Volitelné) Přepište výchozí IP adresu emulátoru. 
    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. Přejděte do https://localhost:8081/_explorer/index.html Průzkumníka dat.

Import certifikátu TLS/SSL emulátoru

Importujte certifikát TLS/SSL emulátoru tak, aby používal emulátor s upřednostňovanou sadou DEVELOPER SDK bez zakázání protokolu TLS/SSL v klientovi.

Varianta kontejneru Dockeru (Linux nebo Windows) emulátoru nepodporuje rozhraní API pro Apache Cassandra, rozhraní API pro Apache Gremlin nebo api for Table.

Certifikát pro emulátor je k dispozici v cestě _explorer/emulator.pem spuštěného kontejneru. Slouží curl ke stažení certifikátu ze spuštěného kontejneru do místního počítače.

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

Certifikát pro emulátor je k dispozici v cestě _explorer/emulator.pem spuštěného kontejneru.

  1. Slouží curl ke stažení certifikátu ze spuštěného kontejneru do místního počítače.

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

    Poznámka:

    Pokud jste tyto hodnoty dříve upravili, možná budete muset změnit hostitele (nebo IP adresu) a číslo portu.

  2. Nainstalujte certifikát podle procesu, který se obvykle používá pro váš operační systém. V Linuxu byste například zkopírovali certifikát do /usr/local/share/ca-certificates/ cesty.

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

  3. Aktualizujte certifikáty certifikační autority a znovu vygenerujte sadu certifikátů pomocí příslušného příkazu pro vaši linuxovou distribuci.

    Pro systémy založené na Debianu (např. Ubuntu) použijte:

    sudo update-ca-certificates

    Pro systémy založené na Red Hatu (např. CentOS, Fedora) použijte:

    sudo update-ca-trust

    Podrobnější pokyny najdete v dokumentaci specifické pro vaši linuxovou distribuci.

Připojení do emulátoru ze sady SDK

Každá sada SDK obsahuje klientskou třídu, která se obvykle používá k připojení sady SDK k vašemu účtu služby Azure Cosmos DB. Pomocí přihlašovacích údajů emulátoru můžete místo toho připojit sadu SDK k instanci emulátoru.

K připojení k emulátoru z aplikace .NET použijte rozhraní API služby Azure Cosmos DB for NoSQL .NET SDK .

  1. Začněte v prázdné složce.

  2. Vytvoření nové konzolové aplikace .NET

    dotnet new console

  3. Microsoft.Azure.Cosmos Přidejte balíček z NuGetu.

    dotnet add package Microsoft.Azure.Cosmos

  4. Otevřete soubor Program.cs.

  5. Odstraňte veškerý existující obsah v souboru.

  6. Přidejte blok using pro Microsoft.Azure.Cosmos obor názvů.

    using Microsoft.Azure.Cosmos;

  7. Vytvořte novou instanci pomocí přihlašovacích CosmosClient údajů emulátoru.

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

  8. Vytvoření nové databáze a kontejneru pomocí CreateDatabaseIfNotExistsAsync a CreateContainerIfNotExistsAsync.

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

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

  9. Vytvoření nové položky v kontejneru pomocí UpsertItemAsync.

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

await container.UpsertItemAsync(item);

  10. Spusťte aplikaci .NET.

    dotnet run

    Upozorňující

    Pokud se zobrazí chyba SSL, možná budete muset pro svou aplikaci zakázat protokol TLS/SSL. K tomu obvykle dochází v případě, že vyvíjíte na místním počítači, používáte emulátor služby Azure Cosmos DB v kontejneru a nenaimportovali certifikát SSL kontejneru. Pokud chcete tento problém vyřešit, nakonfigurujte možnosti klienta tak, aby před vytvořením klienta zakázaly ověřování TLS/SSL:

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

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

Tip

Další operace, které můžete provádět pomocí sady .NET SDK, najdete v příručce pro vývojáře .NET.

Pomocí ovladače MongoDB .NET se připojte k emulátoru z aplikace .NET.

  1. Začněte v prázdné složce.

  2. Vytvoření nové konzolové aplikace .NET

    dotnet new console

  3. MongoDB.Driver Přidejte balíček z NuGetu.

    dotnet add package MongoDB.Driver

  4. Otevřete soubor Program.cs.

  5. Odstraňte veškerý existující obsah v souboru.

  6. Přidejte blok using pro MongoDB.Driver obor názvů.

    using MongoDB.Driver;

  7. Vytvořte novou instanci pomocí přihlašovacích MongoClient údajů emulátoru.

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

  8. Získejte databázi a kontejner pomocí GetDatabase a GetCollection<>.

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

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

  9. Vytvořit novou položku v XXX pomocí InsertOneAsync.

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

await collection.InsertOneAsync(item);

  10. Spusťte aplikaci .NET.

    dotnet run

Pomocí ovladače Apache Cassandra .NET se připojte k emulátoru z aplikace .NET.

  1. Začněte v prázdné složce.

  2. Vytvoření nové konzolové aplikace .NET

    dotnet new console

  3. CassandraCSharpDriver Přidejte balíček z NuGetu.

    dotnet add package CassandraCSharpDriver

  4. Otevřete soubor Program.cs.

  5. Odstraňte veškerý existující obsah v souboru.

  6. Přidejte blok using pro Cassandra obor názvů.

    using Cassandra;

  7. Vytvořte novou instanci pomocí přihlašovacích Cluster údajů emulátoru. Vytvořte novou relaci pomocí Connectpříkazu .

    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. Vytvoření nové databáze a kontejneru pomocí PrepareAsync a 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. Vytvoření nové položky v tabulce pomocí ExecuteAsync. Slouží Bind k přiřazení vlastností k položce.

    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. Spusťte aplikaci .NET.

    dotnet run

Důležité

Než začnete, rozhraní API pro Apache Gremlin vyžaduje vytvoření prostředků v emulátoru. Vytvořte databázi s názvem db1 a kontejner s názvem coll1. Nastavení propustnosti jsou pro tuto příručku irelevantní a můžete je nastavit tak nízké, jak chcete.

Pomocí ovladače Apache Gremlin .NET se připojte k emulátoru z aplikace .NET.

  1. Začněte v prázdné složce.

  2. Vytvoření nové konzolové aplikace .NET

    dotnet new console

  3. Gremlin.Net Přidejte balíček z NuGetu.

    dotnet add package Gremlin.Net

  4. Otevřete soubor Program.cs.

  5. Odstraňte veškerý existující obsah v souboru.

  6. Přidejte blok using pro Gremlin.Net.Driver obor názvů.

    using Gremlin.Net.Driver;

  7. Vytvořte novou instanci GremlinServer a GremlinClient použijte přihlašovací údaje emulátoru.

    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. Vyčistěte graf pomocí SubmitAsync.

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

  9. Znovu použijte SubmitAsync k přidání nové položky do grafu se zadanými parametry.

    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. Spusťte aplikaci .NET.

    dotnet run

Pomocí sady Azure Tables SDK pro .NET se připojte k emulátoru z aplikace .NET.

  1. Začněte v prázdné složce.

  2. Vytvoření nové konzolové aplikace .NET

    dotnet new console

  3. Azure.Data.Tables Přidejte balíček z NuGetu.

    dotnet add package Azure.Data.Tables

  4. Otevřete soubor Program.cs.

  5. Odstraňte veškerý existující obsah v souboru.

  6. Přidejte blok using pro Azure.Data.Tables obor názvů.

    using Azure.Data.Tables;

  7. Vytvořte novou instanci pomocí přihlašovacích TableServiceClient údajů emulátoru.

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

  8. Slouží GetTableClient k vytvoření nové instance TableClient s názvem tabulky. Pak se ujistěte, že tabulka existuje pomocí CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Vytvořte nový record typ pro položky.

    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. Vytvořte novou položku v tabulce pomocí UpsertEntityAsync a Replace režimu.

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

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

  11. Spusťte aplikaci .NET.

    dotnet run

Použití emulátoru v pracovním postupu CI GitHub Actions

Pomocí emulátoru služby Azure Cosmos DB s testovací sadou z zvolené architektury spusťte úlohu kontinuální integrace, která automaticky ověří vaši aplikaci. Emulátor služby Azure Cosmos DB je předinstalovaný ve windows-latest variantě hostovaných spouštěčů GitHub Action.

Spusťte sadu testů pomocí integrovaného testovacího ovladače pro .NET a testovací architektury, jako je MSTest, NUnit nebo XUnit.

  1. Ověřte, že sada testů jednotek pro vaši aplikaci funguje podle očekávání.

    dotnet test

  2. Vytvořte nový pracovní postup v úložišti GitHub v souboru s názvem .github/workflows/ci.yml.

  3. Přidejte do pracovního postupu úlohu pro spuštění emulátoru služby Azure Cosmos DB pomocí PowerShellu a spuštění sady testů jednotek.

    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

    Poznámka:

    Spusťte emulátor z příkazového řádku pomocí různých argumentů nebo příkazů PowerShellu. Další informace najdete v tématu Argumenty příkazového řádku emulátoru.

Další krok

Projděte si poznámky k verzi emulátoru.