使用 Cloud Firestore REST API

虽然 Cloud Firestore 最简单的用法是使用某个原生客户端库,但在有些情况下,直接调用 REST API 会很有用。

REST API 在以下使用情形中会很有帮助:

  • 从资源受限的环境(如无法运行完整客户端库的物联网设备)访问 Cloud Firestore。
  • 自动执行数据库管理,或检索详细的数据库元数据。

如果您使用的是 gRPC 支持的编程语言,可考虑使用 RPC API,而不使用 REST API。

身份验证和授权

Cloud Firestore REST API 接受使用 Firebase 身份验证 ID 令牌或 Google Identity OAuth 2.0 令牌进行身份验证。您提供的令牌会影响您的请求的授权结果:

  • 使用 Firebase ID 令牌对来自您应用用户的请求进行身份验证。对于这些请求,Cloud Firestore 会使用 Cloud Firestore 安全规则来确定请求是否已获得授权。

  • 使用 Google Identity OAuth 2.0 令牌和服务帐号对来自您应用的请求(例如数据库管理请求)进行身份验证。对于这些请求,Cloud Firestore 使用 Cloud Identity and Access Management (IAM) 来确定请求是否已获得授权。

使用 Firebase ID 令牌

您可以通过两种方式获得 Firebase ID 令牌:

通过检索用户的 Firebase ID 令牌,您可以代表用户发出请求。

对于使用 Firebase ID 令牌进行身份验证的请求以及未经身份验证的请求,Cloud Firestore 会使用您的 Cloud Firestore 安全规则来确定请求是否已获得授权。

使用 Google Identity OAuth 2.0 令牌

您可以使用服务帐号通过 Google API 客户端库生成一个访问令牌,或者根据为“服务器到服务器”应用使用 OAuth 2.0 中说明的步骤来生成令牌。您还可以通过 gcloud 命令行工具使用 gcloud auth print-access-token 命令生成令牌。

此令牌必须具有以下范围才能向 Cloud Firestore REST API 发送请求:

  • https://www.googleapis.com/auth/datastore

如果您使用服务帐号和 Google Identity OAuth 2.0 令牌对您的请求进行身份验证,则 Cloud Firestore 会假定您的请求是代表您的应用(而非个人用户)执行操作。Cloud Firestore 将允许这些请求绕过您的安全规则,并改为使用 Cloud Identity and Access Management (IAM) 来确定请求是否已获得授权。

您可以通过分配 Cloud Firestore IAM 角色来控制服务帐号的访问权限。

使用访问令牌进行身份验证

获得 Firebase ID 令牌或 Google Identity OAuth 2.0 令牌后,请将其作为一个 Authorization 标头(设置为 Bearer {YOUR_TOKEN})传递给 Cloud Firestore 端点。

进行 REST 调用

所有 REST API 端点都存在于基准网址 https://firestore.googleapis.com/v1beta1/ 下面。

要在项目 YOUR_PROJECT_ID 下的集合 cities 中创建一个指向 ID 为 LA 的文档的路径,您可以使用以下结构。

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

要与此路径进行互动,请将其与 API 基准网址组合在一起。

https://firestore.googleapis.com/v1beta1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

要开始尝试使用 REST API,最好的方法是使用 API Explorer,它会自动生成 Google Identity OAuth 2.0 令牌,并允许您检查 API。

方法

下面将简要介绍两个最重要的方法组。如需完整列表,请参阅 REST API 参考或使用 API Explorer

v1beta1.projects.databases.documents

对文档执行 CRUD 操作,这与添加数据获取数据指南中列出的那些方法类似。

v1beta1.projects.databases.indexes

对索引执行操作,例如创建新索引、停用现有索引或列出所有当前索引。这适用于自动化数据结构迁移或在多个项目间同步索引。

此方法还可用于检索文档元数据,例如给定文档的所有字段和子集合的列表。

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面