Azure Cosmos DB エミュレーターを使用したローカルでの開発

  • [アーティクル]

エミュレーターの一般的なユース ケースは、アプリケーションの作成中に開発データベースとして使用することです。 開発にエミュレーターを使用すると、サービス コストを発生させることなく、Azure Cosmos DB などのデータベースのデータの作成やモデル化の特徴を学習するのに役立ちます。 さらに、エミュレーターをオートメーション ワークフローの一部として使用すると、確実に同じ統合テスト スイートを実行できます。 開発用コンピューター (ローカル) と継続的インテグレーション ジョブ (リモート) の両方で同じテストを実行できます。

前提条件

  • .NET 6 以降、Node.js LTS、または Python 3.7 以降
    • 必要なすべての実行可能ファイルが PATH にあることを確認します。
  • Windows エミュレーター
    • 64 ビット Windows Server 2016、2019、Windows 10、または Windows 11。
    • 最小ハードウェア要件:
      • 2 GB の RAM
      • 10 GB のハードディスク空き容量
  • Docker エミュレーター

エミュレーターをインストールする

エミュレーターには複数のバリエーションがあり、バリエーションごとにスムーズなインストール プロセスがあります。

まず、Microsoft Container Registry (MCR) から Linux 用のコンテナー イメージを取得します。

  1. コンテナー レジストリからローカル Docker ホストに mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux コンテナー イメージをプルします。

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

  2. エミュレーター イメージがローカル Docker ホストにプルされたことを確認します。

    docker images

まず、Microsoft Container Registry (MCR) から Linux 用のコンテナー イメージを取得します。

  1. コンテナー レジストリからローカル Docker ホストに、mongodb タグを使用して mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux コンテナー イメージをプルします。

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

  2. エミュレーター イメージがローカル Docker ホストにプルされたことを確認します。

    docker images

エミュレーターの Docker コンテナーのバリエーション (Linux または Windows) では、Apache Cassandra 用 API、Apache Gremlin 用 API、または Table 用 API はサポートされていません。

エミュレーターを起動する

ダウンロードしたら、指定した API を有効にしてエミュレーターを起動します。

エミュレーターの Docker コンテナーのバリエーションでは、Apache Cassandra 用 API はサポートされていません。

エミュレーターの Docker コンテナーのバリエーションでは、Apache Gremlin 用 API はサポートされていません。

エミュレーターの Docker コンテナーのバリエーションでは、Table 用 API はサポートされていません。

  1. コンテナー イメージと次の構成を使用して、新しいコンテナーを実行します。

    説明
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(省略可) "使用するパーティションの数を指定します。"
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(省略可) "エミュレーターの実行間のデータ永続化を有効にします。"
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(省略可) "エミュレーターの既定の IP アドレスをオーバーライドします。" 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. https://localhost:8081/_explorer/index.html に移動して、データ エクスプローラーにアクセスします。

  1. コンテナー イメージと次の構成を使用して、新しいコンテナーを実行します。

    説明
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT 使用する MongoDB エンドポイントのバージョンを指定します。 サポートされるエンドポイントは、3.2、3.6、または 4.0 です。
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(省略可) "使用するパーティションの数を指定します。"
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(省略可) "エミュレーターの実行間のデータ永続化を有効にします。"
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(省略可) "エミュレーターの既定の IP アドレスをオーバーライドします。" 
    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. https://localhost:8081/_explorer/index.html に移動して、データ エクスプローラーにアクセスします。

エミュレーターの TLS/SSL 証明書をインポートする

クライアントで TLS/SSL を無効にせず、任意の開発者 SDK でエミュレーターを使用するようにエミュレーターの TLS/SSL 証明書をインポートします。

エミュレーターの Docker コンテナーのバリエーション (Linux または Windows) では、Apache Cassandra 用 API、Apache Gremlin 用 API、または Table 用 API はサポートされていません。

エミュレーターの証明書は、実行中のコンテナーの _explorer/emulator.pem パスで使用できます。 curl を使用して、実行中のコンテナーからローカル コンピューターに証明書をダウンロードします。

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

