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

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

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

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

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

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

Для аутентификации REST API Cloud Firestore принимает либо токен Firebase Authentication ID, либо токен Google Identity OAuth 2.0 . Предоставленный токен влияет на авторизацию вашего запроса:

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

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

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

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

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

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

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

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

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

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

Если вы аутентифицируете свои запросы с помощью учётной записи сервиса и токена Google Identity OAuth 2.0, 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 API Cloud Firestore возвращает код статуса HTTP 200 OK и запрошенные данные. При неудачном выполнении запроса API Cloud Firestore возвращает код статуса HTTP 4xx или 5xx и ответ с информацией об ошибке.

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

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

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

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