Используйте 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 использует систему управления идентификацией и доступом (IAM) для определения того, авторизован ли запрос.

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

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

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

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

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

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

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

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