Développer localement avec l’émulateur Azure Cosmos DB

  • Article

Un cas d’usage courant pour l’émulateur consiste à servir de base de données de développement pendant que vous générez vos applications. L’utilisation de l’émulateur pour le développement peut vous aider à découvrir les caractéristiques de création et de modélisation des données pour une base de données comme Azure Cosmos DB sans entraîner de coûts de service. En outre, l’utilisation de l’émulateur dans le cadre d’un workflow d’automatisation peut vous permettre d’exécuter la même suite de tests d’intégration. Vous pouvez vous assurer que les mêmes tests s’exécutent localement sur votre ordinateur de développement et à distance dans un travail d’intégration continue.

Prérequis

Installer l’émulateur

Il existe plusieurs variantes de l’émulateur et chaque variante a un processus d’installation relativement fluide.

Pour commencer, récupérez la variante Linux de l’image conteneur à partir de Microsoft Container Registry (MCR).

  1. Extrayez l’image mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator conteneur Linux du registre de conteneurs vers l’hôte Docker local.

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

  2. Vérifiez si l’image de l’émulateur est disponible sur votre hôte Docker local.

    docker images

Pour commencer, récupérez la variante Linux de l’image conteneur à partir de Microsoft Container Registry (MCR).

  1. Extrayez l’image mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator conteneur Linux à l’aide de la mongodb balise du registre de conteneurs vers l’hôte Docker local.

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

  2. Vérifiez si l’image de l’émulateur est disponible sur votre hôte Docker local.

    docker images

La variante de conteneur Docker (Linux ou Windows) de l’émulateur ne prend pas en charge l’API pour Apache Cassandra, l’API pour Apache Gremlin ou l’API pour Table.

Démarrer l’émulateur

Une fois téléchargé, démarrez l’émulateur avec votre API spécifiée activée.

La variante de conteneur Docker de l’émulateur ne prend pas en charge l’API pour Apache Cassandra.

La variante de conteneur Docker de l’émulateur ne prend pas en charge l’API pour Apache Gremlin.

La variante de conteneur Docker de l’émulateur ne prend pas en charge l’API pour Table.

  1. Exécutez un nouveau conteneur à l’aide de l’image conteneur et de la configuration suivante :

    Description
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Facultatif) Spécifiez le nombre de partitions à utiliser.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Facultatif) Activer la persistance des données entre les exécutions de l’émulateur.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Facultatif) Remplacez l’adresse IP par défaut de l’émulateur.

    Pour les systèmes Linux, utilisez :

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

    Pour les systèmes Windows, utilisez :

    $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. Accédez à https://localhost:8081/_explorer/index.html pour accéder à l’Explorateur de données.

  1. Exécutez un nouveau conteneur à l’aide de l’image conteneur et de la configuration suivante :

    Description
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Spécifiez la version du point de terminaison MongoDB à utiliser. Les points de terminaison pris en charge sont les suivants : 3.2, 3.6ou 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(Facultatif) Spécifiez le nombre de partitions à utiliser.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(Facultatif) Activer la persistance des données entre les exécutions de l’émulateur.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(Facultatif) Remplacez l’adresse IP par défaut de l’émulateur.

    Pour les systèmes Linux, utilisez :

    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

    Pour les systèmes Windows, utilisez :

    $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. Accédez à https://localhost:8081/_explorer/index.html pour accéder à l’Explorateur de données.

Importer le certificat TLS/SSL de l'émulateur

Importez le certificat TLS/SSL de l'émulateur pour utiliser l'émulateur avec votre kit SDK de développement préféré sans désactiver TLS/SSL sur le client.

La variante de conteneur Docker (Linux ou Windows) de l’émulateur ne prend pas en charge l’API pour Apache Cassandra, l’API pour Apache Gremlin ou l’API pour Table.

Le certificat de l'émulateur est disponible sur le chemin d'accès _explorer/emulator.pem sur le conteneur en cours d'exécution. Utilisez curl pour télécharger le certificat depuis conteneur en cours d’exécution sur votre ordinateur local.

  1. Obtenez le certificat à partir du conteneur en cours d’exécution.

    Pour les systèmes Linux, utilisez :

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

    Pour les systèmes Windows, utilisez :

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

  2. Regénérez le bundle de certificats à l’aide de la commande appropriée pour votre système d’exploitation.

    Pour les systèmes Linux basés sur Debian (par exemple Ubuntu), utilisez :

    sudo update-ca-certificates

    Pour les systèmes Linux basés sur Red Hat (par exemple CentOS, Fedora), utilisez :

    sudo update-ca-trust

    Pour les systèmes Windows, utilisez :

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

    Pour obtenir des instructions plus détaillées, consultez la documentation spécifique à votre système d’exploitation.

