Использование эмулятора Azure Cosmos для разработки и тестирования в локальной средеUse the Azure Cosmos Emulator for local development and testing

Эмулятор Azure Cosmos предоставляет локальную среду для разработки, которая эмулирует службу Azure Cosmos DB.The Azure Cosmos Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. С помощью эмулятора Azure Cosmos вы можете локально разрабатывать и тестировать приложения, не создавая подписку 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 работает надлежащим образом, вы можете перейти на использование учетной записи 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 можно использовать с учетными записями SQL, Cassandra, MongoDB, Gremlin и API таблиц.You can develop using Azure Cosmos Emulator with SQL, Cassandra, MongoDB, Gremlin, and Table API accounts. Но сейчас представление обозревателя данных в эмуляторе полностью поддерживает только клиенты для API SQL.However at this time the Data Explorer view in the emulator fully supports clients for SQL API only.

Как работает эмуляторHow the emulator works

Эмулятор Azure Cosmos обеспечивает высокоточную эмуляцию службы 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 можно разрабатывать и тестировать приложения. Чтобы развернуть эти приложения в глобальной среде Azure, нужно изменить всего один параметр конфигурации для конечной точки подключения к Azure Cosmos DB.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 для подключений.For example, the emulator uses standard OS components such as the local file system for persistence, and the HTTPS protocol stack for connectivity. Это значит, что в режиме эмулятора не применимы некоторые возможности инфраструктуры Azure, включая глобальную репликацию, задержку менее 10 миллисекунд для операций чтения и записи или настраиваемые уровни согласованности.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 и службой Azure Cosmos DB с помощью средства миграции данных 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 для контейнера Docker в Windows. Команда docker pull описана в Центре Docker, а исходный код эмулятора размещен в репозитории GitHub для Dockerfile вместе с дополнительными сведениями.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 DB предоставляет эмулированную среду, которая выполняется на локальном компьютере разработчика. Поэтому есть некоторые различия между доступными возможностями в эмуляторе и облачной учетной записи Azure Cosmos DB.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:

  • Сейчас обозреватель данных в эмуляторе поддерживает только клиенты для API SQL.Currently Data Explorer in the emulator supports clients for SQL API. Представление обозревателя данных и операции для таких API Azure Cosmos DB, как MongoDB, таблиц, Graph и Cassandra, поддерживаются не полностью.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 поддерживает только одну предопределенную учетную запись и известный главный ключ.The Azure Cosmos Emulator supports only a single fixed account and a well-known master key. Повторное создание ключа в эмуляторе Azure Cosmos невозможно, но вы можете изменить ключ по умолчанию с помощью параметра командной строки.Key regeneration is not possible in the Azure Cosmos Emulator, however the default key can be changed using the command-line option.
  • Эмулятор Azure Cosmos не поддерживает масштабирование и не может работать с большим числом контейнеров.The Azure Cosmos Emulator is not a scalable service and will not support a large number of containers.
  • Эмулятор Azure Cosmos не поддерживает разные уровни согласованности Azure Cosmos DB.The Azure Cosmos Emulator does not offer different Azure Cosmos DB consistency levels.
  • Эмулятор Azure Cosmos не поддерживает репликацию между несколькими регионами.The Azure Cosmos Emulator does not offer multi-region replication.
  • Локальная версия эмулятора Azure Cosmos может не всегда отражать свежие изменения в службе Azure Cosmos DB. Поэтому, чтобы точно оценить необходимую пропускную способность для приложения (в единицах запроса), используйте планировщик ресурсов Azure Cosmos DB.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, по умолчанию можно создать до 25 контейнеров фиксированного размера (только пакеты SDK для Azure Cosmos DB) или 5 контейнеров неограниченного размера (эмулятор Azure Cosmos).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. Дополнительные сведения об изменении этого значения см. в разделе Изменение количества коллекций.For more information about changing this value, see Setting the PartitionCount value.

Требования к системеSystem requirements

