雖然使用 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 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 伺服器回傳錯誤。 | 使用指數退避重試。 |