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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете создать токен доступа, используя учетную запись службы с клиентской библиотекой API Google или выполнив действия, описанные в разделе Использование 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 и ответ с информацией об ошибке.

В следующей таблице перечислены рекомендуемые действия для каждого кода ошибки. Эти коды применяются к API-интерфейсам REST и RPC 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 вернул ошибку. Повторите попытку, используя экспоненциальную отсрочку.