Эмулятор Azure Cosmos имеет следующие требования к оборудованию и программному обеспечению.The Azure Cosmos Emulator has the following hardware and software requirements:

  • Требования к программному обеспечениюSoftware requirements
    • Windows Server 2012 R2, Windows Server 2016 или Windows 10.Windows Server 2012 R2, Windows Server 2016, or Windows 10
    • 64-разрядная операционная система.64-bit operating system
  • Минимальные требования к оборудованиюMinimum Hardware requirements
    • 2 ГБ ОЗУ2-GB RAM
    • 10 ГБ свободного дискового пространства10-GB available hard disk space

УстановкаInstallation

Эмулятор Azure Cosmos можно скачать и установить из Центра загрузки Майкрософт. Вы также можете запустить эмулятор в Docker для 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 для Windows см. в статье Использование эмулятора Azure Cosmos DB для разработки и тестирования в локальной среде.For instructions on using the emulator on Docker for Windows, see Running on Docker.

Примечание

Чтобы установить, настроить и запустить эмулятор Azure Cosmos, нужны права администратора на локальном компьютере.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.

Запуск в WindowsRunning on Windows

Чтобы запустить эмулятор Azure Cosmos, нажмите кнопку "Пуск" или клавишу Windows.To start the Azure Cosmos Emulator, select the Start button or press the Windows key. Начните вводить текст эмулятор Azure Cosmos и выберите эмулятор в списке приложений.Begin typing Azure Cosmos Emulator, and select the emulator from the list of applications.

Нажмите кнопку "Пуск" или клавишу Windows, начните вводить эмулятор Azure Cosmos и выберите эмулятор в списке приложений

При запуске эмулятора в области уведомлений панели задач Windows появится соответствующий значок.When the emulator is running, you'll see an icon in the Windows taskbar notification area. Уведомление локального эмулятора Azure Cosmos DB на панели задач

Эмулятор Azure Cosmos по умолчанию выполняется на локальном компьютере (localhost) и прослушивает порт 8081.The Azure Cosmos Emulator by default runs on the local machine ("localhost") listening on port 8081.

