ローカルでの開発とテストのために Azure Cosmos DB Emulator をインストールして使用する

[アーティクル]
03/24/2023

適用対象: NoSQL MongoDB Cassandra Gremlin Table

Azure Cosmos DB Emulator では、Azure Cosmos DB サービスを開発目的でエミュレートするローカル環境を利用できます。 Azure Cosmos DB Emulator を使用すると、ローカルでのアプリケーションの開発とテストが、Azure サブスクリプションを作成したりコストをかけたりせずに実施できます。 Azure Cosmos DB Emulator でのアプリケーションの動作に満足できたら、クラウドでの Azure Cosmos DB アカウントの使用に切り替えることができます。この記事では、Windows、Linux、macOS、および Windows Docker 環境にエミュレーターをインストールして使用する方法について説明します。

エミュレーターをダウンロードする

まず、最新バージョンの Azure Cosmos DB Emulator をローカルコンピューターにダウンロードしてインストールします。エミュレーターリリースノートでは、利用可能なすべてのバージョンと各リリースで行われた機能更新プログラムの一覧を示します。

Azure Cosmos DB Emulator をダウンロードする

NoSQL、Apache Cassandra、MongoDB、Apache Gremlin、Table の API を使用して、アカウントで Azure Cosmos DB Emulator を使用してアプリケーションを開発できます。現在、エミュレーターのデータエクスプローラーで完全にサポートされているのは SQL データの表示のみです。現時点では、MongoDB、Gremlin/Graph、Cassandra の各クライアントアプリケーションを使用して作成されたデータを表示できません。詳細については、さまざまな API からエミュレーターエンドポイントに接続する方法に関するページを参照してください。

エミュレーターのしくみ

Azure Cosmos DB Emulator には、Azure Cosmos DB サービスの高忠実度エミュレーションが用意されています。 Azure Cosmos DB と同等の機能がサポートされています。たとえば、データの作成、データのクエリ、コンテナーのプロビジョニングとスケーリング、ストアドプロシージャとトリガーの実行などです。 Azure Cosmos DB Emulator を使用してアプリケーションを開発してテストし、Azure Cosmos DB 接続エンドポイントを更新することで、それらをグローバル規模で Azure にデプロイできます。

Azure Cosmos DB サービスのエミュレーションは忠実ですが、エミュレーターの実装はサービスとは異なります。たとえば、エミュレーターでは、永続化用のローカルファイルシステムや接続用の HTTPS プロトコルスタックなど、標準的な OS コンポーネントが使用されます。エミュレーターを使用する場合、グローバルレプリケーション、読み取りおよび書き取りの 10 ミリ秒を下回る待ち時間、調整可能な一貫性レベルなど、Azure インフラストラクチャに依存する機能は適用されません。

エミュレーターとクラウドサービスの違い

Azure Cosmos DB Emulator は、ローカルの開発者ワークステーションに環境をエミュレートして提供するものであるため、このエミュレーターとクラウドにある Azure Cosmos DB アカウントとの間には機能にいくつかの違いがあります:

現在、エミュレーターの [データエクスプローラー] ペインで完全にサポートされているのは、API for NoSQL クライアントのみです。 MongoDB、Table、Graph、Cassandra などの API のような、Azure Cosmos DB 用の API については、データエクスプローラーのビューと操作が完全にはサポートされていません。
エミュレーターでサポートされるのは、1 つの固定アカウントと既知の主キーのみです。 Azure Cosmos DB Emulator を使用している場合、キーを再生成することはできませんが、コマンドラインオプションを使用して既定のキーを変更できます。
エミュレーターを使用すると、プロビジョニングされたスループットモードでのみ Azure Cosmos DB アカウントを作成できます。現在、サーバーレスモードはサポートされていません。
エミュレーターはスケーラブルなサービスではなく、多数のコンテナーはサポートされていません。 Azure Cosmos DB Emulator を使用する場合、既定では、固定サイズのコンテナー (Azure Cosmos DB SDK を使用する場合にのみサポートされます) を 400 RU/秒で 25 個まで、容量無制限のコンテナーを 5 個まで作成できます。この値を変更する方法の詳細については、PartitionCount 値の設定に関する記事をご覧ください。
エミュレーターには、クラウドサービスのように複数の Azure Cosmos DB 整合性レベルが用意されていません。
エミュレーターでは、マルチリージョンレプリケーションが提供されていません。
Azure Cosmos DB Emulator には Azure Cosmos DB サービスの最近の変更が反映されていないことがあるため、常に Azure Cosmos DB Capacity Planner を参照し、アプリケーションのスループット (RU) のニーズを正確に見積もる必要があります。
エミュレーターは、254 文字の最大 ID プロパティサイズをサポートしています。

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

