Sdílet prostřednictvím

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

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 je image emulátoru dostupná na místním hostiteli 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 je image emulátoru dostupná na místním hostiteli 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.

    V systémech Linux použijte:

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

    Pro systémy Windows použijte:

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

    V systémech Linux použijte:

    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

    Pro systémy Windows použijte:

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

  1. Získejte certifikát ze spuštěného kontejneru.

    V systémech Linux použijte:

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

    Pro systémy Windows použijte:

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

  2. Znovu vygenerujte sadu certifikátů pomocí příslušného příkazu pro váš operační systém.

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

    sudo update-ca-certificates

    V systémech Linux založených na Red Hatu (například CentOS, Fedora) použijte:

    sudo update-ca-trust

    Pro systémy Windows použijte:

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

    Podrobnější pokyny najdete v dokumentaci specifické pro váš operační systém.

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

  1. Stáhněte si certifikát ze spuštěného kontejneru do místního počítače.

    V systémech Linux použijte:

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

    Pro systémy Windows použijte:

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

    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.

    V systémech Linux použijte:

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

    Pro systémy Windows použijte:

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

  3. V případě linuxových systémů znovu vygenerujte sadu certifikátů pomocí příslušného příkazu pro distribuci Linuxu.

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

    sudo update-ca-certificates

    V systémech Linux založených na Red Hatu (například CentOS, Fedora) použijte:

    sudo update-ca-trust

    Podrobnější pokyny najdete v dokumentaci specifické pro váš operační systém.

Připojení k 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

Pokud chcete spustit úlohu kontinuální integrace, která automaticky ověří vaši aplikaci, použijte emulátor služby Azure Cosmos DB s testovací sadou z libovolné architektury. 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.