本頁面由 Cloud Translation API 翻譯而成。

使用 Cloud Firestore REST API

最簡單的 Cloud Firestore 方法就是使用其中一種在某些情況下直接呼叫 REST API

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

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

如果您使用支援 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/ 下。

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