エミュレーターをインストールする前に、次のハードウェアおよびソフトウェア要件を満たしていることを確認します。

ソフトウェア要件:
- 現在、Windows Server 2016、2019、または Windows 10 ホスト OS がサポートされています。 Active Directory が有効なホスト OS は、現在サポートされていません。
- 64 ビットオペレーティングシステム
最小ハードウェア要件:
- 2 GB の RAM
- 10 GB のハードディスク空き容量
Azure Cosmos DB Emulator をインストール、構成、実行するには、コンピューターの管理特権が必要です。エミュレーターによって、サービスを実行するために証明書が追加され、ファイアウォールルールも設定されます。そのため、エミュレーターでそのような操作を実行できるようには、管理者権限が必要です。

まず、最新バージョンの Azure Cosmos DB Emulator をローカルコンピューターにダウンロードしてインストールします。エミュレーターのインストール時に問題が発生した場合は、エミュレーターのトラブルシューティングの記事を参照してデバッグしてください。

この記事の次のセクションで説明するように、システム要件に応じて、Windows、Docker for Windows、Linux、または macOS 上でエミュレーターを実行できます。

エミュレーターの更新プログラムを確認する

エミュレーターの各バージョンには、一連の機能更新プログラムまたはバグ修正が含まれています。使用できるバージョンを確認するには、エミュレーターのリリースノートの記事を参照してください。

インストール後、既定の設定を使用した場合、エミュレーターに対応するデータは %LOCALAPPDATA%\CosmosDBEmulator の場所に保存されます。オプションのデータパス設定を使用して、別の場所を構成することができます。これは、コマンドラインパラメーターとしての /DataPath=PREFERRED_LOCATION です。 Azure Cosmos DB Emulator のあるバージョンで作成したデータは、他のバージョンを使用してアクセスできない可能性があります。データを永続化して長期にわたって保持する必要がある場合、そのデータは Azure Cosmos DB Emulator ではなく Azure Cosmos DB アカウントに格納することをお勧めします。

Windows 上でエミュレーターを使用する

Azure Cosmos DB Emulator は、既定で C:\Program Files\Azure Cosmos DB Emulator の場所にインストールされます。 Windows 上で Azure Cosmos DB Emulator を起動するには、 [スタート] ボタンを選択するか、Windows キーを押します。「Azure Cosmos DB Emulator」と入力して、アプリケーションの一覧からエミュレーターを選択します。

[スタート] ボタンを選択するか Windows キーを押して「Azure Cosmos DB Emulator」と入力し、アプリケーションの一覧からエミュレーターを選択する

エミュレーターが起動すると、Windows タスクバーの通知領域にアイコンが表示されます。この URL https://localhost:8081/_explorer/index.htmlの URL の Azure Cosmos DB データエクスプローラーがブラウザーで自動的に開きます。

Azure Cosmos DB ローカルエミュレーターのタスクバーの通知

コマンドラインまたは PowerShell コマンドからエミュレーターを起動および停止することもできます。詳細については、コマンドラインツールのリファレンスの記事を参照してください。

Azure Cosmos DB Emulator は既定では、ポート 8081 でリッスンしているローカルコンピューター ("localhost") で実行されます。アドレスは https://localhost:8081/_explorer/index.html として表示されます。エクスプローラーを閉じた後にもう一度開く場合は、ブラウザーで URL を開くか、次に示すように Windows トレイアイコンの Azure Cosmos DB Emulator から起動できます。

Azure Cosmos DB ローカルエミュレーターのデータエクスプローラー起動ツール

Linux または macOS 上でエミュレーターを使用する

現在、Azure Cosmos DB Emulator は Windows でのみ実行できます。 Linux または macOS を使用している場合は、Linux Emulator (プレビュー) を使用するか、ハイパーバイザー (Parallels や VirtualBox など) でホストされる Windows 仮想マシン内でエミュレーターを実行することをお勧めします。

Note

ハイパーバイザーでホストされている Windows 仮想マシンを再起動するたびに、仮想マシンの IP アドレスは変わるため、証明書を再インポートする必要があります。 IP アドレスを保持するように仮想マシンを構成している場合、証明書をインポートする必要はありません。

