Используйте Cloud Firestore REST API

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

REST API может быть полезен в следующих случаях:

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

Если вы используете язык, поддерживаемый gRPC, рекомендуем выбрать RPC API, а не REST API.

Аутентификация и авторизация

Для аутентификации REST API Cloud Firestore принимает токен идентификатора Firebase Authentication или токен Google Identity OAuth 2.0. От токена зависит авторизация запроса:

  • Используйте токены идентификации Firebase для аутентификации запросов от пользователей приложения. Для таких запросов Cloud Firestore использует Cloud Firestore Security Rules, чтобы определить, авторизован ли запрос.

  • Используйте токен OAuth 2.0 Google Identity и сервисный аккаунт для аутентификации запросов из вашего приложения, например запросов на администрирование базы данных. Для таких запросов Cloud Firestore использует Identity and Access Management (IAM), чтобы определить, авторизован ли запрос.

Работа с токенами Firebase ID

Получить токен Firebase ID можно двумя способами:

Получив токен идентификатора Firebase пользователя, вы можете отправлять запросы от его имени.

Для запросов, аутентифицированных с помощью токена Firebase ID, и для неаутентифицированных запросов Cloud Firestore использует Cloud Firestore Security Rules, чтобы определить, авторизован ли запрос.

Работа с токенами OAuth 2.0 в Google Identity

Вы можете сгенерировать токен доступа, используя сервисный аккаунт с клиентской библиотекой API Google или следуя инструкциям в статье Использование OAuth 2.0 для серверных приложений. Вы также можете сгенерировать токен с помощью инструмента командной строки gcloud и команды gcloud auth application-default print-access-token.

Чтобы отправлять запросы к REST API Cloud Firestore, у токена должна быть следующая область действия:

  • https://www.googleapis.com/auth/datastore

Если вы выполняете аутентификацию запросов с помощью сервисного аккаунта и токена OAuth 2.0 Google Identity, Cloud Firestore предполагает, что запросы выполняются от имени приложения, а не отдельного пользователя. Cloud Firestore позволяет таким запросам игнорировать правила безопасности. Вместо этого Cloud Firestore использует IAM, чтобы определить, авторизован ли запрос.

Вы можете управлять разрешениями на доступ сервисных аккаунтов, назначая роли IAM Cloud Firestore.

Аутентификация с помощью токена доступа

Получив токен Firebase ID или токен Google Identity OAuth 2.0, передайте его конечным точкам Cloud Firestore в заголовке Authorization, заданном как Bearer {YOUR_TOKEN}.

Как выполнять вызовы REST

Все конечные точки REST API находятся по базовому URL https://firestore.googleapis.com/v1/.

Чтобы создать путь к документу с идентификатором LA в коллекции cities в проекте YOUR_PROJECT_ID, используйте следующую структуру:

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Чтобы взаимодействовать с этим путем, объедините его с базовым URL API.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Лучший способ начать экспериментировать с REST API – использовать API Explorer, который автоматически генерирует токены Google Identity OAuth 2.0 и позволяет изучить API.

Методы

Ниже приведены краткие описания двух наиболее важных групп методов. Полный список приведен в справочнике по REST API. Также вы можете воспользоваться API Explorer.

v1.projects.databases.documents

Выполняйте операции CRUD с документами, аналогичные описанным в руководствах по добавлению и получению данных.

v1.projects.databases.collectionGroups.indexes

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

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

Коды ошибок

Если запрос Cloud Firestore выполнен успешно, Cloud Firestore API возвращает код статуса HTTP 200 OK и запрошенные данные. Если запрос не удается выполнить, Cloud Firestore API возвращает код статуса HTTP 4xx или 5xx и ответ с информацией об ошибке.

В таблице ниже перечислены рекомендуемые действия для каждого кода ошибки. Эти коды применяются к REST и RPC API Cloud Firestore. SDK и клиентские библиотеки Cloud Firestore могут не возвращать эти коды ошибок.

Канонический код ошибки Описание Рекомендуемое действие
ABORTED Запрос конфликтует с другим запросом. Для фиксации без транзакции:
Повторите запрос или измените структуру модели данных, чтобы уменьшить конкуренцию.

Для запросов в транзакции:
Повторите всю транзакцию или измените структуру модели данных, чтобы уменьшить конкуренцию.
ALREADY_EXISTS Запрос пытался создать документ, который уже существует. Прежде чем повторить попытку, устраните проблему.
DEADLINE_EXCEEDED Сервер Cloud Firestore, обрабатывающий запрос, превысил срок. Повторите попытку, используя экспоненциальную выдержку.
FAILED_PRECONDITION Запрос не соответствует одному из предварительных условий. Например, для запроса может потребоваться индекс, который ещё не определен. Чтобы узнать, какое условие не выполнено, посмотрите поле message в ответе об ошибке. Прежде чем повторить попытку, устраните проблему.
INTERNAL Сервер Cloud Firestore вернул ошибку. Не повторяйте этот запрос более одного раза.
INVALID_ARGUMENT Параметр запроса содержит недопустимое значение. Недопустимое значение указано в поле сообщения в ответе об ошибке. Прежде чем повторить попытку, устраните проблему.
NOT_FOUND Запрос пытался обновить несуществующий документ. Прежде чем повторить попытку, устраните проблему.
PERMISSION_DENIED У пользователя нет прав для выполнения этого запроса. Прежде чем повторить попытку, устраните проблему.
RESOURCE_EXHAUSTED Проект превысил квоту или емкость региона/мультирегиона. Убедитесь, что вы не превысили квоту проекта. Если вы превысили квоту проекта, не повторяйте попытку, не устранив проблему.

В противном случае повторите попытку с экспоненциальной выдержкой.
UNAUTHENTICATED В запросе не указаны действительные учетные данные для аутентификации. Прежде чем повторить попытку, устраните проблему.
UNAVAILABLE Сервер Cloud Firestore вернул ошибку. Повторите попытку, используя экспоненциальную выдержку.