エミュレーターの証明書は、実行中のコンテナーの _explorer/emulator.pem パスで使用できます。

  1. curl を使用して、実行中のコンテナーからローカル コンピューターに証明書をダウンロードします。

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

    Note

    これらの値を以前に変更した場合は、ホスト (または IP アドレス) とポート番号の変更が必要な場合があります。

  2. オペレーティング システムで通常使用されるプロセスに従って証明書をインストールします。 たとえば、Linux では、証明書を /usr/local/share/ca-certificates/ パスにコピーします。

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

  3. お使いの Linux ディストリビューションに適したコマンドを使用して、CA 証明書を更新し、証明書バンドルを再生成します。

    Debian ベースのシステム (Ubuntu など) の場合は、以下を使用します。

    sudo update-ca-certificates

    Red Hat ベースのシステム (CentOS、Fedora など) の場合は、以下を使用します。

    sudo update-ca-trust

    詳細な手順については、お使いの Linux ディストリビューションに固有のドキュメントを参照してください。

SDK からエミュレーターに接続する

各 SDK には、SDK を Azure Cosmos DB アカウントに接続するために通常使用されるクライアント クラスが含まれています。 エミュレーターの資格情報を使用して、SDK をエミュレーター インスタンスに接続できます。

Azure Cosmos DB API for NoSQL .NET SDK を使用して、.NET アプリケーションからエミュレーターに接続します。

  1. 空のフォルダーから開始します。

  2. 新しい .NET コンソール アプリケーションを作成します。

    dotnet new console

  3. NuGet から Microsoft.Azure.Cosmos パッケージを追加します。

    dotnet add package Microsoft.Azure.Cosmos

  4. Program.cs ファイルを開きます。

  5. ファイル内に既存のコンテンツがあれば削除します。

  6. Microsoft.Azure.Cosmos 名前空間の using ブロックを追加します。

    using Microsoft.Azure.Cosmos;

  7. エミュレーターの資格情報を使用して、CosmosClient の新しいインスタンスを作成します。

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

  8. CreateDatabaseIfNotExistsAsync および CreateContainerIfNotExistsAsync を使用して、新しいデータベースとコンテナーを作成します。

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

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

  9. UpsertItemAsync を使用して、コンテナーに新しい項目を作成します。

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

await container.UpsertItemAsync(item);

  10. .NET アプリケーションを実行します。

    dotnet run

    警告

    SSL エラーが発生すると、場合によってはアプリケーションの TLS/SSL を無効にする必要があります。 通常これが発生するのは、コンテナー内の Azure Cosmos DB エミュレーターを使用してローカル コンピューターで開発しているときに、コンテナーの SSL 証明書をインポートしていない場合です。 これを解決するには、クライアントを作成する前に、TLS/SSL 検証を無効にするようにクライアントのオプションを構成します。

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

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

ヒント

.NET SDK を使用して実行できるその他の操作については、.NET 開発者ガイドを参照してください。

MongoDB .NET ドライバーを使用して、.NET アプリケーションからエミュレーターに接続します。

  1. 空のフォルダーから開始します。

  2. 新しい .NET コンソール アプリケーションを作成します。

    dotnet new console

  3. NuGet から MongoDB.Driver パッケージを追加します。

    dotnet add package MongoDB.Driver

  4. Program.cs ファイルを開きます。

  5. ファイル内に既存のコンテンツがあれば削除します。

  6. MongoDB.Driver 名前空間の using ブロックを追加します。

    using MongoDB.Driver;

  7. エミュレーターの資格情報を使用して、MongoClient の新しいインスタンスを作成します。

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

  8. GetDatabase および GetCollection<> を使用して、データベースとコンテナーを取得します。

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

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

  9. InsertOneAsync を使用して XXX に新しい項目を 作成します。

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

await collection.InsertOneAsync(item);

  10. .NET アプリケーションを実行します。

    dotnet run

