使用 Cloud Firestore REST API

雖然使用 Cloud Firestore 最簡單的方法是使用其中一個原生用戶端程式庫，但在某些情況下，直接呼叫 REST API 會很有用。

REST API 適用於下列用途：

  • 從資源受限的環境 (例如物聯網 (IoT) 裝置) 存取 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 權杖後，請將其傳遞至 Cloud Firestore 端點，並將 Authorization 標頭設為 Bearer {YOUR_TOKEN}。

發出 REST 呼叫

所有 REST API 端點都位於基準網址 https://firestore.googleapis.com/v1/ 下。

如要建立文件路徑，且文件 ID 為 LA，位於專案 YOUR_PROJECT_ID 下的集合 cities 中，請使用下列結構。

/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

對文件執行 CRUD 作業，類似於新增資料或取得資料指南中概述的操作。

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 FirestoreSDK 和用戶端程式庫可能不會傳回這些錯誤代碼。

標準化錯誤代碼 說明 建議做法
ABORTED 要求與其他要求衝突。 非交易修訂版本：
重試要求或重新建構資料模型，減少爭用情形。

交易中的要求：
重試整個交易或重新建構資料模型，減少爭用情形。
ALREADY_EXISTS 要求嘗試建立的文件已存在。 未修正問題前請勿重試。
DEADLINE_EXCEEDED 處理要求的 Cloud Firestore 伺服器超過期限。 使用指數輪詢重試。
FAILED_PRECONDITION 要求不符合其中一項先決條件。舉例來說，查詢要求可能需要尚未定義的索引。請查看錯誤回應中的訊息欄位，瞭解失敗的前提條件。 未修正問題前請勿重試。
INTERNAL Cloud Firestore 伺服器傳回錯誤。 此項要求最多只能重試一次。
INVALID_ARGUMENT 要求參數包含無效值。請查看錯誤回應中的訊息欄位，瞭解無效值。 未修正問題前請勿重試。
NOT_FOUND 要求嘗試更新不存在的文件。 未修正問題前請勿重試。
PERMISSION_DENIED 使用者未獲授權，無法提出這項要求。 未修正問題前請勿重試。
RESOURCE_EXHAUSTED 專案超過配額或區域/多區域容量。 確認您未超出專案配額。如果超出專案配額，請先修正問題再重試。

否則，請使用指數輪詢重試。
UNAUTHENTICATED 要求不含有效的驗證憑證。 未修正問題前請勿重試。
UNAVAILABLE Cloud Firestore 伺服器傳回錯誤。 使用指數輪詢重試。