使用 Cloud Firestore REST API

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

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

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

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

身份验证和授权

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

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

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

使用 Firebase ID 令牌

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

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

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

使用 Google Identity OAuth 2.0 令牌

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

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

  • 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 令牌后，请将其作为一个 Authorization 标头（设置为 Bearer {YOUR_TOKEN}）传递给 Cloud Firestore 端点。

进行 REST 调用

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

如需创建指向项目 YOUR_PROJECT_ID 下的集合 cities 中 ID 为 LA 的文档的路径，您可以使用以下结构。

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

如需与此路径进行互动，请将其与 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

对文档执行增删改查操作，这与添加数据或获取数据指南中概述的方法类似。

v1.projects.databases.collectionGroups.indexes

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

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

错误代码

当 Cloud Firestore 请求成功时，Cloud Firestore API 将返回 HTTP 200 OK 状态代码以及请求的数据。当请求失败时，Cloud Firestore API 将返回 HTTP 4xx 或 5xx 状态代码以及包含错误相关信息的响应。

下表列出了针对每个错误代码的建议操作。这些代码适用于 Cloud Firestore REST 和 RPC API。Cloud Firestore SDK 和客户端库可能不会返回这些错误代码。

标准错误代码 说明 建议执行的操作
ABORTED 该请求与另一请求冲突。 对于非事务性提交：
重试该请求或重新设计数据模型结构以减少争用。

对于事务中的请求：
重试整个事务或重新设计数据模型结构以减少争用。
ALREADY_EXISTS 该请求尝试创建的文档已存在。 在解决问题之前，请勿重试。
DEADLINE_EXCEEDED 处理请求的 Cloud Firestore 服务器超时。 依照指数退避算法重试。
FAILED_PRECONDITION 请求不满足其中某个前提条件。例如，查询请求可能需要尚未定义的索引。请查看错误响应中的消息字段，了解未满足的前提条件。 在解决问题之前，请勿重试。
INTERNAL Cloud Firestore 服务器返回一个错误。 不要多次重试此请求。
INVALID_ARGUMENT 请求参数包含无效值。请参阅错误响应中的消息字段，了解无效值。 在解决问题之前，请勿重试。
NOT_FOUND 该请求尝试更新的文档不存在。 在解决问题之前，请勿重试。
PERMISSION_DENIED 该用户无权发出此请求。 在解决问题之前，请勿重试。
RESOURCE_EXHAUSTED 项目超出其配额或区域/多区域容量。 确认您没有超出项目配额。如果您超出了项目配额，则必须解决问题再重试。

否则，请依照指数退避算法重试。
UNAUTHENTICATED 请求不包含有效的身份验证凭据。 在解决问题之前，请勿重试。
UNAVAILABLE Cloud Firestore 服务器返回一个错误。 依照指数退避算法重试。