Linux または macOS 環境上でエミュレーターを使用するには、次の手順を実行します。

Windows 仮想マシンから次のコマンドを実行し、IPv4 アドレスをメモします。
```
ipconfig.exe
```
アプリケーション内で、localhost ではなく ipconfig.exe から返される IPv4 アドレスを使用するようにエンドポイント URL を変更します。
Windows 仮想マシンから、次のオプションを使用してコマンドラインから Azure Cosmos DB Emulator を起動します。コマンドラインでサポートされているパラメーターの詳細については、エミュレーターのコマンドラインツールリファレンスに関するページを参照してください。
```
Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
```
最後に、Linux または Mac 環境で実行されているアプリケーションとエミュレーターの間の証明書の信頼プロセスを解決する必要があります。次の 2 つのオプションのいずれかを使用して、証明書を解決できます。
1. エミュレーターの TLS/SSL 証明書を Linux または Mac 環境にインポートする、または
2. アプリケーションで TLS/SSL 検証を無効にする

オプション 1: エミュレーターの TLS/SSL 証明書をインポートする

以下のセクションでは、エミュレーターの TLS/SSL 証明書を Linux および macOS 環境にインポートする方法について説明します。

Linux 環境

Linux 環境では、.NET が OpenSSL に依存して検証を行います。

証明書を PFX 形式でエクスポートします。 PFX オプションは、秘密キーのエクスポートを選択するときに使用できます。
PFX ファイルを Linux 環境にコピーします。

PFX ファイルを CRT ファイルに変換します。

openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt

ご利用の Linux ディストリビューションの、カスタム証明書が格納されているフォルダーに CRT ファイルをコピーします。一般に、Debian ディストリビューションでは /usr/local/share/ca-certificates/ に格納されます。
```
cp YourCTR.crt /usr/local/share/ca-certificates/
```
TLS/SSL 証明書を更新します。これによって /etc/ssl/certs/ フォルダーが更新されます。
```
update-ca-certificates
```

macOS 環境

Mac 環境では、次の手順に従います。

証明書を PFX 形式でエクスポートします。 PFX オプションは、秘密キーのエクスポートを選択するときに使用できます。
PFX ファイルを Mac 環境にコピーします。
Keychain Access アプリケーションを開いて PFX ファイルをインポートします。
証明書の一覧を開き、localhost という名前の証明書を特定します。
その特定の項目のコンテキストメニューを開いて [項目の取得] を選択し、 [信頼]>[この証明書を使用するとき] オプションの [常に信頼] を選択します。

オプション 2: アプリケーションで SSL 検証を無効にする

SSL 検証の無効化は、開発目的の場合にのみお勧めします。運用環境で実行するときは無効にしないでください。次の例は、.NET および Node.js アプリケーションの SSL 検証を無効にする方法を示しています。

.NET Standard 2.1 以降と互換性のあるフレームワークで実行されているアプリケーションの場合は、CosmosClientOptions.HttpClientFactory を活用できます。

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    HttpClientFactory = () =>
    {
        HttpMessageHandler httpMessageHandler = new HttpClientHandler()
        {
            ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
        };

        return new HttpClient(httpMessageHandler);
    },
    ConnectionMode = ConnectionMode.Gateway
};


CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);

.NET Standard 2.0 と互換性のあるフレームワークで実行されているアプリケーションの場合は、CosmosClientOptions.HttpClientFactory を活用できます。

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    HttpClientFactory = () =>
    {
        HttpMessageHandler httpMessageHandler = new HttpClientHandler()
        {
            ServerCertificateCustomValidationCallback = (req, cert, chain, errors) => true
        };

        return new HttpClient(httpMessageHandler);
    },
    ConnectionMode = ConnectionMode.Gateway
};


CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);

Node.js アプリケーションの場合は、アプリケーションの起動中に NODE_TLS_REJECT_UNAUTHORIZED を設定するように package.json ファイルを変更できます。

"start": NODE_TLS_REJECT_UNAUTHORIZED=0 node app.js

ローカルネットワーク上でエミュレーターへのアクセスを有効にする

1 つのネットワークを使用する複数のマシンがあり、1 つのマシンにエミュレーターを設定していて、他のマシンからエミュレーターにアクセスする場合があります。このような場合、ローカルネットワーク上でエミュレーターへのアクセスを有効にする必要があります。