Apache Cassandra .NET ドライバーを使用して、.NET アプリケーションからエミュレーターに接続します。

  1. 空のフォルダーから開始します。

  2. 新しい .NET コンソール アプリケーションを作成します。

    dotnet new console

  3. NuGet から CassandraCSharpDriver パッケージを追加します。

    dotnet add package CassandraCSharpDriver

  4. Program.cs ファイルを開きます。

  5. ファイル内に既存のコンテンツがあれば削除します。

  6. Cassandra 名前空間の using ブロックを追加します。

    using Cassandra;

  7. エミュレーターの資格情報を使用して、Cluster の新しいインスタンスを作成します。 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. PrepareAsync および 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. ExecuteAsync を使用して、テーブルに新しい項目を作成します。 Bindを使用して、項目にプロパティを割り当てます。

    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. .NET アプリケーションを実行します。

    dotnet run

重要

Apache Gremlin 用 API の場合、開始する前に、エミュレーターにリソースを作成する必要があります。 db1 という名前のデータベースと coll1 という名前のコンテナーを作成します。 スループットの設定は、このガイドには関係ありません。必要に応じて低く設定できます。

Apache Gremlin .NET ドライバーを使用して、.NET アプリケーションからエミュレーターに接続します。

  1. 空のフォルダーから開始します。

  2. 新しい .NET コンソール アプリケーションを作成します。

    dotnet new console

  3. NuGet から Gremlin.Net パッケージを追加します。

    dotnet add package Gremlin.Net

  4. Program.cs ファイルを開きます。

  5. ファイル内に既存のコンテンツがあれば削除します。

  6. Gremlin.Net.Driver 名前空間の using ブロックを追加します。

    using Gremlin.Net.Driver;

  7. エミュレーターの資格情報を使用して、GremlinServer と GremlinClient の新しいインスタンスを作成します。

    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. SubmitAsync を使用してグラフをクリーンアップします。

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

  9. もう一度 SubmitAsync を使用し、指定したパラメーターを使用してグラフに新しい項目を追加します。

    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. .NET アプリケーションを実行します。

    dotnet run

Azure Tables SDK for .NET を使用して、.NET アプリケーションからエミュレーターに接続します。

  1. 空のフォルダーから開始します。

  2. 新しい .NET コンソール アプリケーションを作成します。

    dotnet new console

  3. NuGet から Azure.Data.Tables パッケージを追加します。

    dotnet add package Azure.Data.Tables

  4. Program.cs ファイルを開きます。

  5. ファイル内に既存のコンテンツがあれば削除します。

  6. Azure.Data.Tables 名前空間の using ブロックを追加します。

    using Azure.Data.Tables;

  7. エミュレーターの資格情報を使用して、TableServiceClient の新しいインスタンスを作成します。

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

  8. GetTableClient を使用して、TableClient の新しいインスタンスをテーブルの名前で作成します。 次に、CreateIfNotExistsAsync を使用してテーブルが存在することを確認します。

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

await client.CreateIfNotExistsAsync();

  9. 項目の新しい record 型を作成します。

    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. UpsertEntityAsync と 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. .NET アプリケーションを実行します。

    dotnet run

GitHub Actions CI ワークフローでエミュレーターを使用する

選択したフレームワークのテスト スイートと共に Azure Cosmos DB エミュレーターを使用して、アプリケーションを自動的に検証する継続的インテグレーション ワークロードを実行します。 Azure Cosmos DB エミュレーターは、windows-latest 用の GitHub Action ホストテッド ランナーにプレインストールされています。

.NET 用の組み込みテスト ドライバーと、MSTest、NUnit、 XUnit などのテスト フレームワークを使用して、テスト スイートを実行します。

  1. アプリケーションの単体テスト スイートが予期したとおりに動作することを検証します。

    dotnet test

  2. .github/workflows/ci.yml という名前のファイル内に GitHub リポジトリの新しいワークフローを作成します。

  3. PowerShell を使用して Azure Cosmos DB エミュレーターを起動し、単体テスト スイートを実行するジョブをワークフローに追加します。

    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

    Note

    さまざまな引数または PowerShell コマンドを使用して、コマンドラインからエミュレーターを起動します。 詳細については、「エミュレーターのコマンドライン引数」を参照してください。

次のステップ

エミュレーターのリリース ノートを確認する