使用 Cloud Firestore REST API

使用 Cloud Firestore 是最簡單的方式 在某些情況下 直接呼叫 REST API

REST API 很適合用於下列用途：

  • 從資源受限的環境存取 Cloud Firestore 例如物聯網 (IoT) 裝置 透過 Google 代管的完整用戶端 就無法使用程式庫
  • 自動管理資料庫或擷取詳細的資料庫中繼資料。

如果您使用 支援 gRPC 的語言，請考慮使用 RPC API，而非 REST API。

驗證及授權

如要進行驗證，Cloud Firestore REST API 接受 Firebase 驗證 ID 權杖 Google Identity OAuth 2.0 權杖。您提供的權杖 會影響要求的授權：

  • 使用 Firebase ID 權杖來驗證應用程式使用者的要求。 針對這類要求，Cloud Firestore 會使用 判斷要求是否屬於 Cloud Firestore 安全性規則 已獲得授權

  • 使用 Google 身分 OAuth 2.0 權杖和 服務帳戶來驗證來自您 例如資料庫管理要求針對這些要求 Cloud Firestore 使用的 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 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/ 下。

如何為「cities」集合中的 ID 為 LA 的文件建立路徑 在專案 YOUR_PROJECT_ID 下，您將使用下列結構。

/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 APICloud 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 伺服器傳回錯誤。 使用指數輪詢重試。