ローカルネットワークでのエミュレーターを実行できます。ネットワークアクセスを有効にするには、コマンドラインで /AllowNetworkAccess オプションを指定します。また、/Key=key_string または /KeyFile=file_name を指定する必要もあります。 /GenKeyFile=file_name を使用すると、ランダムなキーを備えたファイルを事前に生成できます。その後、それを /KeyFile=file_name または /Key=contents_of_file に渡すことができます。

ネットワークアクセスを初めて有効にする場合は、エミュレーターをシャットダウンし、エミュレーターのデータディレクトリ ( %LOCALAPPDATA%\CosmosDBEmulator) を削除する必要があります。

エミュレーターの使用時に接続を認証する

クラウドの Azure Cosmos DB と同様に、Azure Cosmos DB Emulator に対する各要求は認証される必要があります。 Azure Cosmos DB Emulator では、TLS 経由のセキュリティで保護された通信のみがサポートされます。 Azure Cosmos DB Emulator では、主キー認証について、単一の固定アカウントと既知の認証キーがサポートされています。 Azure Cosmos DB Emulator ではこのアカウントとキーのみが資格情報として使用できます。これらは次のとおりです。

Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Note

Azure Cosmos DB Emulator でサポートされている主キーは、エミュレーターで使用することのみを想定したものです。 Azure Cosmos DB Emulator で運用環境の Azure Cosmos DB アカウントとキーを使用することはできません。

Note

/Key オプションを使用してエミュレーターを開始した場合は、既定のキーである C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== の代わりに生成されたキーを使用します。 /Key オプションの詳細については、コマンドラインツールのリファレンスを参照してください。

エミュレーターを使用してさまざまな API に接続する

NoSQL 用 API

デスクトップで Azure Cosmos DB Emulator を実行している間、サポートされている Azure Cosmos DB SDK または Azure Cosmos DB REST API を使用してエミュレーターを操作できます。 Azure Cosmos DB Emulator には、NoSQL または Mongo DB 用 API のコンテナーを作成できる組み込みのデータエクスプローラーも含まれています。データエクスプローラーを使用すると、コードを書くことなく項目を表示および編集できます。

// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
   "https://localhost:8081", 
    "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");

MongoDB 用 API

デスクトップ上で Azure Cosmos DB Emulator が実行中になったら、Azure Cosmos DB の MongoDB 用 API を使用してエミュレーターを操作できます。コマンドプロンプトから管理者としてエミュレーターを起動します。その際、一緒に "/EnableMongoDbEndpoint" を指定します。その後、次の接続文字列を使用して MongoDB 用API アカウントに接続します：

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

Table 用 API

デスクトップ上で Azure Cosmos DB Emulator が実行中になったら、Azure Cosmos DB Table SDK用API を使用してエミュレーターを操作できます。コマンドプロンプトから管理者としてエミュレーターを起動します。その際、一緒に "/EnableTableEndpoint" を指定します。続いて、次のコードを実行して Table 用API アカウントに接続します：

using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Table;
using CloudTable = Microsoft.WindowsAzure.Storage.Table.CloudTable;
using CloudTableClient = Microsoft.WindowsAzure.Storage.Table.CloudTableClient;

string connectionString = "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;";

CloudStorageAccount account = CloudStorageAccount.Parse(connectionString);
CloudTableClient tableClient = account.CreateCloudTableClient();
CloudTable table = tableClient.GetTableReference("testtable");
table.CreateIfNotExists();
table.Execute(TableOperation.Insert(new DynamicTableEntity("partitionKey", "rowKey")));

Cassandra 用 API

管理者のコマンドプロンプトからエミュレーターを起動します。その際、一緒に "/EnableCassandraEndpoint" を指定します。代わりに、環境変数 AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true を設定することもできます。

Python 2.7 をインストールします
Cassandra CLI/CQLSH をインストールします

通常のコマンドプロンプトウィンドウで次のコマンドを実行します。

set Path=c:\Python27;%Path%
cd /d C:\sdk\apache-cassandra-3.11.3\bin
set SSL_VERSION=TLSv1_2
set SSL_VALIDATE=false
cqlsh localhost 10350 -u localhost -p C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== --ssl

CQLSH シェルで次のコマンドを実行し、Cassandra エンドポイントに接続します。

