ローカルでの開発とテストに Azure Cosmos Emulator を使用するUse the Azure Cosmos Emulator for local development and testing

Azure Cosmos Emulator は、開発目的で Azure Cosmos DB サービスをエミュレートするローカル環境を提供するものです。The Azure Cosmos Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Azure Cosmos Emulator を使用すると、ローカルでのアプリケーションの開発とテストを、Azure サブスクリプションを作成したりコストをかけたりせずに実施できます。Using the Azure Cosmos Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. Azure Cosmos Emulator でのアプリケーションの動作に満足できたら、クラウドでの Azure Cosmos アカウントの使用に切り替えることができます。When you're satisfied with how your application is working in the Azure Cosmos Emulator, you can switch to using an Azure Cosmos account in the cloud.

Azure Cosmos Emulator を使った開発には、SQLCassandraMongoDBGremlinTable の API アカウントを利用できます。You can develop using Azure Cosmos Emulator with SQL, Cassandra, MongoDB, Gremlin, and Table API accounts. ただし、現時点でエミュレーター内のデータ エクスプローラー ビューで完全にサポートされるのは、SQL API のクライアントのみです。However at this time the Data Explorer view in the emulator fully supports clients for SQL API only.

エミュレーターの機能How the emulator works

Azure Cosmos Emulator には、Azure Cosmos DB サービスの高忠実度エミュレーションが用意されています。The Azure Cosmos Emulator provides a high-fidelity emulation of the Azure Cosmos DB service. データの作成とクエリ、コンテナーのプロビジョニングとスケーリング、ストアド プロシージャとトリガーの実行のサポートなど、Azure Cosmos DB と同じ機能がサポートされています。It supports identical functionality as Azure Cosmos DB, including support for creating and querying data, provisioning and scaling containers, and executing stored procedures and triggers. Azure Cosmos Emulator を使用してアプリケーションの開発とテストを行い、Azure Cosmos DB 用の接続エンドポイントの構成を 1 つ変更するだけで、世界規模で Azure にデプロイすることができます。You can develop and test applications using the Azure Cosmos Emulator, and deploy them to Azure at global scale by just making a single configuration change to the connection endpoint for Azure Cosmos DB.

Azure Cosmos DB サービスのエミュレーションは忠実ですが、エミュレーターの実装はサービスとは異なります。While emulation of the Azure Cosmos DB service is faithful, the emulator's implementation is different than the service. たとえば、エミュレーターでは、永続化用のローカル ファイル システムや接続用の HTTPS プロトコル スタックなど、標準的な OS コンポーネントが使用されます。For example, the emulator uses standard OS components such as the local file system for persistence, and the HTTPS protocol stack for connectivity. グローバル レプリケーション、読み取り/書き取りの 10 ミリ秒を下回る待ち時間、調整可能な一貫性レベルなど、Azure インフラストラクチャに依存する機能は適用されません。Functionality that relies on Azure infrastructure like global replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not applicable.

Azure Cosmos DB Data Migration Tool を使用すると、Azure Cosmos Emulator と Azure Cosmos DB サービスの間でデータを移行できます。You can migrate data between the Azure Cosmos Emulator and the Azure Cosmos DB service by using the Azure Cosmos DB Data Migration Tool.

Azure Cosmos Emulator は Windows Docker コンテナー上で実行できます。docker pull コマンドについては Docker HubDockerfile などの詳しい情報については GitHub を、それぞれ参照してください。You can run Azure Cosmos Emulator on the Windows Docker container, see the Docker Hub for the docker pull command and GitHub for the Dockerfile and more information.

エミュレーターとサービスの違いDifferences between the emulator and the service

