Подключите свое приложение к эмулятору Cloud Firestore.

Прежде чем подключать приложение к эмулятору Cloud Firestore, убедитесь, что вы понимаете общий рабочий процесс Firebase Local Emulator Suite, установили и настроили Local Emulator Suite и изучили команды CLI.

Выберите проект Firebase

Firebase Local Emulator Suite эмулирует продукты для одного проекта Firebase.

Чтобы выбрать проект, перед запуском эмуляторов выполните в CLI команду firebase use в рабочем каталоге. или передавать флаг --project каждой команде эмулятора.

Local Emulator Suite поддерживает эмуляцию реальных и демонстрационных проектов Firebase.

Тип проекта Функции Использование с эмуляторами
Реал

Реальный проект Firebase – это проект, который вы создали и настроили (скорее всего, в консоли Firebase).

В реальных проектах есть активные ресурсы, такие как экземпляры баз данных, сегменты хранилища, функции и другие ресурсы, настроенные для этого проекта Firebase.

При работе с реальными проектами Firebase вы можете запускать эмуляторы для любого или всех поддерживаемых продуктов.

Для всех продуктов, которые вы не эмулируете, ваши приложения и код будут взаимодействовать с активным ресурсом (экземпляром базы данных, сегментом хранилища, функцией и т. д.).

Демонстрация

В демонстрационном проекте Firebase нет реальной конфигурации Firebase и активных ресурсов. Доступ к таким проектам обычно предоставляется через практические работы или другие учебные материалы.

Идентификаторы демопроектов имеют префикс demo-.

При работе с демонстрационными проектами Firebase ваши приложения и код взаимодействуют только с эмуляторами. Если приложение попытается взаимодействовать с ресурсом, для которого не запущен эмулятор, код не сработает.

Рекомендуем по возможности использовать демопроекты. Преимущества подписки на Google One включают:

  • Простая настройка, поскольку вы можете запускать эмуляторы, не создавая проект Firebase.
  • Повышенная безопасность. Если ваш код случайно вызовет неэмулированные (рабочие) ресурсы, данные не будут изменены, а плата за использование не будет взиматься.
  • Улучшенная поддержка офлайн-режима, поскольку для скачивания конфигурации SDK не требуется доступ к интернету.

Как настроить приложение для взаимодействия с эмуляторами

При запуске эмулятор Cloud Firestore создает базу данных по умолчанию и именованную базу данных для каждой конфигурации firestore в файле firebase.json.

Именованные базы данных также создаются неявно в ответ на любые вызовы SDK или REST API к эмулятору, которые ссылаются на определенную базу данных. Такие базы данных работают с открытыми правилами.

Чтобы работать с базами данных по умолчанию и именованными базами данных в Emulator Suite UI, в адресной строке браузера измените URL, выбрав нужную базу данных.

  • Например, чтобы просмотреть данные в экземпляре по умолчанию, измените URL на следующий: localhost:4000/firestore/default/data
  • Чтобы просматривать контент в экземпляре ecommerce, обновите приложение до версии localhost:4000/firestore/ecommerce/data.

Как запустить эмулятор в определенной версии

Эмулятор запустится в версии, указанной в разделе firestore.edition файла firebase.json. Вы также можете указать издание в разделе emulators.firestore.edition файла firebase.json. Допустимые значения: standard и enterprise. Если вы укажете edition в обеих конфигурациях, приоритет будет у emulators.firestore.edition.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

SDK для Android, платформ Apple и веб-приложений

Настройте конфигурацию в приложении или тестовые классы для взаимодействия с Cloud Firestore, как описано ниже. Обратите внимание, что в приведенных ниже примерах код приложения подключается к базе данных проекта по умолчанию. Примеры, в которых используются дополнительные базы данных Cloud Firestore, помимо базы данных по умолчанию, приведены в руководстве по работе с несколькими базами данных.

Kotlin
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
Unity
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

Web

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);

Web

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}

Для тестирования функций Cloud Functions, активируемых событиями Firestore, с помощью эмулятора дополнительная настройка не требуется. Когда эмуляторы Firestore и Cloud Functions запущены, они автоматически работают вместе.

Admin SDK сек.

Firebase Admin SDK автоматически подключаются к эмулятору Cloud Firestore, если задана переменная среды FIRESTORE_EMULATOR_HOST:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Если ваш код выполняется в эмуляторе Cloud Functions, идентификатор проекта и другие параметры конфигурации задаются автоматически при вызове initializeApp.

Если вы хотите, чтобы код Admin SDK подключался к общему эмулятору, работающему в другой среде, укажите тот же идентификатор проекта, который вы задали с помощью интерфейса командной строки Firebase. Вы можете передать идентификатор проекта напрямую в initializeApp или задать переменную среды GCLOUD_PROJECT.