Le certificat de l'émulateur est disponible sur le chemin d'accès /_explorer/emulator.pem sur le conteneur en cours d'exécution.

  1. Téléchargez le certificat du conteneur en cours d’exécution sur votre machine locale.

    Pour les systèmes Linux, utilisez :

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

    Pour les systèmes Windows, utilisez :

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

    Remarque

    Il peut être nécessaire de changer l’hôte (ou l’adresse IP) et le numéro de port si vous avez déjà modifié ces valeurs.

  2. Installez le certificat selon le processus généralement utilisé pour votre système d’exploitation. Par exemple dans Linux, vous copiez le certificat dans le chemin /usr/local/share/ca-certificates/.

    Pour les systèmes Linux, utilisez :

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

    Pour les systèmes Windows, utilisez :

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

  3. Pour les systèmes Linux, regénérez le bundle de certificats à l’aide de la commande appropriée pour votre distribution Linux.

    Pour les systèmes Linux basés sur Debian (par exemple Ubuntu), utilisez :

    sudo update-ca-certificates

    Pour les systèmes Linux basés sur Red Hat (par exemple CentOS, Fedora), utilisez :

    sudo update-ca-trust

    Pour obtenir des instructions plus détaillées, consultez la documentation spécifique à votre système d’exploitation.

Se connecter à l’émulateur à partir du Kit de développement logiciel (SDK)

Chaque KIT de développement logiciel (SDK) inclut une classe de client généralement utilisée pour connecter le KIT de développement logiciel (SDK) à votre compte Azure Cosmos DB. En utilisant les informations d'identification de l'émulateur, vous pouvez connecter le kit SDK à l'instance de l'émulateur à la place.

Utilisez le Kit de développement logiciel (SDK) .NET De l’API Azure Cosmos DB pour NoSQL pour vous connecter à l’émulateur à partir d’une application .NET.

  1. Démarrez dans un dossier vide.

  2. Créez une application console .NET

    dotnet new console

  3. Ajoutez le package Microsoft.Azure.Cosmos à partir de NuGet.

    dotnet add package Microsoft.Azure.Cosmos

  4. Ouvrez le fichier Program.cs.

  5. Supprimez tout contenu existant dans le fichier.

  6. Ajouter un bloc d'utilisation pour l'espace de noms Microsoft.Azure.Cosmos.

    using Microsoft.Azure.Cosmos;

  7. Créez un instance d’utilisation des CosmosClient informations d’identification de l’émulateur.

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

  8. Créez une base de données et un conteneur à l’aide de CreateDatabaseIfNotExistsAsync et CreateContainerIfNotExistsAsync.

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

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

  9. Créez un élément dans le conteneur à l’aide de UpsertItemAsync.

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

await container.UpsertItemAsync(item);

  10. Exécutez l’application .NET.

    dotnet run

    Avertissement

    Si vous obtenez une erreur SSL, vous devrez peut-être désactiver TLS/SSL pour votre application. Cela se produit généralement si vous développez sur votre ordinateur local, que vous utilisez l’émulateur Azure Cosmos DB dans un conteneur et que vous n’avez pas importé le certificat SSL du conteneur. Pour résoudre ce problème, configurez les options du client pour désactiver la validation TLS/SSL avant de créer le client :

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

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

Conseil

Reportez-vous au guide du développeur .NET pour plus d’opérations que vous pouvez effectuer à l’aide du Kit de développement logiciel (SDK) .NET.

Utilisez le pilote .NET MongoDB pour vous connecter à l’émulateur à partir d’une application .NET.

  1. Démarrez dans un dossier vide.

  2. Créez une application console .NET

    dotnet new console

  3. Ajoutez le package MongoDB.Driver à partir de NuGet.

    dotnet add package MongoDB.Driver

  4. Ouvrez le fichier Program.cs.

  5. Supprimez tout contenu existant dans le fichier.

  6. Ajouter un bloc d'utilisation pour l'espace de noms MongoDB.Driver.

    using MongoDB.Driver;

  7. Créez un instance d’utilisation des MongoClient informations d’identification de l’émulateur.

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

  8. Obtenez la base de données et le conteneur à l’aide de GetDatabase et GetCollection<>.

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

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

  9. Créez un élément dans le XXX à l’aide de InsertOneAsync.

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

await collection.InsertOneAsync(item);

  10. Exécutez l’application .NET.

    dotnet run

