Устранение неполадок эмулятора Azure Cosmos DB

  • Статья

Эмулятор Azure Cosmos DB предоставляет среду, которая эмулирует облачную службу для разработки. Используйте советы, приведенные в этой статье, чтобы устранить проблемы, которые могут возникнуть при установке или использовании эмулятора.

Контрольный список для устранения неполадок

Ниже приведен список распространенных действий по устранению неполадок, которые необходимо выполнить, если эмулятор Azure Cosmos DB не работает должным образом.

Сброс данных

Если вы установили новую версию эмулятора и у вас возникли ошибки, убедитесь, что вы сбросили данные. Чтобы сбросить данные, откройте контекстное меню эмулятора Azure Cosmos DB на панели задач и выберите Сбросить данные.

Если сброс данных не устраняет ошибки, вы можете:

  • Удалите эмулятор.
  • Удалите старые версии эмулятора (если они существуют).
  • Удалите папку %ProgramFiles%\Azure Cosmos DB Emulator .
  • Переустановите эмулятор.

Кроме того, если сброс данных не работает, перейдите в %LOCALAPPDATA%\CosmosDBEmulator расположение и удалите папку.

Просмотр поврежденных счетчиков производительности Windows

  • Если эмулятор Azure Cosmos DB перестает отвечать на запросы, соберите файлы дампа из %LOCALAPPDATA%\CrashDumps папки, сжать файлы, а затем откройте запрос в службу поддержки в портал Azure.

  • Если Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe перестает отвечать на запросы, этот сбой может указывать на повреждение счетчиков производительности. Чтобы проверка состояние счетчика, выполните следующую команду:

    lodctr /R

Диагностика проблем с подключением

  • Если возникла проблема с подключением, соберите файлы трассировки, сожмите файлы, а затем отправьте запрос в службу поддержки в портал Azure.

  • Если появляется сообщение "Служба недоступна", эмулятор может не инициализировать сетевой стек. Проверьте, установлен ли клиент Pulse Secure или Клиент Juniper Networks, так как их драйверы сетевых фильтров могут вызвать проблему. Вы также можете попробовать удалить другие драйверы сетевых фильтров, чтобы устранить проблему. Кроме того, запустите эмулятор, используя /DisableRIO для переключения сетевого взаимодействия эмулятора на обычный Winsock.

  • Если вы получаете сообщение об ошибке подключения, например "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...", это сообщение об ошибке может указывать на глобальные изменения в ОС (например, Insider Preview Build 20170) или изменения в параметрах браузера, которые в качестве протокола по умолчанию включает TLS 1.3. Аналогичное сообщение об ошибке, например "Microsoft.Azure.Documents.DocumentClientException: Запрос выполняется с запрещенным шифрованием в протоколе передачи или шифре. Проверка минимально допустимого параметра протокола SSL/TLS учетной записи", если вы используете пакет SDK для выполнения запроса к эмулятору Azure Cosmos DB. Эта ошибка также может возникнуть из-за того, что эмулятор Azure Cosmos DB поддерживает только протокол TLS 1.2. Рекомендуемое решение — установить TLS 1.2 в качестве значения по умолчанию.

    Например:

    1. В диспетчере IIS перейдите в раздел Сайты>Веб-сайты по умолчанию.

    2. Найдите привязки сайта для порта 8081 и измените их, чтобы отключить TLS 1.3. Вы также можете обновить параметры веб-браузера с помощью параметра Параметры .

      Примечание.

      Если компьютер переходит в спящий режим или запускает обновления ОС во время работы эмулятора, может появиться сообщение об ошибке "Служба сейчас недоступна".

    3. Чтобы сбросить данные эмулятора, щелкните правой кнопкой мыши значок, который отображается в области уведомлений Windows, а затем выберите Сбросить данные.

Сбор файлов трассировки

Чтобы собрать отладочные трассировки, выполните следующие команды от имени администратора в окне командной строки:

  1. Перейдите по пути, по которому установлен эмулятор:

    cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"

  2. Завершите работу эмулятора и watch системный лоток, чтобы убедиться, что программа отключена:

    Microsoft.Azure.Cosmos.Emulator.exe /shutdown

    Примечание.

    Завершение процесса может занять одну минуту. Вы также можете выбрать Выход в пользовательском интерфейсе эмулятора Azure Cosmos DB.

  3. Начните ведение журнала, выполнив следующую команду:

    Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces

  4. Запустите эмулятор:

    Microsoft.Azure.Cosmos.Emulator.exe

  5. Воспроизведите проблему. Если обозреватель данных не работает, необходимо подождать всего несколько секунд, пока браузер не сможет обнаружить ошибку.

  6. Остановить ведение журнала:

    Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

  7. Перейдите по %ProgramFiles%\Azure Cosmos DB Emulator пути и найдите файл docdbemulator_000001.etl .

  8. Откройте запрос в службу поддержки в портал Azure и добавьте ETL-файл вместе с любыми шагами, необходимыми для воспроизведения проблемы.