Node.js Admin SDK
admin.initializeApp({ projectId: "your-project-id" });
Переменная среды
export GCLOUD_PROJECT="your-project-id"

Cloud Firestore REST API

Эмулятор Cloud Firestore предоставляет конечную точку REST для взаимодействия с вашей базой данных. Все вызовы REST API должны направляться к конечной точке http://localhost:8080/v1.

Полный путь для вызова REST выглядит следующим образом:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

Например, чтобы получить список всех документов в коллекции users для проекта my-project-id, можно использовать curl:

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

Очищайте базу данных между тестами

В рабочей версии Firestore нет метода SDK платформы для очистки базы данных, но эмулятор Firestore предоставляет конечную точку REST специально для этой цели, которую можно вызвать из шага настройки/tearDown тестовой среды, из тестового класса или из оболочки (например, с помощью curl) перед запуском теста. Вы можете использовать этот подход в качестве альтернативы простому завершению процесса эмулятора.

В подходящем методе выполните операцию HTTP DELETE, указав идентификатор проекта Firebase, например firestore-emulator-example, для следующей конечной точки:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Естественно, ваш код должен ожидать подтверждения REST о том, что очистка завершена или не удалась.

Вы можете выполнить эту операцию из оболочки:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Реализовав такой шаг, вы можете упорядочить тесты и запускать функции, будучи уверенными, что старые данные будут удалены между запусками и вы используете новую базовую конфигурацию теста.

Как импортировать и экспортировать данные

Эмуляторы базы данных и Cloud Storage for Firebase позволяют экспортировать данные из запущенного экземпляра эмулятора. Определите базовый набор данных для использования в модульном тестировании или рабочих процессах непрерывной интеграции, а затем экспортируйте его, чтобы поделиться им с командой.

firebase emulators:export ./dir

В тестах при запуске эмулятора импортируйте базовые данные.

firebase emulators:start --import=./dir

Вы можете настроить эмулятор так, чтобы он экспортировал данные при завершении работы. Для этого укажите путь экспорта или просто используйте путь, переданный флагу --import.

firebase emulators:start --import=./dir --export-on-exit

Эти параметры импорта и экспорта данных также работают с командой firebase emulators:exec. Дополнительную информацию можно найти в справочнике по командам эмулятора.

Визуализация активности правил безопасности

Работая над прототипом и циклами тестирования, вы можете использовать инструменты визуализации и отчёты, предоставляемые Local Emulator Suite.

Как использовать мониторинг запросов

Эмулятор Cloud Firestore позволяет визуализировать запросы клиентов в Emulator Suite UI, включая отслеживание оценки для Firebase Security Rules.

Откройте вкладку Firestore > Requests (Firestore > Запросы), чтобы посмотреть подробную последовательность оценки для каждого запроса.

Монитор запросов эмулятора Firestore, показывающий оценки правил безопасности

Как визуализировать отчеты об оценке правил

Добавляя правила безопасности в прототип, вы можете отлаживать их с помощью инструментов отладки Local Emulator Suite.

После выполнения набора тестов вы можете получить доступ к отчетам о покрытии тестами, в которых показано, как оценивалось каждое из ваших правил безопасности.

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

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

Правила будут разбиты на выражения и подвыражения. Наведите на них указатель мыши, чтобы увидеть дополнительную информацию, в том числе количество вычислений и возвращенные значения. Чтобы получить необработанные данные в формате JSON, добавьте в запрос следующий URL:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

В HTML-версии отчета выделены вычисления, которые приводят к ошибкам неопределенного и нулевого значения:

Чем эмулятор Cloud Firestore отличается от рабочей среды

Эмулятор Cloud Firestore пытается точно воспроизвести поведение рабочего сервиса с некоторыми заметными ограничениями.

Поддержка нескольких баз данных для Cloud Firestore

В настоящее время Emulator Suite UI поддерживает интерактивное создание, редактирование, удаление, мониторинг запросов и визуализацию безопасности для базы данных по умолчанию, но не для дополнительных именованных баз данных.

Однако сам эмулятор создает именованную базу данных на основе конфигурации в файле firebase.json и неявно в ответ на вызовы SDK или REST API.

Транзакции

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

Индексы

Эмулятор не отслеживает составные индексы и выполняет любые допустимые запросы. Протестируйте приложение на реальном экземпляре Cloud Firestore, чтобы определить, какие индексы вам понадобятся.

Ограничения

Эмулятор не применяет все ограничения, применяемые в рабочей среде. Например, эмулятор может разрешать транзакции, которые будут отклонены как слишком большие в рабочей среде. Ознакомьтесь с ограничениями и разработайте приложение так, чтобы не превышать их.

Что дальше?