Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

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

Для аутентификации Cloud Firestore REST API принимает либо токен Firebase Authentication ID, либо токен 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 , чтобы определить, авторизован ли запрос.

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

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

После того, как вы получите токен 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 .

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