Azure Cosmos Emulator は、ローカルの開発者ワークステーションに環境をエミュレートして提供するものであるため、このエミュレーターとクラウドにある Azure Cosmos アカウントとの間には機能にいくつかの違いがあります。Because the Azure Cosmos Emulator provides an emulated environment running on the local developer workstation, there are some differences in functionality between the emulator and an Azure Cosmos account in the cloud:

  • エミュレーターのデータ エクスプローラーでは現在、SQL API 用のクライアントがサポートされています。Currently Data Explorer in the emulator supports clients for SQL API. MongoDB API、Table API、Graph API、Cassandra API など、Azure Cosmos DB 用の API については、データ エクスプローラーのビューと操作が完全にはサポートされていません。The Data Explorer view and operations for Azure Cosmos DB APIs such as MongoDB, Table, Graph, and Cassandra APIs are not fully supported.
  • Azure Cosmos Emulator は、1 つの固定アカウントと既知のマスター キーのみに対応しています。The Azure Cosmos Emulator supports only a single fixed account and a well-known master key. Azure Cosmos Emulator ではキーを登録できませんが、コマンドライン オプションを使って既定のキーを変更することは可能です。Key regeneration is not possible in the Azure Cosmos Emulator, however the default key can be changed using the command-line option.
  • Azure Cosmos Emulator はスケーラブルなサービスではなく、大量のコンテナーはサポートされません。The Azure Cosmos Emulator is not a scalable service and will not support a large number of containers.
  • Azure Cosmos Emulator では、異なる Azure Cosmos DB 整合性レベルを利用できません。The Azure Cosmos Emulator does not offer different Azure Cosmos DB consistency levels.
  • Azure Cosmos Emulator では、複数リージョンのレプリケーションを利用できません。The Azure Cosmos Emulator does not offer multi-region replication.
  • ご使用の Azure Cosmos Emulator には Azure Cosmos DB サービスの最近の変更が反映されていないことがあるため、Azure Cosmos DB Capacity Planner を参照し、アプリケーションの運用スループット (RU) のニーズを正確に見積もる必要があります。As your copy of the Azure Cosmos Emulator might not always be up-to-date with the most recent changes in the Azure Cosmos DB service, you should refer to the Azure Cosmos DB capacity planner to accurately estimate the production throughput (RUs) needs of your application.
  • Azure Cosmos Emulator を使用する場合、作成できるコンテナーの数の既定値は、固定サイズのコンテナーであれば 25 個 (Azure Cosmos DB SDK を使用した場合にのみサポート)、容量無制限のコンテナーであれば 5 個までです。When using the Azure Cosmos Emulator, by default, you can create up to 25 fixed size containers (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers using the Azure Cosmos Emulator. この値を変更する方法の詳細については、PartitionCount 値の設定に関するトピックを参照してください。For more information about changing this value, see Setting the PartitionCount value.

システム要件System requirements

Azure Cosmos Emulator のハードウェア要件とソフトウェア要件は、次のとおりです。The Azure Cosmos Emulator has the following hardware and software requirements:

  • ソフトウェア要件Software requirements
    • Windows Server 2012 R2、Windows Server 2016、または Windows 10Windows Server 2012 R2, Windows Server 2016, or Windows 10
    • 64 ビット オペレーティング システム64-bit operating system
  • 最小ハードウェア要件Minimum Hardware requirements
    • 2 GB の RAM2-GB RAM
    • 10 GB のハードディスク空き容量10-GB available hard disk space

インストールInstallation

Microsoft ダウンロード センターから Azure Cosmos Emulator をダウンロードしてインストールできます。または、Docker for Windows でこのエミュレーターを実行できます。You can download and install the Azure Cosmos Emulator from the Microsoft Download Center or you can run the emulator on Docker for Windows. Docker for Windows でエミュレーターを使用する方法については、「Docker で実行する」を参照してください。For instructions on using the emulator on Docker for Windows, see Running on Docker.

注意

Azure Cosmos Emulator をインストール、構成、実行するには、コンピューターの管理特権が必要です。To install, configure, and run the Azure Cosmos Emulator, you must have administrative privileges on the computer. エミュレーターでは、サービスを実行するために証明書の作成/追加と、ファイアウォール規則の設定が行われます。このため、エミュレーターがそのような操作を実行できるようになっている必要があります。The emulator will create/add a certificate and also set the firewall rules in order to run its services; therefore it's necessary for the emulator to be able to execute such operations.

Windows で実行するRunning on Windows

Azure Cosmos Emulator を起動するには、[スタート] ボタンをクリックするか、Windows キーを押します。To start the Azure Cosmos Emulator, select the Start button or press the Windows key. Azure Cosmos Emulator」と入力して、アプリケーションの一覧からエミュレーターを選択します。Begin typing Azure Cosmos Emulator, and select the emulator from the list of applications.

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

エミュレーターの実行中は、Windows タスク バーの通知領域にアイコンが表示されます。When the emulator is running, you'll see an icon in the Windows taskbar notification area. Azure Cosmos DB ローカル エミュレーターのタスク バーの通知

Azure Cosmos Emulator は、既定ではポート 8081 でリッスンしているローカル コンピューター ("localhost") で実行されます。The Azure Cosmos Emulator by default runs on the local machine ("localhost") listening on port 8081.

Azure Cosmos Emulator は、既定では C:\Program Files\Azure Cosmos DB Emulator にインストールされます。The Azure Cosmos Emulator is installed to C:\Program Files\Azure Cosmos DB Emulator by default. コマンドラインを使ってエミュレーターを起動したり停止したりすることもできます。You can also start and stop the emulator from the command-line. 詳しくは、「コマンドライン ツールのリファレンス」をご覧ください。For more information, see the command-line tool reference.

データ エクスプローラーの起動Start Data Explorer

Azure Cosmos Emulator が起動すると、ブラウザーで Azure Cosmos データ エクスプローラーが自動的に開きます。When the Azure Cosmos Emulator launches, it automatically opens the Azure Cosmos Data Explorer in your browser. アドレスは https://localhost:8081/_explorer/index.html として表示されます。The address appears as https://localhost:8081/_explorer/index.html. エクスプローラーを閉じた後にもう一度開く場合は、ブラウザーでこの URL を開くか、次に示すように Windows トレイ アイコンの Azure Cosmos Emulator から起動できます。If you close the explorer and would like to reopen it later, you can either open the URL in your browser or launch it from the Azure Cosmos Emulator in the Windows Tray Icon as shown below.

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

更新プログラムの確認Checking for updates

データ エクスプローラーでは、ダウンロード可能な新しい更新プログラムがあるかどうかが示されます。Data Explorer indicates if there is a new update available for download.

注意

Azure Cosmos Emulator のあるバージョンで作成したデータ (%LOCALAPPDATA%\CosmosDBEmulator またはデータ パスに関するオプション設定を参照してください) は、他のバージョンを使用してアクセスできない可能性があります。Data created in one version of the Azure Cosmos Emulator (see %LOCALAPPDATA%\CosmosDBEmulator or data path optional settings) is not guaranteed to be accessible when using a different version. データを永続化して長期にわたって保持する必要がある場合、そのデータは Azure Cosmos Emulator ではなく Azure Cosmos アカウントに格納することをお勧めします。If you need to persist your data for the long term, it is recommended that you store that data in an Azure Cosmos account, rather than in the Azure Cosmos Emulator.

要求の認証Authenticating requests

クラウドの Azure Cosmos DB と同様に、Azure Cosmos Emulator に対する要求にはいずれも認証が必要です。As with Azure Cosmos DB in the cloud, every request that you make against the Azure Cosmos Emulator must be authenticated. Azure Cosmos Emulator では、マスター キー認証について、単一の固定アカウントと既知の認証キーがサポートされています。The Azure Cosmos Emulator supports a single fixed account and a well-known authentication key for master key authentication. Azure Cosmos Emulator ではこのアカウントとキーのみ、資格情報として使用できます。This account and key are the only credentials permitted for use with the Azure Cosmos Emulator. 次に例を示します。They are:

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

注意

Azure Cosmos Emulator でサポートされているマスター キーは、エミュレーターで使用することのみを想定したものです。The master key supported by the Azure Cosmos Emulator is intended for use only with the emulator. Azure Cosmos Emulator で運用環境の Azure Cosmos DB アカウントとキーを使用することはできません。You cannot use your production Azure Cosmos DB account and key with the Azure Cosmos Emulator.

注意

/Key オプションを使用してエミュレーターを開始した場合は、C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== の代わりに生成されたキーを使用します。If you have started the emulator with the /Key option, then use the generated key instead of C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. /Key オプションの詳細については、「コマンドライン ツールのリファレンス」を参照してください。For more information about /Key option, see Command-line tool reference.

Azure Cosmos DB と同様に、Azure Cosmos Emulator では SSL 経由のセキュリティ保護された通信のみサポートされています。As with the Azure Cosmos DB, the Azure Cosmos Emulator supports only secure communication via SSL.

ローカル ネットワークで実行するRunning on a local network

ローカル ネットワークでのエミュレーターを実行できます。You can run the emulator on a local network. ネットワーク アクセスを有効にするには、コマンド ライン/AllowNetworkAccess オプションを指定します。また、/Key=key_string または /KeyFile=file_name を指定する必要もあります。To enable network access, specify the /AllowNetworkAccess option at the command-line, which also requires that you specify /Key=key_string or /KeyFile=file_name. /GenKeyFile=file_name を使用すると、ランダムなキーを備えたファイルを事前に生成できます。You can use /GenKeyFile=file_name to generate a file with a random key upfront. その後、それを /KeyFile=file_name または /Key=contents_of_file に渡すことができます。Then you can pass that to /KeyFile=file_name or /Key=contents_of_file.

ネットワーク アクセスを初めて有効にする場合は、エミュレーターをシャットダウンし、エミュレーターのデータ ディレクトリ (%LOCALAPPDATA%\CosmosDBEmulator) を削除する必要があります。To enable network access for the first time the user should shut down the emulator and delete the emulator’s data directory (%LOCALAPPDATA%\CosmosDBEmulator).

エミュレーターを使用した開発Developing with the emulator

SQL APISQL API

デスクトップで Azure Cosmos Emulator が実行中になったら、サポートされている Azure Cosmos DB SDK または Azure Cosmos DB REST API を使用してエミュレーターを操作できます。Once you have the Azure Cosmos Emulator running on your desktop, you can use any supported Azure Cosmos DB SDK or the Azure Cosmos DB REST API to interact with the emulator. Azure Cosmos Emulator にはデータ エクスプローラーも組み込まれており、コードを記述することなく、SQL API または Cosmos DB for MongoDB API 用のコンテナーを作成したり、項目の表示と編集を行ったりできます。The Azure Cosmos Emulator also includes a built-in Data Explorer that lets you create containers for SQL API or Cosmos DB for Mongo DB API, and view and edit items without writing any code.

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

Azure Cosmos DB の MongoDB 用 APIAzure Cosmos DB's API for MongoDB

ご自分のデスクトップ上で Azure Cosmos Emulator が実行中になったら、Azure Cosmos DB の MongoDB 用 API を使用してエミュレーターを操作できます。Once you have the Azure Cosmos Emulator running on your desktop, you can use the Azure Cosmos DB's API for MongoDB to interact with the emulator. コマンド プロンプトから管理者としてエミュレーターを起動します。その際、一緒に "/EnableMongoDbEndpoint" を指定します。Start emulator from command prompt as an administrator with "/EnableMongoDbEndpoint". その後、次の接続文字列を使用して MongoDB API アカウントに接続します。Then use the following connection string to connect to the MongoDB API account:

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

テーブル APITable API

デスクトップで Azure Cosmos Emulator が実行中になったら、Azure Cosmos DB Table API SDK を使用してエミュレーターを操作できます。Once you have the Azure Cosmos Emulator running on your desktop, you can use the Azure Cosmos DB Table API SDK to interact with the emulator. コマンド プロンプトから管理者としてエミュレーターを起動します。その際、一緒に "/EnableTableEndpoint" を指定します。Start emulator from command prompt as an administrator with “/EnableTableEndpoint”. 続いて、次のコードを実行して Table API アカウントに接続します。Next run the following code to connect to the table API account:

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 APICassandra API

管理者のコマンド プロンプトからエミュレーターを起動します。その際、一緒に "/EnableCassandraEndpoint" を指定します。Start emulator from an administrator command prompt with “/EnableCassandraEndpoint”. 代わりに、環境変数 AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true を設定することもできます。Alternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.

  • Python 2.7 をインストールしますInstall Python 2.7

  • Cassandra CLI/CQLSH をインストールしますInstall Cassandra CLI/CQLSH

  • 通常のコマンド プロンプト ウィンドウで次のコマンドを実行します。Run the following commands in a regular command prompt window:

    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 エンドポイントに接続します。In the CQLSH shell, run the following commands to connect to the Cassandra endpoint:

    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 APIGremlin API

管理者のコマンド プロンプトからエミュレーターを起動します。その際、一緒に "/EnableGremlinEndpoint" を指定します。Start emulator from an administrator command prompt with “/EnableGremlinEndpoint”. 代わりに、環境変数 AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true を設定することもできますAlternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

  • apache-tinkerpop-gremlin-console-3.3.4 をインストールしますInstall apache-tinkerpop-gremlin-console-3.3.4

  • エミュレーター内で、データ エクスプローラーによりデータベース "db1" とコレクション "coll1" が作成されます。パーティション キーには "/name" を選択しますIn the emulator’s Data Explorer create a database "db1" and a collection "coll1"; for the partition key, choose "/name"

  • 通常のコマンド プロンプト ウィンドウで次のコマンドを実行します。Run the following commands in a regular command prompt window:

    cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.3.4-bin\apache-tinkerpop-gremlin-console-3.3.4
    
    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 エンドポイントに接続します。In the Gremlin shell run the following commands to connect to the Gremlin endpoint:

    :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()
    

SSL 証明書のエクスポートExport the SSL certificate

.NET 言語とランタイムでは、Azure Cosmos DB ローカル エミュレーターに安全に接続するために Windows 証明書ストアが使用されます。.NET languages and runtime use the Windows Certificate Store to securely connect to the Azure Cosmos DB local emulator. その他の言語では、証明書の管理と使用について独自の方法があります。Other languages have their own method of managing and using certificates. Java の場合は独自の証明書ストアが使用され、Python の場合はソケット ラッパーが使用されます。Java uses its own certificate store whereas Python uses socket wrappers.

Windows 証明書ストアと統合されていない言語およびランタイムで使用する証明書を取得するには、Windows 証明書マネージャーを使用して証明書をエクスポートする必要があります。In order to obtain a certificate to use with languages and runtimes that do not integrate with the Windows Certificate Store, you will need to export it using the Windows Certificate Manager. これは certlm.msc を実行することで開始できます。または、Azure Cosmos Emulator 証明書のエクスポートに関するページに記載されている手順に従ってください。You can start it by running certlm.msc or follow the step by step instructions in Export the Azure Cosmos Emulator Certificates. 証明書マネージャーの実行中、次に示すように Personal フォルダーの Certificates を開き、"DocumentDBEmulatorCertificate" というフレンドリ名の証明書を BASE-64 encoded X.509 (.cer) ファイルとしてエクスポートします。Once the certificate manager is running, open the Personal Certificates as shown below and export the certificate with the friendly name "DocumentDBEmulatorCertificate" as a BASE-64 encoded X.509 (.cer) file.

Azure Cosmos DB ローカル エミュレーターの SSL 証明書

X.509 証明書を Java 証明書ストアにインポートするには、「証明書を Java CA 証明書ストアに追加する方法」の手順に従います。The X.509 certificate can be imported into the Java certificate store by following the instructions in Adding a Certificate to the Java CA Certificates Store. 証明書を証明書ストアにインポートすると、SQL API および Azure Cosmos DB の MongoDB 用 API のクライアントが Azure Cosmos Emulator に接続できるようになります。Once the certificate is imported into the certificate store, clients for SQL and Azure Cosmos DB's API for MongoDB will be able to connect to the Azure Cosmos Emulator.

Python SDK および Node.js SDK からエミュレーターに接続すると、SSL 検証が無効になります。When connecting to the emulator from Python and Node.js SDKs, SSL verification is disabled.

コマンドライン ツールのリファレンスCommand-line tool reference

インストール先では、コマンドラインを使用することで、エミュレーターの開始と停止やオプションの構成などの操作を実行できます。From the installation location, you can use the command-line to start and stop the emulator, configure options, and perform other operations.

コマンドライン構文Command-line syntax

CosmosDB.Emulator.exe [/Shutdown] [/DataPath] [/Port] [/MongoPort] [/DirectPorts] [/Key] [/EnableRateLimiting] [/DisableRateLimiting] [/NoUI] [/NoExplorer] [/EnableMongoDbEndpoint] [/?]

オプションの一覧を表示するには、コマンド プロンプトで「 CosmosDB.Emulator.exe /? 」と入力します。To view the list of options, type CosmosDB.Emulator.exe /? at the command prompt.

オプションOption 説明Description コマンドCommand 引数Arguments
[引数なし][No arguments] 既定の設定で Azure Cosmos Emulator を起動します。Starts up the Azure Cosmos Emulator with default settings. CosmosDB.Emulator.exeCosmosDB.Emulator.exe
[Help][Help] サポートされるコマンド ライン引数の一覧を表示します。Displays the list of supported command-line arguments. CosmosDB.Emulator.exe /?CosmosDB.Emulator.exe /?
GetStatusGetStatus Azure Cosmos Emulator の状態を取得します。Gets the status of the Azure Cosmos Emulator. この状態は、終了コードで示されます。終了コードは、1 = 開始中、2 = 実行中、3 = 停止済みです。The status is indicated by the exit code: 1 = Starting, 2 = Running, 3 = Stopped. 負の終了コードは、エラーが発生したことを示します。A negative exit code indicates that an error occurred. その他の出力は生成されません。No other output is produced. CosmosDB.Emulator.exe /GetStatusCosmosDB.Emulator.exe /GetStatus
ShutdownShutdown Azure Cosmos Emulator をシャットダウンします。Shuts down the Azure Cosmos Emulator. CosmosDB.Emulator.exe /ShutdownCosmosDB.Emulator.exe /Shutdown
DataPathDataPath データ ファイルを格納するパスを指定します。Specifies the path in which to store data files. 既定値は %LocalAppdata%\CosmosDBEmulator です。Default value is %LocalAppdata%\CosmosDBEmulator. CosmosDB.Emulator.exe /DataPath=<datapath>CosmosDB.Emulator.exe /DataPath=<datapath> <datapath>:アクセスできるパス<datapath>: An accessible path
PortPort エミュレーターで使用するポート番号を指定します。Specifies the port number to use for the emulator. 既定値は 8081 です。Default value is 8081. CosmosDB.Emulator.exe /Port=<port>CosmosDB.Emulator.exe /Port=<port> <port>:単一のポート番号<port>: Single port number
ComputePortComputePort Compute Interop Gateway サービスに使用するポート番号を指定します。Specified the port number to use for the Compute Interop Gateway service. ゲートウェイの HTTP エンドポイント プローブ ポートのポート番号は、ComputePort に 79 を加えた値として計算されます。The Gateway's HTTP endpoint probe port is calculated as ComputePort + 79. このため、ComputePort と ComputePort に 79 を加えた番号のポートは、開いて利用可能な状態にしておく必要があります。Hence, ComputePort and ComputePort + 79 must be open and available. 既定値は 8900 と 8979 です。The default values are 8900, 8979. CosmosDB.Emulator.exe /ComputePort = <computeport>CosmosDB.Emulator.exe /ComputePort = <computeport> <computeport>:単一のポート番号<computeport>: Single port number
EnableMongoDbEndpointEnableMongoDbEndpoint MongoDB API を有効にしますEnables MongoDB API CosmosDB.Emulator.exe /EnableMongoDbEndpointCosmosDB.Emulator.exe /EnableMongoDbEndpoint
MongoPortMongoPort MongoDB 互換性 API に使用するポート番号を指定します。Specifies the port number to use for MongoDB compatibility API. 既定値は 10255 です。Default value is 10255. CosmosDB.Emulator.exe /MongoPort= <mongoport>CosmosDB.Emulator.exe /MongoPort= <mongoport> <mongoport>:単一のポート番号<mongoport>: Single port number
EnableCassandraEndpointEnableCassandraEndpoint Cassandra API を有効にしますEnables Cassandra API CosmosDB.Emulator.exe /EnableCassandraEndpointCosmosDB.Emulator.exe /EnableCassandraEndpoint
CassandraPortCassandraPort Cassandra エンドポイントで使用するポート番号を指定します。Specifies the port number to use for the Cassandra endpoint. 既定値は 10350 です。Default value is 10350. CosmosDB.Emulator.exe /CassandraPort = <cassandraport>CosmosDB.Emulator.exe /CassandraPort = <cassandraport> <cassandraport>:単一のポート番号<cassandraport>: Single port number
EnableGremlinEndpointEnableGremlinEndpoint Gremlin API を有効にしますEnables Gremlin API CosmosDB.Emulator.exe /EnableGremlinEndpointCosmosDB.Emulator.exe /EnableGremlinEndpoint
GremlinPortGremlinPort Gremlin エンドポイントに使用するポート番号です。Port number to use for the Gremlin Endpoint. 既定値は 8901 です。Default value is 8901. CosmosDB.Emulator.exe /GremlinPort=<port>CosmosDB.Emulator.exe /GremlinPort=<port> <port>:単一のポート番号<port>: Single port number
EnableTableEndpointEnableTableEndpoint Azure Table API を有効にしますEnables Azure Table API CosmosDB.Emulator.exe /EnableTableEndpointCosmosDB.Emulator.exe /EnableTableEndpoint
TablePortTablePort Azure Table エンドポイントに使用するポート番号です。Port number to use for the Azure Table Endpoint. 既定値は 8902 です。Default value is 8902. CosmosDB.Emulator.exe /TablePort=<port>CosmosDB.Emulator.exe /TablePort=<port> <port>:単一のポート番号<port>: Single port number
KeyFileKeyFile 指定されたファイルから承認キーを読み取ります。Read authorization key from the specified file. キーファイルの生成には、/GenKeyFile オプションを使用しますUse the /GenKeyFile option to generate a keyfile CosmosDB.Emulator.exe /KeyFile=<file_name>CosmosDB.Emulator.exe /KeyFile=<file_name> <file_name>:ファイルへのパス<file_name>: Path to the file
ResetDataPathResetDataPath 指定されたパスにある全部のファイルを、再帰的に削除します。Recursively removes all the files in the specified path. パスを指定しなかった場合には、既定値が %LOCALAPPDATA%\CosmosDbEmulator になりますIf you don't specify a path, it defaults to %LOCALAPPDATA%\CosmosDbEmulator CosmosDB.Emulator.exe /ResetDataPath=<path>CosmosDB.Emulator.exe /ResetDataPath=<path> <path>:ファイル パス<path>: File path
StartTracesStartTraces デバッグ トレース ログの収集を開始します。Start collecting debug trace logs. CosmosDB.Emulator.exe /StartTracesCosmosDB.Emulator.exe /StartTraces
StopTracesStopTraces デバッグ トレース ログの収集を停止します。Stop collecting debug trace logs. CosmosDB.Emulator.exe /StopTracesCosmosDB.Emulator.exe /StopTraces
FailOnSslCertificateNameMismatchFailOnSslCertificateNameMismatch 証明書の SAN にエミュレーターのホストのドメイン名、ローカル IPv4 アドレス、"localhost"、"127.0.0.1" が含まれていない場合、既定では、エミュレーターにより自己署名 SSL 証明書が再生成されます。By default the Emulator regenerates its self-signed SSL certificate, if the certificate's SAN does not include the Emulator host's domain name, local IPv4 address, 'localhost', and '127.0.0.1'. このオプションを設定すると、その代わりにエミュレーターが起動に失敗します。With this option, the emulator will fail at startup instead. その後は /GenCert オプションを使って新しい自己署名 SSL 証明書を作成およびインストールする必要があります。You should then use the /GenCert option to create and install a new self-signed SSL certificate. CosmosDB.Emulator.exe /FailOnSslCertificateNameMismatchCosmosDB.Emulator.exe /FailOnSslCertificateNameMismatch
GenCertGenCert 新しい自己署名 SSL 証明書を生成およびインストールします。Generate and install a new self-signed SSL certificate. オプションで、ネットワーク経由でエミュレーターにアクセスするための追加の DNS 名を列挙したコンマ区切りリストを含めることもできます。optionally including a comma-separated list of additional DNS names for accessing the Emulator over the network. CosmosDB.Emulator.exe /GenCert=<dns-names>CosmosDB.Emulator.exe /GenCert=<dns-names> <dns-names>: 追加の DNS 名のコンマ区切りリスト (省略可能)<dns-names>: Optional comma-separated list of additional dns names
DirectPortsDirectPorts 直接接続に使用するポートを指定します。Specifies the ports to use for direct connectivity. 既定値は、10251、10252、10253、10254 です。Defaults are 10251,10252,10253,10254. CosmosDB.Emulator.exe /DirectPorts:<directports>CosmosDB.Emulator.exe /DirectPorts:<directports> <directports>:4 つのポートのコンマ区切りリスト<directports>: Comma-delimited list of 4 ports
KeyKey エミュレーターの承認キーです。Authorization key for the emulator. キーは、64 バイト ベクトルの Base 64 エンコーディングが施されている必要があります。Key must be the base-64 encoding of a 64-byte vector. CosmosDB.Emulator.exe /Key:<key>CosmosDB.Emulator.exe /Key:<key> <key>:キーは、64 バイト ベクトルの Base 64 エンコーディングが施されている必要があります<key>: Key must be the base-64 encoding of a 64-byte vector
EnableRateLimitingEnableRateLimiting 要求レート制限の動作の有効化を指定します。Specifies that request rate limiting behavior is enabled. CosmosDB.Emulator.exe /EnableRateLimitingCosmosDB.Emulator.exe /EnableRateLimiting
DisableRateLimitingDisableRateLimiting 要求レート制限の動作の無効化を指定します。Specifies that request rate limiting behavior is disabled. CosmosDB.Emulator.exe /DisableRateLimitingCosmosDB.Emulator.exe /DisableRateLimiting
NoUINoUI エミュレーターのユーザー インターフェイスを表示しません。Do not show the emulator user interface. CosmosDB.Emulator.exe /NoUICosmosDB.Emulator.exe /NoUI
NoExplorerNoExplorer 起動時にデータ エクスプローラーを表示しません。Don't show data explorer on startup. CosmosDB.Emulator.exe /NoExplorerCosmosDB.Emulator.exe /NoExplorer
PartitionCountPartitionCount パーティション分割されたコンテナーの最大数を指定します。Specifies the maximum number of partitioned containers. 詳細については、「コンテナーの数を変更する」を参照してください。See Change the number of containers for more information. CosmosDB.Emulator.exe /PartitionCount=<partitioncount>CosmosDB.Emulator.exe /PartitionCount=<partitioncount> <partitioncount>:許容される単一パーティション コンテナーの最大数です。<partitioncount>: Maximum number of allowed single partition containers. 既定値は 25 です。Default value is 25. 許容される最大値は 250 です。Maximum allowed is 250.
DefaultPartitionCountDefaultPartitionCount パーティション分割されたコンテナーの既定のパーティション数を指定します。Specifies the default number of partitions for a partitioned container. CosmosDB.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount>CosmosDB.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount> <defaultpartitioncount> 既定値は 25 です。<defaultpartitioncount> Default value is 25.
AllowNetworkAccessAllowNetworkAccess ネットワーク上でのエミュレーターへのアクセスを有効にします。Enables access to the emulator over a network. /Key=<key_string> または /KeyFile=<file_name> を渡して、ネットワーク アクセスを有効にする必要があります。You must also pass /Key=<key_string> or /KeyFile=<file_name> to enable network access. CosmosDB.Emulator.exe /AllowNetworkAccess /Key=<key_string> または CosmosDB.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>CosmosDB.Emulator.exe /AllowNetworkAccess /Key=<key_string> or CosmosDB.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>
NoFirewallNoFirewall /AllowNetworkAccess オプションが使用されているときは、ファイアウォール規則を調整しないでください。Don't adjust firewall rules when /AllowNetworkAccess option is used. CosmosDB.Emulator.exe /NoFirewallCosmosDB.Emulator.exe /NoFirewall
GenKeyFileGenKeyFile 新しい承認キーを生成し、指定したファイルに保存します。Generate a new authorization key and save to the specified file. 生成されたキーは、/Key オプションまたは/KeyFile オプションで使用できます。The generated key can be used with the /Key or /KeyFile options. CosmosDB.Emulator.exe /GenKeyFile=<キー ファイルへのパス>CosmosDB.Emulator.exe /GenKeyFile=<path to key file>
整合性Consistency アカウントの既定の一貫性レベルを設定します。Set the default consistency level for the account. CosmosDB.Emulator.exe /Consistency=<consistency>CosmosDB.Emulator.exe /Consistency=<consistency> <consistency>:値は次のいずれかの一貫性レベルである必要があります。Session、Strong、Eventual、または BoundedStaleness。<consistency>: Value must be one of the following consistency levels: Session, Strong, Eventual, or BoundedStaleness. 既定値は Session です。The default value is Session.
?? ヘルプ メッセージを表示します。Show the help message.

コンテナーの数を変更するChange the number of containers

Azure Cosmos Emulator で作成できるコンテナーの数の既定値は、固定サイズのコンテナーであれば 25 個 (Azure Cosmos DB SDK を使用した場合にのみサポート)、容量無制限のコンテナーであれば 5 個までです。By default, you can create up to 25 fixed size containers (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers using the Azure Cosmos Emulator. PartitionCount の値を変更すると、固定サイズのコンテナーであれば 250 個、容量無制限のコンテナーであれば 50 個まで作成できるようになります。この 2 つの組み合わせは、固定サイズのコンテナー 250 個分を超えない範囲であれば、自由に決めることができます (容量無制限のコンテナーは、1 個につき固定サイズのコンテナー 5 個分として計算されます)。By modifying the PartitionCount value, you can create up to 250 fixed size containers or 50 unlimited containers, or any combination of the two that does not exceed 250 fixed size containers (where one unlimited container = 5 fixed size containers). ただし、固定サイズのコンテナーが 200 個以上の状態でエミュレーターを実行する設定にはしないことをお勧めします。However it's not recommended to set up the emulator to run with more than 200 fixed size containers. これは、ディスクの IO 操作にオーバーヘッドが加わり、エンドポイント API の使用中に予測し得ないタイムアウトが発生する原因となるためです。Because of the overhead that it adds to the disk IO operations, which result in unpredictable timeouts when using the endpoint APIs.

現在のパーティション数を超えた後にコンテナーを作成しようとすると、次のメッセージと共に ServiceUnavailable 例外がスローされます。If you attempt to create a container after the current partition count has been exceeded, the emulator throws a ServiceUnavailable exception, with the following message.

"申し訳ありません。このリージョンでは現在需要が高まっており、要求にお応えすることができない状況です。"Sorry, we are currently experiencing high demand in this region, and cannot fulfill your request at this time. Microsoft では引き続きオンラインの容量を拡充し、もう一度お試しいただくご案内ができるよう取り組んでまいります。We work continuously to bring more and more capacity online, and encourage you to try again. ご不明な点がありましたら、内容を問わずいつでも askcosmosdb@microsoft.com までメールをお送りください。Please do not hesitate to email askcosmosdb@microsoft.com at any time or for any reason. ActivityId:12345678-1234-1234-1234-123456789abc"ActivityId: 12345678-1234-1234-1234-123456789abc"

Azure Cosmos Emulator で利用可能なコンテナーの数を変更する手順は次のとおりです。To change the number of containers available in the Azure Cosmos Emulator, run the following steps:

  1. システム トレイの [Azure Cosmos DB Emulator] アイコンを右クリックし、 [Reset Data](データのリセット) をクリックして、ローカルの Azure Cosmos Emulator データをすべて削除します。Delete all local Azure Cosmos Emulator data by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Reset Data….
  2. フォルダー %LOCALAPPDATA%\CosmosDBEmulator にあるエミュレーターのデータをすべて削除します。Delete all emulator data in this folder %LOCALAPPDATA%\CosmosDBEmulator.
  3. システム トレイの [Azure Cosmos DB Emulator] アイコンを右クリックし、 [終了] をクリックし、開いているインスタンスをすべて終了します。Exit all open instances by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Exit. すべてのインスタンスが終了するまでしばらく時間がかかる場合があります。It may take a minute for all instances to exit.
  4. 最新版の Azure Cosmos Emulator をインストールします。Install the latest version of the Azure Cosmos Emulator.
  5. PartitionCount フラグの値を 250 以下に設定して、エミュレーターを起動します。Launch the emulator with the PartitionCount flag by setting a value <= 250. (例: C:\Program Files\Azure Cosmos DB Emulator> CosmosDB.Emulator.exe /PartitionCount=100)。For example: C:\Program Files\Azure Cosmos DB Emulator> CosmosDB.Emulator.exe /PartitionCount=100.

エミュレーターの制御Controlling the emulator

エミュレーターには、サービスの開始、停止、アンインストール、状態の取得のための PowerShell モジュールが付属しています。The emulator comes with a PowerShell module to start, stop, uninstall, and retrieve the status of the service. この PowerShell モジュールを使用するには、次のコマンドレットを実行します。Run the following cmdlet to use the PowerShell module:

Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"

このほか、PSModulesPathPSModules ディレクトリを追加したうえで、次のコマンドを使用してインポートする方法もあります。or place the PSModules directory on your PSModulesPath and import it as shown in the following command:

$env:PSModulesPath += "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules"
Import-Module Microsoft.Azure.CosmosDB.Emulator

PowerShell からエミュレーターを制御するためのコマンドの概要を次に示します。Here is a summary of the commands for controlling the emulator from PowerShell:

Get-CosmosDbEmulatorStatus

構文Syntax

Get-CosmosDbEmulatorStatus

解説Remarks

次のいずれかの ServiceControllerStatus 値が返されます。ServiceControllerStatus.StartPending、ServiceControllerStatus.Running、または ServiceControllerStatus.Stopped。Returns one of these ServiceControllerStatus values: ServiceControllerStatus.StartPending, ServiceControllerStatus.Running, or ServiceControllerStatus.Stopped.

Start-CosmosDbEmulator

構文Syntax

Start-CosmosDbEmulator [-DataPath <string>] [-DefaultPartitionCount <uint16>] [-DirectPort <uint16[]>] [-MongoPort <uint16>] [-NoUI] [-NoWait] [-PartitionCount <uint16>] [-Port <uint16>] [<CommonParameters>]

解説Remarks

エミュレーターを起動します。Starts the emulator. 既定では、このコマンドは、エミュレーターで要求を受け付ける準備ができるまで待ちます。By default, the command waits until the emulator is ready to accept requests. エミュレーターを起動したらすぐにコマンドレットから戻るようにする場合は、-NoWait オプションを使用します。Use the -NoWait option, if you wish the cmdlet to return as soon as it starts the emulator.

Stop-CosmosDbEmulator

構文Syntax

Stop-CosmosDbEmulator [-NoWait]

解説Remarks

エミュレーターを停止します。Stops the emulator. 既定では、このコマンドは、エミュレーターが完全に停止するまで待ちます。By default, this command waits until the emulator is fully shut down. エミュレーターが停止し始めたらすぐにコマンドレットから戻るようにする場合は、-NoWait オプションを使用します。Use the -NoWait option, if you wish the cmdlet to return as soon as the emulator begins to shut down.

Uninstall-CosmosDbEmulator

構文Syntax

Uninstall-CosmosDbEmulator [-RemoveData]

解説Remarks

エミュレーターをアンインストールし、オプションで $env:LOCALAPPDATA\CosmosDbEmulator のすべての内容を削除します。Uninstalls the emulator and optionally removes the full contents of $env:LOCALAPPDATA\CosmosDbEmulator. このコマンドレットは、アンインストールする前にエミュレーターが停止されたことを確認します。The cmdlet ensures the emulator is stopped before uninstalling it.

Docker で実行するRunning on Docker

Azure Cosmos Emulator は、Docker for Windows 上で実行できます。The Azure Cosmos Emulator can be run on Docker for Windows. エミュレーターは、Docker for Oracle Linux では機能しません。The emulator does not work on Docker for Oracle Linux.

Docker for Windows をインストールしたら、ツール バーの Docker アイコンを右クリックし、 [Switch to Windows containers](Windows コンテナーに切り替える) を選択して Windows コンテナーに切り替えます。Once you have Docker for Windows installed, switch to Windows containers by right-clicking the Docker icon on the toolbar and selecting Switch to Windows containers.

次に、普段利用しているシェルから次のコマンドを実行し、Docker Hub からエミュレーター イメージをプルします。Next, pull the emulator image from Docker Hub by running the following command from your favorite shell.

docker pull mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator

イメージを起動するには、次のコマンドを実行します。To start the image, run the following commands.

コマンド ラインから:From the command-line:


md %LOCALAPPDATA%\CosmosDBEmulator\bind-mount

docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%LOCALAPPDATA%\CosmosDBEmulator\bind-mount,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator

注意

docker run コマンドを実行するときにポートの競合エラー (指定されたポートが既に使用されている) が表示される場合は、ポート番号を変更してカスタム ポートを渡すことができます。If you see a port conflict error (specified port is already in use) when you run the docker run command, you can pass a custom port by altering the port numbers. たとえば、"-p 8081:8081" を "-p 443:8081" に変更できますFor example, you can change the "-p 8081:8081" to "-p 443:8081"

PowerShell から:From PowerShell:


md $env:LOCALAPPDATA\CosmosDBEmulator\bind-mount 2>null

docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=$env:LOCALAPPDATA\CosmosDBEmulator\bind-mount,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator

応答は次のようになります。The response looks similar to the following:

Starting emulator
Emulator Endpoint: https://172.20.229.193:8081/
Master Key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Exporting SSL Certificate
You can import the SSL certificate from an administrator command prompt on the host by running:
cd /d %LOCALAPPDATA%\CosmosDBEmulatorCert
powershell .\importcert.ps1
--------------------------------------------------------------------------------------------------
Starting interactive shell

クライアントで応答からのエンドポイントとマスター キーを使用し、SSL 証明書をホストにインポートします。Now use the endpoint and master key-in from the response in your client and import the SSL certificate into your host. SSL 証明書をインポートするには、admin コマンド プロンプトから以下を実行します。To import the SSL certificate, do the following from an admin command prompt:

コマンド ラインから:From the command-line:

cd  %LOCALAPPDATA%\CosmosDBEmulator\bind-mount
powershell .\importcert.ps1

PowerShell から:From PowerShell:

cd $env:LOCALAPPDATA\CosmosDBEmulator\bind-mount
.\importcert.ps1

エミュレーターの起動後に対話型シェルを閉じると、エミュレーターのコンテナーがシャットダウンします。Closing the interactive shell once the emulator has been started will shut down the emulator’s container.

データ エクスプローラーを開くには、ブラウザーで次の URL に移動します。To open the Data Explorer, navigate to the following URL in your browser. 上記の応答メッセージにエミュレーター エンドポイントが表示されます。The emulator endpoint is provided in the response message shown above.

https://<emulator endpoint provided in response>/_explorer/index.html

Linux docker コンテナーで実行されている .NET クライアント アプリケーションがあり、ホスト コンピューター上で Azure Cosmos Emulator を実行している場合、エミュレーターから Azure Cosmos アカウントに接続することはできません。If you have a .NET client application running on a Linux docker container and if you are running Azure Cosmos emulator on a host machine, in this case you can’t connect to the Azure Cosmos account from the emulator. アプリがホスト コンピューター上で実行されていないため、エミュレーターのエンドポイントに一致する、Linux コンテナーに登録されている証明書を追加することはできません。Because the app is not running on the host machine, the certificate registered on the Linux container that matches the emulator’s endpoint cannot be added.

この回避策として、次の .Net コード サンプルに示すように HttpClientHandler インスタンスを渡すことによって、クライアント アプリケーションからサーバーの SSL 証明書の検証を無効にすることができます。As a workaround, you can disable the server’s SSL certificate validation from your client application by passing a HttpClientHandler instance as shown in the following .Net code sample. この回避策は、Microsoft.Azure.DocumentDB Nuget パッケージを使用している場合にのみ適用されます。これは Microsoft.Azure.Cosmos Nuget パッケージではサポートされていません。This workaround is only applicable if you are using the Microsoft.Azure.DocumentDB Nuget package, it isn't supported with the Microsoft.Azure.Cosmos Nuget package:

var httpHandler = new HttpClientHandler()
{
   ServerCertificateCustomValidationCallback = (req,cert,chain,errors) => true
};

using (DocumentClient client = new DocumentClient(new Uri(strEndpoint), strKey, httpHandler))
{
   RunDatabaseDemo(client).GetAwaiter().GetResult();
}

SSL 証明書の検証を無効にするだけでなく、/allownetworkaccess オプションを使用してエミュレーターを起動し、エミュレーターのエンドポイントが host.docker.internal DNS ではなくホスト IP アドレスからアクセスできることが重要です。In addition to disabling the SSL certificate validation, it is important that you start the emulator with the /allownetworkaccess option and the emulator’s endpoint is accessible from the host IP address rather than host.docker.internal DNS.

Mac または Linux 上での実行Running on Mac or Linux

現在、Cosmos エミュレーターは Windows でのみ実行できます。Currently the Cosmos emulator can only be run on Windows. Mac または Linux を実行するユーザーは、Windows 仮想マシンによってホストされる、Parallels や VirtualBox などのハイパーバイザー内でエミュレーターを実行できます。Users running Mac or Linux can run the emulator in a Windows virtual machine hosted a hypervisor such as Parallels or VirtualBox. これを有効にする手順は、次のとおりです。Below are the steps to enable this.

Windows VM 内で以下のコマンドを実行して、IPv4 アドレスをメモします。Within the Windows VM run the command below and make note of the IPv4 address.

ipconfig.exe

アプリケーション内で、ipconfig.exe によって返される IPv4 アドレスを使用するには、DocumentClient オブジェクトの URI を変更する必要があります。Within your application you need to change the URI for the DocumentClient object to use the IPv4 address returned by ipconfig.exe. 次の手順では、DocumentClient オブジェクトを構築するときに、CA 検証を回避します。The next step is to work around the CA validation when constructing the DocumentClient object. このためには、HttpClientHandler を、ServerCertificateCustomValidationCallback のその独自の実装を持つ DocumentClient コンストラクターに指定する必要があります。For this you will need to provide an HttpClientHandler to the DocumentClient constructor, which has it's own implementation for ServerCertificateCustomValidationCallback.

下は必要なコードの例です。Below is an example of what the code should look like.

using System;
using Microsoft.Azure.Documents;
using Microsoft.Azure.Documents.Client;
using System.Net.Http;

namespace emulator
{
    class Program
    {
        static async void Main(string[] args)
        {
            string strEndpoint = "https://10.135.16.197:8081/";  //IPv4 address from ipconfig.exe
            string strKey = "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==";

            //Work around the CA validation
            var httpHandler = new HttpClientHandler()
            {
                ServerCertificateCustomValidationCallback = (req,cert,chain,errors) => true
            };

            //Pass http handler to document client
            using (DocumentClient client = new DocumentClient(new Uri(strEndpoint), strKey, httpHandler))
            {
                Database database = await client.CreateDatabaseIfNotExistsAsync(new Database { Id = "myDatabase" });
                Console.WriteLine($"Created Database: id - {database.Id} and selfLink - {database.SelfLink}");
            }
        }
    }
}

最後に、Windows VM 内から、次のオプションを使用してコマンド ラインから Cosmos エミュレーターを起動します。Finally, from the within the Windows VM, launch the Cosmos emulator from the command line using the following options.

Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

トラブルシューティングTroubleshooting

次のヒントは、Azure Cosmos Emulator で発生する問題のトラブルシューティングに役立ちます。Use the following tips to help troubleshoot issues you encounter with the Azure Cosmos Emulator:

  • 新しいバージョンのエミュレーターをインストールしてエラーが発生している場合は、データをリセットしていることを確認します。If you installed a new version of the emulator and are experiencing errors, ensure you reset your data. システム トレイの [Azure Cosmos Emulator] アイコンを右クリックし、[Reset Data](データのリセット) をクリックすると、データをリセットできます。You can reset your data by right-clicking the Azure Cosmos Emulator icon on the system tray, and then clicking Reset Data…. それでもエラーが解消しない場合には、エミュレーターを (旧バージョンがあれば、それも含めて) アンインストールし、"C:\Program files\Azure Cosmos DB Emulator" ディレクトリを削除してから、エミュレーターを再インストールします。If that does not fix the errors, you can uninstall the emulator and any older versions of the emulator if found, remove "C:\Program files\Azure Cosmos DB Emulator" directory and reinstall the emulator. 手順については、「ローカル エミュレーターのアンインストール」をご覧ください。See Uninstall the local emulator for instructions.

  • Azure Cosmos Emulator がクラッシュした場合には、%LOCALAPPDATA%\CrashDumps フォルダーからダンプ ファイルを収集し、圧縮したうえでメールに添付して askcosmosdb@microsoft.com にお送りください。If the Azure Cosmos Emulator crashes, collect dump files from '%LOCALAPPDATA%\CrashDumps' folder, compress them, and attach them to an email to askcosmosdb@microsoft.com.

  • Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe にクラッシュが発生した場合、パフォーマンス カウンターが破損していることを示す兆候である可能性が考えられます。If you experience crashes in Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe, this might be a symptom where the Performance Counters are in a corrupted state. この問題は通常、管理者のコマンド プロンプトから次のコマンドを実行すると解消します。Usually running the following command from an admin command prompt fixes the issue:

    lodctr /R
    
  • 接続の問題が発生した場合は、トレース ファイルを収集し、それらを圧縮して、askcosmosdb@microsoft.com への電子メールに添付します。If you encounter a connectivity issue, collect trace files, compress them, and attach them to an email to askcosmosdb@microsoft.com.

  • "サービス利用不可" というメッセージが表示された場合、エミュレーターがネットワーク スタックの初期化に失敗している可能性があります。If you receive a Service Unavailable message, the emulator might be failing to initialize the network stack. Pulse Secure クライアントまたは Juniper Networks クライアントのネットワーク フィルター ドライバーが問題の原因である可能性があるため、これらのクライアントがインストールされているかどうかを確認してください。Check to see if you have the Pulse secure client or Juniper networks client installed, as their network filter drivers may cause the problem. 通常、サード パーティのネットワーク フィルター ドライバーをアンインストールすると、問題が解決されます。Uninstalling third-party network filter drivers typically fixes the issue. このほか、/DisableRIO オプションを指定してエミュレーターを起動する方法もあります。このオプションを使うと、エミュレーターのネットワーク通信が通常の Winsock に切り替わります。Alternatively, start the emulator with /DisableRIO, which will switch the emulator network communication to regular Winsock.

  • エミュレーターの実行中に、ご利用のコンピューターがスリープ モードになった場合や、そのコンピューターで OS を更新した場合、"サービスは現在使用できません" というメッセージが表示される可能性があります。While the emulator is running, if your computer goes to sleep mode or runs any OS updates, you might see a Service is currently unavailable message. Windows 通知トレイに表示されているアイコンを右クリックし、 [Reset Data](データのリセット) を選択して、エミュレーターのデータをリセットします。Reset the emulator's data, by right-clicking on the icon that appears on the windows notification tray and select Reset Data.

トレース ファイルの収集Collect trace files

デバッグ トレースを収集するには、管理コマンド プロンプトから次のコマンドを実行します。To collect debugging traces, run the following commands from an administrative command prompt:

  1. cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
  2. CosmosDB.Emulator.exe /shutdownCosmosDB.Emulator.exe /shutdown. プログラムがシャットダウンしたことをシステム トレイで確認します。シャットダウンに 1 分かかる場合があります。Watch the system tray to make sure the program has shut down, it may take a minute. Azure Cosmos Emulator のユーザー インターフェイスで [終了] をクリックするだけでもかまいません。You can also just click Exit in the Azure Cosmos Emulator user interface.
  3. CosmosDB.Emulator.exe /starttraces
  4. CosmosDB.Emulator.exe
  5. 問題を再現します。Reproduce the problem. データ エクスプローラーが動作していない場合は、エラーを捕捉するために、ブラウザーが開くまで数秒間待つだけです。If Data Explorer is not working, you only need to wait for the browser to open for a few seconds to catch the error.
  6. CosmosDB.Emulator.exe /stoptraces
  7. %ProgramFiles%\Azure Cosmos DB Emulator に移動し、docdbemulator_000001.etl ファイルを見つけます。Navigate to %ProgramFiles%\Azure Cosmos DB Emulator and find the docdbemulator_000001.etl file.
  8. デバッグのために、再現手順と共に .etl ファイルを askcosmosdb@microsoft.com に送付します。Send the .etl file along with repro steps to askcosmosdb@microsoft.com for debugging.

ローカル エミュレーターのアンインストールUninstall the local emulator

  1. システム トレイの Azure Cosmos Emulator アイコンを右クリックし、[終了] をクリックして、開いているローカル エミュレーターのインスタンスをすべて終了します。Exit all open instances of the local emulator by right-clicking the Azure Cosmos Emulator icon on the system tray, and then clicking Exit. すべてのインスタンスが終了するまでしばらく時間がかかる場合があります。It may take a minute for all instances to exit.
  2. Windows 検索ボックスに「アプリと機能」と入力し、アプリと機能 (システム設定) の検索結果をクリックします。In the Windows search box, type Apps & features and click on the Apps & features (System settings) result.
  3. アプリの一覧で、Azure Cosmos DB Emulator までスクロールして選択し、 [アンインストール] をクリックし、確認して再度、 [アンインストール] をクリックします。In the list of apps, scroll to Azure Cosmos DB Emulator, select it, click Uninstall, then confirm and click Uninstall again.
  4. アプリがアンインストールされたら、%LOCALAPPDATA%\CosmosDBEmulator に移動して、フォルダーを削除します。When the app is uninstalled, navigate to %LOCALAPPDATA%\CosmosDBEmulator and delete the folder.

次の手順Next steps

このチュートリアルでは、無料のローカル開発のためにローカル エミュレーターを使用する方法について学習しました。In this tutorial, you've learned how to use the local emulator for free local development. これで次のチュートリアルに進み、エミュレーター SSL 証明書をエクスポートする方法について学習できます。You can now proceed to the next tutorial and learn how to export emulator SSL certificates.