Используйте 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 с помощью 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 могут не возвращать эти коды ошибок.