Установка сертификатов для клиентских приложений

Иногда может потребоваться взять экспортируемый сертификат эмулятора и использовать его с клиентским приложением. Точный процесс зависит от пакета SDK.

Экспорт сертификата TLS/SLL

Экспортируйте сертификат эмулятора, чтобы успешно использовать конечную точку эмулятора из языков и сред выполнения, которые не интегрируются с хранилищем сертификатов Windows. Вы можете экспортировать сертификат с помощью диспетчера сертификатов Windows или PowerShell после первого запуска эмулятора.

  1. Получите сертификат, используя понятное имя DocumentDbEmulatorCertificate , и сохраните сертификат в переменной оболочки с именем $cert.

    $cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}

  2. Используйте export-Certificate для экспорта сертификата во временный файл в домашней папке.

    $params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params

    Примечание.

    В Windows домашняя папка обычно C:\Users\[username]\используется при условии, что домашний диск — C:.

  3. Используйте certutil для преобразования сертификата в файл сертификата X.509 в кодировке Base-64 .

    certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer

  4. Удалите временный файл.

    Remove-Item $home/tmp-cert.cer

Импорт сертификата для приложений Java

При запуске приложений Java или приложений MongoDB, использующих клиент на основе Java, установить сертификат в хранилище сертификатов Java по умолчанию проще, чем передавать -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" параметры. Например, включенное демонстрационное приложение Java (https://localhost:8081/_explorer/index.html) зависит от хранилища сертификатов по умолчанию.

Следуйте инструкциям в разделе Создание, экспорт и импорт TLS/SSL-сертификатов, чтобы импортировать сертификат X.509 в хранилище сертификатов Java по умолчанию. Помните, что при запуске keytool вы работаете в каталоге %JAVA_HOME%. После импорта сертификата в хранилище сертификатов клиенты для SQL и API Azure Cosmos DB для MongoDB могут подключаться к эмулятору Azure Cosmos DB.

Кроме того, можно выполнить следующий bash скрипт для импорта сертификата:

#!/bin/bash

# If the emulator was started with /AllowNetworkAccess, replace the following with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
# Delete the cert if it already exists
sudo $JAVA_HOME/bin/keytool -cacerts -delete -alias cosmos_emulator
# Import the cert
sudo $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

CosmosDBEmulatorCertificate После установки TLS/SSL-сертификата приложение сможет подключаться к локальному эмулятору Azure Cosmos DB и использовать его.

Если у вас возникли проблемы, см . раздел Отладка подключений SSL/TLS. В большинстве случаев сертификат может не быть установлен в хранилище %JAVA_HOME%/jre/lib/security/cacerts . Например, если установлено несколько версий Java, приложение может использовать хранилище сертификатов, отличное от обновленной.

Импорт сертификата для приложений Python

При подключении к эмулятору из приложений Python проверка TLS отключается. По умолчанию пакет SDK Python для Azure Cosmos DB для NoSQL не пытается использовать TLS/SSL-сертификат при подключении к локальному эмулятору. Дополнительные сведения см. в статье Клиентская библиотека Azure Cosmos DB для NoSQL для Python.

Если вы хотите использовать проверку TLS, следуйте примерам, приведенным в статье Tls/SSL-оболочка для объектов сокетов.

Импорт сертификата для приложений Node.js

При подключении к эмулятору из пакетов SDK Node.js проверка TLS отключается. По умолчанию пакет SDK дляNode.js (версии 1.10.1 или более поздней) для API для NoSQL не пытается использовать TLS/SSL-сертификат при подключении к локальному эмулятору.

Если вы хотите использовать проверку TLS, следуйте примерам из документации поNode.js.

Смена сертификатов

Вы можете принудительно восстановить сертификаты эмулятора, открыв эмулятор с аргументом /ResetDataPath . Это действие удаляет все данные, хранящиеся локально в эмуляторе. Дополнительные сведения о аргументах командной строки см. в разделе Аргументы командной строки эмулятора Windows.

Совет

Кроме того, выберите Сброс данных в контекстном меню эмулятора Azure Cosmos DB на панели задач Windows.

Если вы установили сертификаты в хранилище сертификатов Java или использовали их в другом месте, их необходимо повторно добавить с помощью текущих сертификатов. Приложение не сможет подключиться к локальному эмулятору, пока не обновите сертификаты.