CREATE KEYSPACE MyKeySpace WITH replication = {'class':'MyClass', 'replication_factor': 1};
DESCRIBE keyspaces;
USE mykeyspace;
CREATE table table1(my_id int PRIMARY KEY, my_name text, my_desc text);
INSERT into table1 (my_id, my_name, my_desc) values( 1, 'name1', 'description 1');
SELECT * from table1;
EXIT

Gremlin 用 API

管理者のコマンドプロンプトからエミュレーターを起動します。その際、一緒に "/EnableGremlinEndpoint" を指定します。代わりに、環境変数 AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true を設定することもできます

apache-tinkerpop-gremlin-console-3.6.0 をインストールします。
エミュレーターのデータエクスプローラーから、データベース "db1" とコレクション "coll1" を作成します。パーティションキーには "/name" を選択します

通常のコマンドプロンプトウィンドウで次のコマンドを実行します。

cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.6.0-bin\apache-tinkerpop-gremlin-console-3.6.0

copy /y conf\remote.yaml conf\remote-localcompute.yaml
notepad.exe conf\remote-localcompute.yaml
  hosts: [localhost]
  port: 8901
  username: /dbs/db1/colls/coll1
  password: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
  connectionPool: {
  enableSsl: false}
  serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0,
  config: { serializeResultToString: true  }}

bin\gremlin.bat

Gremlin シェルで次のコマンドを実行し、Gremlin エンドポイントに接続します。

:remote connect tinkerpop.server conf/remote-localcompute.yaml
:remote console
:> g.V()
:> g.addV('person1').property(id, '1').property('name', 'somename1')
:> g.addV('person2').property(id, '2').property('name', 'somename2')
:> g.V()

ローカルエミュレーターのアンインストール

次の手順に従ってエミュレーターをアンインストールします。

システムトレイの Azure Cosmos DB Emulator のアイコンを右クリックし、 [終了] を選択して、開いているローカルエミュレーターのインスタンスをすべて終了します。すべてのインスタンスが終了するまでしばらく時間がかかる場合があります。
Windows 検索ボックスに「アプリと機能」と入力し、アプリと機能 (システム設定) の検索結果を選択します。
アプリの一覧で、Azure Cosmos DB エミュレーター までスクロールして選択し、 [アンインストール] を選択し、確認して再度、 [アンインストール] をクリックします。

次のステップ

この記事では、無料のローカル開発のためにローカルエミュレーターを使用する方法について学習しました。次の記事に進むことができます。

ローカルでの開発とテストのために Azure Cosmos DB Emulator をインストールして使用する

エミュレーターをダウンロードする

エミュレーターのしくみ

エミュレーターとクラウドサービスの違い

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

エミュレーターの更新プログラムを確認する

Windows 上でエミュレーターを使用する

Linux または macOS 上でエミュレーターを使用する

オプション 1: エミュレーターの TLS/SSL 証明書をインポートする

Linux 環境

macOS 環境

オプション 2: アプリケーションで SSL 検証を無効にする

ローカルネットワーク上でエミュレーターへのアクセスを有効にする

エミュレーターの使用時に接続を認証する

エミュレーターを使用してさまざまな API に接続する

NoSQL 用 API

MongoDB 用 API

Table 用 API

Cassandra 用 API

Gremlin 用 API

ローカルエミュレーターのアンインストール

次のステップ

その他のリソース

その他のリソース

ローカルでの開発とテストのために Azure Cosmos DB Emulator をインストールして使用する

エミュレーターをダウンロードする

エミュレーターのしくみ

エミュレーターとクラウド サービスの違い

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

エミュレーターの更新プログラムを確認する

Windows 上でエミュレーターを使用する

Linux または macOS 上でエミュレーターを使用する

オプション 1: エミュレーターの TLS/SSL 証明書をインポートする

Linux 環境

macOS 環境

オプション 2: アプリケーションで SSL 検証を無効にする

ローカル ネットワーク上でエミュレーターへのアクセスを有効にする

エミュレーターの使用時に接続を認証する

エミュレーターを使用してさまざまな API に接続する

NoSQL 用 API

MongoDB 用 API

Table 用 API

Cassandra 用 API

Gremlin 用 API

ローカル エミュレーターのアンインストール

次のステップ

その他のリソース

その他のリソース

エミュレーターとクラウドサービスの違い

ローカルネットワーク上でエミュレーターへのアクセスを有効にする

ローカルエミュレーターのアンインストール