使用 Firestore REST API

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

REST API 可用於下列用途：

  • 從資源受限的環境存取 Firestore，例如物聯網 (IoT) 裝置，這類環境無法執行完整的用戶端程式庫。
  • 自動執行資料庫管理作業，或擷取詳細的資料庫中繼資料。

如果您使用支援 gRPC 的語言，建議使用 RPC API，而非 REST API。

驗證及授權

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

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

  • 使用 Google Identity OAuth 2.0 權杖和服務帳戶，驗證來自應用程式的要求，例如資料庫管理要求。對於這類要求，Firestore 會使用 Identity and Access Management (IAM) 判斷要求是否已獲得授權。

使用 Firebase ID 憑證

您可以透過兩種方式取得 Firebase ID 權杖：

擷取使用者的 Firebase ID 權杖後，您就能代表使用者提出要求。

對於使用 Firebase ID 權杖驗證的要求和未經驗證的要求，Firestore 會使用 Firestore 安全性規則判斷要求是否已獲得授權。

使用 Google Identity OAuth 2.0 權杖

您可以使用服務帳戶和 Google API 用戶端程式庫產生存取權杖，也可以按照「針對伺服器對伺服器應用程式使用 OAuth 2.0」一文中的步驟操作。您也可以使用 gcloud 指令列工具和 gcloud auth application-default print-access-token 指令產生權杖。

如要將要求傳送至 Firestore REST API，這個權杖必須具有下列範圍：

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

如果您使用服務帳戶和 Google Identity OAuth 2.0 權杖驗證要求，Firestore 會假設您的要求是代表應用程式 (而非個別使用者) 執行動作。Firestore 允許這些要求忽略安全性規則。Firestore 會改用 IAM 判斷要求是否已獲得授權。

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

使用存取權杖進行驗證

取得 Firebase ID 權杖或 Google Identity OAuth 2.0 權杖後，請將權杖做為 Authorization 標頭傳遞至 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

對索引執行動作，例如建立新索引、停用現有索引，或列出所有目前的索引。有助於自動化資料結構遷移作業，或在專案之間同步處理索引。

此外，您也可以擷取文件的中繼資料，例如特定文件的所有欄位和子集合清單。

錯誤代碼

Firestore 要求成功時，Firestore API 會傳回 HTTP 200 OK 狀態碼和所要求的資料。如果要求失敗，Firestore API 會傳回 HTTP 4xx 或 5xx 狀態碼，以及包含錯誤資訊的回應。

下表列出各個錯誤代碼的建議動作。這些代碼適用於 Firestore REST 和 RPC API。Firestore SDK 和用戶端程式庫可能不會傳回這些錯誤碼。

標準化錯誤代碼 說明 建議做法
ABORTED 該要求與另一項要求衝突。 非交易式提交：
重試要求，或重新建構資料模型以減少爭用。

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

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