Utilisez le pilote Apache Cassandra .NET pour vous connecter à l’émulateur à partir d’une application .NET.

  1. Démarrez dans un dossier vide.

  2. Créez une application console .NET

    dotnet new console

  3. Ajoutez le package CassandraCSharpDriver à partir de NuGet.

    dotnet add package CassandraCSharpDriver

  4. Ouvrez le fichier Program.cs.

  5. Supprimez tout contenu existant dans le fichier.

  6. Ajouter un bloc d'utilisation pour l'espace de noms Cassandra.

    using Cassandra;

  7. Créez un instance d’utilisation des Cluster informations d’identification de l’émulateur. Créez une nouvelle session en utilisant 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. Créez une base de données et un conteneur à l’aide de PrepareAsync et 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. Créez un élément dans la table à l’aide de ExecuteAsync. Utilisez Bind pour affecter des propriétés à l’élément.

    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. Exécutez l’application .NET.

    dotnet run

Important

Avant de commencer, l’API pour Apache Gremlin vous oblige à créer vos ressources dans l’émulateur. Créez une base de données nommée db1 et un conteneur nommé coll1. Les paramètres de débit ne sont pas pertinents pour ce guide et peuvent être définis aussi bas que vous le souhaitez.

Utilisez le pilote Apache Cassandra .NET pour vous connecter à l’émulateur à partir d’une application .NET.

  1. Démarrez dans un dossier vide.

  2. Créez une application console .NET

    dotnet new console

  3. Ajoutez le package Gremlin.Net à partir de NuGet.

    dotnet add package Gremlin.Net

  4. Ouvrez le fichier Program.cs.

  5. Supprimez tout contenu existant dans le fichier.

  6. Ajouter un bloc d'utilisation pour l'espace de noms Gremlin.Net.Driver.

    using Gremlin.Net.Driver;

  7. Créez une instance de GremlinServer et GremlinClient à l’aide des informations d’identification de l’émulateur.

    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. Nettoyez le graphique à l’aide de SubmitAsync.

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

  9. Utilisez SubmitAsync à nouveau pour ajouter un nouvel élément au graphique avec les paramètres spécifiés.

    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. Exécutez l’application .NET.

    dotnet run

Utilisez le Kit de développement logiciel (SDK) Azure Tables pour .NET pour vous connecter à l’émulateur à partir d’une application .NET.

  1. Démarrez dans un dossier vide.

  2. Créez une application console .NET

    dotnet new console

  3. Ajoutez le package Azure.Data.Tables à partir de NuGet.

    dotnet add package Azure.Data.Tables

  4. Ouvrez le fichier Program.cs.

  5. Supprimez tout contenu existant dans le fichier.

  6. Ajouter un bloc d'utilisation pour l'espace de noms Azure.Data.Tables.

    using Azure.Data.Tables;

  7. Créez un instance d’utilisation des TableServiceClient informations d’identification de l’émulateur.

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

  8. Utilisez GetTableClient pour créer un instance de TableClient avec le nom de la table. Vérifiez ensuite que la table existe à l’aide de CreateIfNotExistsAsync.

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

await client.CreateIfNotExistsAsync();

  9. Créez un record type pour les éléments.

    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. Créez un élément dans la table à l’aide du modeUpsertEntityAsync et 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. Exécutez l’application .NET.

    dotnet run

Utiliser l’émulateur dans un flux de travail CI GitHub Actions

Pour exécuter une charge de travail d’intégration continue qui valide automatiquement votre application, utilisez l’émulateur Azure Cosmos DB avec une suite de tests de l’infrastructure de votre choix. L’émulateur Azure Cosmos DB est préinstallé dans la windows-latest variante des exécuteurs hébergés de GitHub Action.

Exécutez une suite de tests à l’aide du pilote de test intégré pour .NET et d’une infrastructure de test telle que MSTest, NUnit ou XUnit.

  1. Vérifiez que la suite de tests unitaires pour votre application fonctionne comme prévu.

    dotnet test

  2. Créez un flux de travail dans votre référentiel GitHub dans un fichier nommé .github/workflows/ci.yml.

  3. Ajoutez un travail à votre workflow pour démarrer l’émulateur Azure Cosmos DB à l’aide de PowerShell et exécuter votre suite de tests unitaires.

    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

    Remarque

    Démarrez l’émulateur à partir de la ligne de commande à l’aide de différents arguments ou commandes PowerShell. Pour plus d’informations, consultez Arguments de ligne de commande de l’émulateur.

Étape suivante

Consultez les notes de version de l'émulateur