使用 Cloud Firestore REST API

雖然使用 Cloud Firestore 最簡單的方法是使用本機用戶端程式庫之一,但在某些情況下直接呼叫 REST API 很有用。

REST API 對於以下用例很有幫助:

  • 從資源受限的環境(例如物聯網 (IoT) 裝置)存取 Cloud Firestore,在該環境中無法執行完整的用戶端程式庫。
  • 自動化資料庫管理或檢索詳細的資料庫元資料。

如果您使用的是gRPC 支援的語言,請考慮使用RPC API而不是 REST API。

認證與授權

對於驗證,Cloud Firestore REST API 接受Firebase 驗證ID 令牌或Google Identity OAuth 2.0令牌。您提供的令牌會影響您的請求的授權:

  • 使用 Firebase ID 令牌對來自應用程式使用者的請求進行身份驗證。對於這些請求,Cloud Firestore 使用Cloud Firestore 安全性規則來決定請求是否獲得授權。

  • 使用 Google Identity OAuth 2.0 令牌和服務帳戶對來自應用程式的請求進行身份驗證,例如資料庫管理請求。對於這些請求,Cloud Firestore 使用身分識別和存取管理 (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 Identity OAuth 2.0 令牌對請求進行身份驗證,則 Cloud Firestore 會假定您的請求代表您的應用程式而不是個人使用者執行操作。 Cloud Firestore 允許這些要求忽略您的安全規則。相反,Cloud Firestore 使用IAM來確定請求是否獲得授權。

您可以透過指派Cloud Firestore IAM 角色來控制服務帳號的存取權限。

使用訪問令牌進行身份驗證

取得 Firebase ID 令牌或 Google Identity OAuth 2.0 令牌後,將其作為設定為Bearer {YOUR_TOKEN} Authorization標頭傳遞到 Cloud Firestore 端點。

進行 REST 調用

所有 REST API 端點都存在於基本 URL https://firestore.googleapis.com/v1/下方。

若要在專案YOUR_PROJECT_ID下的集合cities中建立 ID 為LA的文件的路徑,您將使用下列結構。

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

要與此路徑交互,請將其與基本 API URL 結合。

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 4xx5xx狀態碼以及包含錯誤訊息的回應。

下表列出了針對每個錯誤代碼的建議操作。這些程式碼適用於 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 伺服器回傳錯誤。使用指數退避重試。