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

適用対象: 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 をダウンロードする

NoSQLApache CassandraMongoDBApache GremlinTable の 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 をローカル コンピューターにダウンロードしてインストールします。 エミュレーターのインストール時に問題が発生した場合は、エミュレーターのトラブルシューティングの記事を参照してデバッグしてください。

この記事の次のセクションで説明するように、システム要件に応じて、WindowsDocker for WindowsLinux、または 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 環境上でエミュレーターを使用するには、次の手順を実行します。

  1. Windows 仮想マシンから次のコマンドを実行し、IPv4 アドレスをメモします。

    ipconfig.exe
    
  2. アプリケーション内で、localhost ではなく ipconfig.exe から返される IPv4 アドレスを使用するようにエンドポイント URL を変更します。

  3. Windows 仮想マシンから、次のオプションを使用してコマンド ラインから Azure Cosmos DB Emulator を起動します。 コマンド ラインでサポートされているパラメーターの詳細については、エミュレーターのコマンドライン ツール リファレンスに関するページを参照してください。

    Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    
  4. 最後に、Linux または Mac 環境で実行されているアプリケーションとエミュレーターの間の証明書の信頼プロセスを解決する必要があります。 次の 2 つのオプションのいずれかを使用して、証明書を解決できます。

    1. エミュレーターの TLS/SSL 証明書を Linux または Mac 環境にインポートする、または
    2. アプリケーションで TLS/SSL 検証を無効にする

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

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

Linux 環境

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

  1. 証明書を PFX 形式でエクスポートします。 PFX オプションは、秘密キーのエクスポートを選択するときに使用できます。

  2. PFX ファイルを Linux 環境にコピーします。

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

    openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
    
  4. ご利用の Linux ディストリビューションの、カスタム証明書が格納されているフォルダーに CRT ファイルをコピーします。 一般に、Debian ディストリビューションでは /usr/local/share/ca-certificates/ に格納されます。

    cp YourCTR.crt /usr/local/share/ca-certificates/
    
  5. TLS/SSL 証明書を更新します。これによって /etc/ssl/certs/ フォルダーが更新されます。

    update-ca-certificates
    

macOS 環境

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

  1. 証明書を PFX 形式でエクスポートします。 PFX オプションは、秘密キーのエクスポートを選択するときに使用できます。

  2. PFX ファイルを Mac 環境にコピーします。

  3. Keychain Access アプリケーションを開いて PFX ファイルをインポートします。

  4. 証明書の一覧を開き、localhost という名前の証明書を特定します。

  5. その特定の項目のコンテキスト メニューを開いて [項目の取得] を選択し、 [信頼]>[この証明書を使用するとき] オプションの [常に信頼] を選択します。

    その特定の項目のコンテキスト メニューを開いて [項目の取得] を選択し、[信頼] の [この証明書を使用するとき] オプションで [常に信頼] を選択する

オプション 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);

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

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 を設定することもできます。

  1. Python 2.7 をインストールします

  2. Cassandra CLI/CQLSH をインストールします

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

    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
    
  4. 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 を設定することもできます

  1. apache-tinkerpop-gremlin-console-3.6.0 をインストールします

  2. エミュレーターのデータ エクスプローラーから、データベース "db1" とコレクション "coll1" を作成します。パーティション キーには "/name" を選択します

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

    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
    
  4. 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()
    

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

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

  1. システム トレイの Azure Cosmos DB Emulator のアイコンを右クリックし、 [終了] を選択して、開いているローカル エミュレーターのインスタンスをすべて終了します。 すべてのインスタンスが終了するまでしばらく時間がかかる場合があります。

  2. Windows 検索ボックスに「アプリと機能」と入力し、アプリと機能 (システム設定) の検索結果を選択します。

  3. アプリの一覧で、Azure Cosmos DB エミュレーター までスクロールして選択し、 [アンインストール] を選択し、確認して再度、 [アンインストール] をクリックします。

次のステップ

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