Хотя самый простой способ использовать 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 с помощью REST API Firebase Authentication .
- Получите токен Firebase ID пользователя из Firebase Authentication SDK .
Получив токен 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 вернул ошибку. | Повторите попытку, используя экспоненциальную отсрочку. |