Эмулятор Azure Cosmos по умолчанию устанавливается в каталог 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 автоматически откроет в браузере страницу обозревателя данных 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-адрес или запустить обозреватель из эмулятора Azure Cosmos, используя значок в области уведомлений Windows, как показано ниже.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 DB (папка %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, а не эмуляторе 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, в эмуляторе Azure Cosmos для каждого запроса должна выполняться аутентификация.As with Azure Cosmos DB in the cloud, every request that you make against the Azure Cosmos Emulator must be authenticated. Эмулятор Azure Cosmos поддерживает аутентификацию с помощью главного ключа, используя одну предопределенную учетную запись и известный ключ аутентификации.The Azure Cosmos Emulator supports a single fixed account and a well-known authentication key for master key authentication. В качестве учетных данных для эмулятора Azure Cosmos можно использовать только эту учетную запись и только этот ключ.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, предназначен для использования только с этим эмулятором.The master key supported by the Azure Cosmos Emulator is intended for use only with the emulator. Использовать рабочую учетную запись и ключ Azure Cosmos DB с эмулятором Azure Cosmos нельзя.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 поддерживает только безопасное подключение по протоколу 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

API SQLSQL API

Когда эмулятор Azure Cosmos будет запущен на локальном компьютере, вы сможете работать с ним с помощью любых поддерживаемых пакетов SDK для Azure Cosmos DB или REST API Azure Cosmos DB.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 также содержит встроенный обозреватель данных, который позволяет создавать коллекции для API SQL или API Cosmos DB для MongoDB, а также просматривать и редактировать элементы без необходимости писать код.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==");

API Azure Cosmos DB для MongoDBAzure Cosmos DB's API for MongoDB

Когда эмулятор Azure Cosmos будет запущен на локальном компьютере, вы сможете взаимодействовать с ним с помощью пакета SDK для API Azure Cosmos DB для MongoDB.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". Затем подключитесь к учетной записи API MongoDB, используя следующую строку подключения: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

API таблицTable API

Когда эмулятор Azure Cosmos будет запущен на локальном компьютере, вы сможете взаимодействовать с ним с помощью пакета SDK для API таблиц Azure Cosmos DB.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”. Затем выполните следующий код для подключения к учетной записи 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")));

API CassandraCassandra 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/CQLSHInstall 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
    

API GremlinGremlin 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.4Install 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 используют хранилище сертификатов Windows для безопасного подключения к локальному эмулятору Azure Cosmos DB..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.You can start it by running certlm.msc or follow the step by step instructions in Export the Azure Cosmos Emulator Certificates. Когда откроется диспетчер сертификатов, откройте в нем "Личные сертификаты", как показано ниже, и экспортируйте сертификат с понятным именем DocumentDBEmulatorCertificate в формате X.509 с кодировкой BASE-64 (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.

Сертификат SSL для эмулятора Azure Cosmos DB

Чтобы импортировать сертификат X.509 в хранилище сертификатов Java, выполните инструкции из статьи Добавление сертификата в хранилище сертификатов ЦС Java.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 смогут подключаться к эмулятору Azure Cosmos.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.

При подключении к эмулятору с помощью пакетов SDK для Python и Node.js проверка 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

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

Чтобы просмотреть список параметров, в командной строке введите Microsoft.Azure.Cosmos.Emulator.exe /? .To view the list of options, type Microsoft.Azure.Cosmos.Emulator.exe /? at the command prompt.

ПараметрOption ОписаниеDescription CommandCommand АргументыArguments
[Нет аргументов][No arguments] Запускает эмулятор Azure Cosmos с параметрами по умолчанию.Starts up the Azure Cosmos Emulator with default settings. Microsoft.Azure.Cosmos.Emulator.exeMicrosoft.Azure.Cosmos.Emulator.exe
[Help][Help] Отображает список поддерживаемых аргументов командной строки.Displays the list of supported command-line arguments. Microsoft.Azure.Cosmos.Emulator.exe /?Microsoft.Azure.Cosmos.Emulator.exe /?
GetStatusGetStatus Получает состояние эмулятора Azure Cosmos.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. Microsoft.Azure.Cosmos.Emulator.exe /GetStatusMicrosoft.Azure.Cosmos.Emulator.exe /GetStatus
ShutdownShutdown Завершает работу эмулятора Azure Cosmos.Shuts down the Azure Cosmos Emulator. Microsoft.Azure.Cosmos.Emulator.exe /ShutdownMicrosoft.Azure.Cosmos.Emulator.exe /Shutdown
DataPathDataPath Указывает путь для сохранения файлов данных.Specifies the path in which to store data files. По умолчанию имеет значение %LocalAppdata%\CosmosDBEmulator.Default value is %LocalAppdata%\CosmosDBEmulator. Microsoft.Azure.Cosmos.Emulator.exe /DataPath=<datapath>Microsoft.Azure.Cosmos.Emulator.exe /DataPath=<datapath> <datapath:> любой доступный путь.<datapath>: An accessible path
ПортPort Указывает номер порта, который должен использоваться эмулятором.Specifies the port number to use for the emulator. Значение по умолчанию — 8081.Default value is 8081. Microsoft.Azure.Cosmos.Emulator.exe /Port=<port>Microsoft.Azure.Cosmos.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.The default value is 8900. Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=<computeport>Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=<computeport> <computeport>: один номер порта.<computeport>: Single port number
EnableMongoDbEndpoint=3.2EnableMongoDbEndpoint=3.2 Включает API MongoDB 3.2Enables MongoDB API 3.2 Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2
EnableMongoDbEndpoint=3.6EnableMongoDbEndpoint=3.6 Включает API MongoDB 3.6Enables MongoDB API 3.6 Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6
MongoPortMongoPort Указывает номер порта для использования с интерфейсом совместимости с MongoDB.Specifies the port number to use for MongoDB compatibility API. Значение по умолчанию — 10255.Default value is 10255. Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=<mongoport>Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=<mongoport> <mongoport:> один номер порта.<mongoport>: Single port number
EnableCassandraEndpointEnableCassandraEndpoint Включает API CassandraEnables Cassandra API Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint
CassandraPortCassandraPort Указывает номер порта для конечной точки Cassandra.Specifies the port number to use for the Cassandra endpoint. Значение по умолчанию — 10350.Default value is 10350. Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=<cassandraport>Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=<cassandraport> <cassandraport>: один номер порта.<cassandraport>: Single port number
EnableGremlinEndpointEnableGremlinEndpoint Включает API GremlinEnables Gremlin API Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint
GremlinPortGremlinPort Номер порта для конечной точки Gremlin.Port number to use for the Gremlin Endpoint. Значение по умолчанию — 8901.Default value is 8901. Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=<port>Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=<port> <port:> один номер порта.<port>: Single port number
EnableTableEndpointEnableTableEndpoint Включает API таблиц AzureEnables Azure Table API Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint
TablePortTablePort Номер порта для конечной точки таблицы Azure.Port number to use for the Azure Table Endpoint. Значение по умолчанию — 8902.Default value is 8902. Microsoft.Azure.Cosmos.Emulator.exe /TablePort=<port>Microsoft.Azure.Cosmos.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 Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=<file_name>Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=<file_name> <file_name>: Путь к файлу.<file_name>: Path to the file
ResetDataPathResetDataPath Рекурсивно удаляет файлы по указанному пути.Recursively removes all the files in the specified path. Если путь не указан, используется путь по умолчанию %LOCALAPPDATA%\CosmosDbEmulatorIf you don't specify a path, it defaults to %LOCALAPPDATA%\CosmosDbEmulator Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath=<path>Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath=<path> <path>: Путь к файлу<path>: File path
StartTracesStartTraces Начинает сбор журналов трассировки для отладки с помощью LOGMAN.Start collecting debug trace logs using LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StartTracesMicrosoft.Azure.Cosmos.Emulator.exe /StartTraces
StopTracesStopTraces Завершает сбор журналов трассировки для отладки с помощью LOGMAN.Stop collecting debug trace logs using LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StopTracesMicrosoft.Azure.Cosmos.Emulator.exe /StopTraces
StartWprTracesStartWprTraces Начинает сбор журналов трассировки для отладки с помощью средства записи производительности Windows.Start collecting debug trace logs using Windows Performance Recording tool. Microsoft.Azure.Cosmos.Emulator.exe /StartWprTracesMicrosoft.Azure.Cosmos.Emulator.exe /StartWprTraces
StopWprTracesStopWprTraces Останавливает сбор журналов трассировки для отладки с помощью средства записи производительности Windows.Stop collecting debug trace logs using Windows Performance Recording tool. Microsoft.Azure.Cosmos.Emulator.exe /StopWprTracesMicrosoft.Azure.Cosmos.Emulator.exe /StopWprTraces
FailOnSslCertificateNameMismatchFailOnSslCertificateNameMismatch По умолчанию эмулятор повторно создает собственный самозаверяющий SSL-сертификат, если альтернативное имя субъекта этого сертификата не содержит одно из следующих значений: доменное имя узла, локальный адрес IPv4, localhost или 127.0.0.1.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. Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatchMicrosoft.Azure.Cosmos.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. Microsoft.Azure.Cosmos.Emulator.exe /GenCert=<dns-names>Microsoft.Azure.Cosmos.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. Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:<directports>Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:<directports> <directports:> разделенный запятыми список из 4 портов.<directports>: Comma-delimited list of 4 ports
КлавишиKey Ключ проверки подлинности для эмулятора.Authorization key for the emulator. Ключ должен иметь формат 64-разрядного вектора в кодировке Base-64.Key must be the base-64 encoding of a 64-byte vector. Microsoft.Azure.Cosmos.Emulator.exe /Key:<key>Microsoft.Azure.Cosmos.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. Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimitingMicrosoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting
DisableRateLimitingDisableRateLimiting Указывает, что ограничение частоты запросов отключено.Specifies that request rate limiting behavior is disabled. Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimitingMicrosoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting
NoUINoUI Скрывает пользовательский интерфейс эмулятора.Do not show the emulator user interface. Microsoft.Azure.Cosmos.Emulator.exe /NoUIMicrosoft.Azure.Cosmos.Emulator.exe /NoUI
NoExplorerNoExplorer Скрывает обозреватель данных при запуске.Don't show data explorer on startup. Microsoft.Azure.Cosmos.Emulator.exe /NoExplorerMicrosoft.Azure.Cosmos.Emulator.exe /NoExplorer
PartitionCountPartitionCount Указывает максимальное количество секционированных контейнеров.Specifies the maximum number of partitioned containers. Дополнительные сведения см. в разделе Изменение количества контейнеров.See Change the number of containers for more information. Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=<partitioncount>Microsoft.Azure.Cosmos.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. Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount>Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount> <defaultpartitioncount> Значение по умолчанию — 25.<defaultpartitioncount> Default value is 25.
AllowNetworkAccessAllowNetworkAccess Разрешает доступ к эмулятору по сети.Enables access to the emulator over a network. Для включения сетевого доступа нужно также передать один из параметров: /Key=<строка_ключа> или /KeyFile=<имя_файла>.You must also pass /Key=<key_string> or /KeyFile=<file_name> to enable network access. Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=<key_string> или Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=<key_string> or Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>
NoFirewallNoFirewall Не изменяйте правила брандмауэра при использовании /AllowNetworkAccess.Don't adjust firewall rules when /AllowNetworkAccess option is used. Microsoft.Azure.Cosmos.Emulator.exe /NoFirewallMicrosoft.Azure.Cosmos.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. Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=<путь к файлу ключа>Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=<path to key file>
СогласованностьConsistency Определяет уровень согласованности по умолчанию для учетной записи.Set the default consistency level for the account. Microsoft.Azure.Cosmos.Emulator.exe /Consistency=<consistency>Microsoft.Azure.Cosmos.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

По умолчанию можно создать до 25 контейнеров фиксированного размера (только пакеты SDK для Azure Cosmos DB) или 5 контейнеров неограниченного размера (эмулятор Azure Cosmos).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 контейнеров неограниченного размера либо любое их сочетание в пределах указанных ограничений (где один контейнер неограниченного размера приравнивается к 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. Дополнительное количество создаваемых ими операций ввода-вывода может привести к непредсказуемым превышениям времени ожидания при использовании 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."Sorry, we are currently experiencing high demand in this region, and cannot fulfill your request at this time. We work continuously to bring more and more capacity online, and encourage you to try again.We work continuously to bring more and more capacity online, and encourage you to try again. ActivityId: 12345678-1234-1234-1234-123456789abc. (К сожалению, сейчас в этом регионе отмечается высокий спрос, и мы не можем выполнить ваш запрос. Мы постоянно работаем над повышением доступной емкости и рекомендуем вам попробовать еще раз. Вы можете обратиться к нам на адрес askcosmosdb@microsoft.com в любое время и по любому поводу.)ActivityId: 12345678-1234-1234-1234-123456789abc"

Чтобы изменить количество доступных для эмулятора Azure Cosmos DB контейнеров, сделайте следующее.To change the number of containers available in the Azure Cosmos Emulator, run the following steps:

  1. Удалите все локальные данные эмулятора Azure Cosmos, щелкнув правой кнопкой мыши значок эмулятора Azure Cosmos DB в области уведомлений и выбрав Сброс данных.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 в области уведомлений и выбрав Выход.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.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> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.For example: C:\Program Files\Azure Cosmos DB Emulator> Microsoft.Azure.Cosmos.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"

Или поместите каталог PSModules в PSModulesPath и импортируйте его с помощью следующей команды: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.

Запуск в DockerRunning on Docker

Эмулятор Azure Cosmos может выполняться в Docker для Windows.The Azure Cosmos Emulator can be run on Docker for Windows. Этот эмулятор не работает в Docker для Oracle Linux.The emulator does not work on Docker for Oracle Linux.

Установив Docker для Windows, переключитесь на контейнеры Windows. Для этого на панели инструментов щелкните правой кнопкой мыши значок Docker и выберите Switch to Windows containers (Переключиться на контейнеры 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-сертификат, выполните следующие действия из командной строки с правами администратора.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

Если клиентское приложение .NET выполняется в контейнере docker для Linux и вы используете эмулятор Azure Cosmos на хост-компьютере, выполнить подключение к учетной записи 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.

В качестве обходного решения можно отключить проверку SSL-сертификата сервера в клиентском приложении, передав экземпляр HttpClientHandler, как показано в следующем примере кода .NET.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. Это решение применимо только при использовании пакета Nuget Microsoft.Azure.DocumentDB, но не поддерживается для пакета Nuget Microsoft.Azure.Cosmos.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 и чтобы конечная точка эмулятора была доступна с IP-адреса узла, а не DNS host.docker.internal.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 или LinuxRunning 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 выполните приведенную ниже команду и запишите адрес IPv4.Within the Windows VM run the command below and make note of the IPv4 address.

ipconfig.exe

В вашем приложении нужно изменить URI для объекта DocumentClient, чтобы использовать адрес IPv4, возвращаемый ipconfig.exe.Within your application you need to change the URI for the DocumentClient object to use the IPv4 address returned by ipconfig.exe. Далее необходимо обойти проверку центра сертификации при создании объекта DocumentClient.The next step is to work around the CA validation when constructing the DocumentClient object. Для этого вам нужно будет предоставить HttpClientHandler для конструктора DocumentClient, который имеет собственную реализацию ServerCertificateCustomValidationCallback.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 запустите эмулятор 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.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 в области уведомлений и выбрав "Сбросить данные".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 DB соберите файлы резервной копии из папки %LOCALAPPDATA%\CrashDumps, сожмите их и создайте запрос в службу поддержки на портале Azure.If the Azure Cosmos Emulator crashes, collect dump files from '%LOCALAPPDATA%\CrashDumps' folder, compress them, and open a support ticket from the Azure portal.

  • Если в 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
    
  • Если возникли проблемы с подключением, соберите файлы трассировки, сожмите их и создайте запрос в службу поддержки на портале Azure.If you encounter a connectivity issue, collect trace files, compress them, and open a support ticket in the Azure portal.

  • При получении сообщения Служба недоступна эмулятор может не инициализировать сетевой стек.If you receive a Service Unavailable message, the emulator might be failing to initialize the network stack. Проверьте, установлен ли защищенный клиент Pulse или сетевой клиент Juniper, так как драйверы их сетевого фильтра могут вызвать проблему.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.

  • Если во время работы эмулятора компьютер переходит в ждущий режим или запускает какие-либо обновления операционной системы, может появиться сообщение Service is currently unavailable (Служба сейчас недоступна).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 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. Microsoft.Azure.Cosmos.Emulator.exe /shutdown.Microsoft.Azure.Cosmos.Emulator.exe /shutdown. Проверьте область уведомлений, чтобы убедиться, что работа программы завершена, так как на это может потребоваться до минуты.Watch the system tray to make sure the program has shut down, it may take a minute. Кроме того, можно просто щелкнуть Выйти в пользовательском интерфейсе эмулятора Azure Cosmos.You can also just click Exit in the Azure Cosmos Emulator user interface.
  3. Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
  4. Microsoft.Azure.Cosmos.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. Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces
  7. Перейдите к %ProgramFiles%\Azure Cosmos DB Emulator и найдите файл docdbemulator_000001.etl.Navigate to %ProgramFiles%\Azure Cosmos DB Emulator and find the docdbemulator_000001.etl file.
  8. Создайте запрос в службу поддержки на портале Azure и добавьте ETL-файл вместе с действиями по воспроизведению.Open a support ticket in the Azure portal and include the .etl file along with repro steps.

Удаление локального эмулятораUninstall the local emulator

  1. Выйдите из всех открытых экземпляров локального эмулятора, щелкнув правой кнопкой мыши значок эмулятора Azure Cosmos в области уведомлений и выбрав "Выйти".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 Приложения и возможности и выберите команду Apps & features (System settings) (Приложения и возможности (системные параметры)).In the Windows search box, type Apps & features and click on the Apps & features (System settings) result.
  3. В списке приложений перейдите к эмулятору Azure Cosmos DB, выберите его, щелкните Удалить, подтвердите и щелкните Удалить еще раз.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.