使用 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 身分 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 身分 OAuth 2.0 權杖驗證要求，Cloud Firestore 會假設您的要求是代表應用程式而非個別使用者執行。Cloud Firestore 允許這些要求忽略您的安全性規則。Cloud Firestore 會改用 IAM 來判斷要求是否獲得授權。

您可以指派 Cloud Firestore IAM 角色，藉此控管服務帳戶的存取權限。

使用存取權杖進行驗證

取得 Firebase ID 權杖或 Google Identity OAuth 2.0 權杖後，請將其設為 Authorization 標頭，並傳送至 Cloud Firestore 端點，並將其設為 Bearer {YOUR_TOKEN}。

發出 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

針對文件執行 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 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 伺服器傳回錯誤。 使用指數輪詢重試。