API 使用方式
您可以使用任何 Firebase 即時資料庫網址做為 REST 端點。隨心所欲
是將 .json 附加至網址結尾並傳送要求
。
必須使用 HTTPS。Firebase 只會回應加密流量，確保資料安全無虞。
GET - 讀取資料
只要發出 HTTP 要求，即可讀取 Realtime Database 中的資料
對端點的 GET 要求。以下範例
示範如何擷取使用者的
您先前儲存在「Realtime Database」的名稱。
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
200 OK HTTP 圖示表示要求成功
狀態碼。回應會包含與
GET 要求中的路徑。
{ "first": "Jack", "last": "Sparrow" }
PUT - 寫入資料
您可以透過 PUT 要求寫入資料。
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
200 OK HTTP 圖示表示要求成功
狀態碼。回應會包含
PUT要求。
{ "first": "Jack", "last": "Sparrow" }
POST - 推送資料
為完成與 JavaScript push() 的對等項目
方法 (請參閱「資料清單」)。
可以發出 POST 要求
curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \ 'https://[PROJECT_ID].firebaseio.com/message_list.json'
要求成功會顯示在 200 OK HTTP 狀態中
再也不是件繁重乏味的工作回應包含新資料的子項名稱
在 POST 要求中指定。
{ "name": "-INOQPH-aV_psbk3ZXEX" }
PATCH - 更新資料
您可以更新地點的特定孩子，無需覆寫
使用 PATCH 要求建立現有資料在
使用 PATCH 寫入的資料會遭到覆寫，但省略的數字
子項不會遭到刪除這相當於 JavaScript
update() 函式。
curl -X PATCH -d '{"last":"Jones"}' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'
要求成功會顯示在 200 OK HTTP 狀態中
再也不是件繁重乏味的工作回應會包含
PATCH要求。
{ "last": "Jones" }
刪除 - 移除資料
您可以使用 DELETE 要求刪除資料：
curl -X DELETE \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
如果 DELETE 要求成功，
200 OK HTTP 狀態碼，且回應包含 JSON
null。
方法覆寫
如果您從不支援
上述方法，您可以
POST 要求，並使用以下指令設定您的方法
X-HTTP-Method-Override 要求標頭。
curl -X POST -H "X-HTTP-Method-Override: DELETE" \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
您也可以使用 x-http-method-override 查詢參數。
curl -X POST \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'
條件式要求
條件式要求，相當於 SDK 交易作業的 REST，會根據 或符合特定條件查看工作流程總覽並進一步瞭解條件式要求 儲存資料中的 REST 類型。
Firebase ETag
Firebase ETag 是目前資料在指定位置的專屬 ID。如果
該位置的資料變更，ETag 也會跟著改變。您必須在
標頭 (通常是
GET，但可以是 PATCH 以外的任何項目)。
curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
若相符
if-match 條件會針對您要更新的資料指定 ETag 值。
如果使用條件，Realtime Database 就只會完成
寫入要求和資料庫中現有資料的 ETag。擷取
ETag 位於有 Firebase ETag 要求的位置。如果您想覆寫某個
空值，使用 null_etag。
curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'
預期的回應
下表概略說明各要求類型的預期回應。 建立一個新的主要類別
| 要求類型 | 「X-Firebase-ETag: true」 | ETag 與 if_match: <matching etag> 相符 |
ETag 與 不符 if_match: <no matching etag> |
|
|---|---|---|---|---|
| 下載 | 回應狀態/內容 | 200：「<data_at_path>」 | 400：「...不支援...」 | 400：「...不支援...」 |
| 新增的標頭 | ETag：<ETag_of_data> | 不適用 | 不適用 | |
| 固定 | 回應狀態/內容 | 200：「<put_data>」 | 200：「<put_data>」 | 412：「...ETag 不符..」 |
| 新增的標頭 | ETag：<ETag_of_put_data> | 不適用 | ETag：<database_ETag> | |
| 發布 | 回應狀態/內容 | 200：「<post_data>」 | 400：「...不支援...」 | 400：「...不支援...」 |
| 新增的標頭 | ETag：<ETag_of_post_data> | 不適用 | 不適用 | |
| 簡報 | 回應狀態/內容 | 400：「...不支援...」 | 400：「...不支援...」 | 400：「...不支援...」 |
| 新增的標頭 | 不適用 | 不適用 | 不適用 | |
| 刪除 | 回應狀態/內容 | 200：空值 | 200：「<data_after_put>」 | 412：「...ETag 不符..」 |
| 新增的標頭 | ETag：<ETag_of_null> | 不適用 | ETag：<database_ETag> | |
查詢參數
Firebase Database REST API 接受下列查詢參數，並 值：
access_token
所有要求類型都支援這項功能。驗證這項要求即可 存取由 Firebase Realtime Database Security Rules 保護的資料。 詳情請參閱 REST 驗證說明文件。
curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'
淺層
這項進階功能主要是為了協助您
不必下載所有資料設為
true：限制傳回資料的深度
物件如果位置的資料是 JSON 基元
(字串、數字或布林值)，系統只會傳回其值。如果
位置的資料快照是 JSON 物件
每個鍵的值都會截斷為 true。
| 引數 | REST 方法 | 說明 |
|---|---|---|
| 淺層 | GET | 限制回應深度。 |
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'
請注意，shallow 無法與任何其他查詢搭配使用
參數。
列印
將伺服器的回應中傳回的資料格式化。
| 引數 | REST 方法 | 說明 |
|---|---|---|
| 美觀 | GET、PUT、POST、PATCH、DELETE | 以使用者可理解的格式查看資料。 |
| 靜音 | GET、PUT、POST、PATCH |
用於在寫入資料時抑制伺服器輸出。
產生的回應會是空白的
204 No Content HTTP 狀態碼。
|
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'
回呼
僅支援 GET。透過網路瀏覽器執行 REST 呼叫
可以使用 JSONP，將回應包裝在 JavaScript 中
回呼函式。新增 callback= 以納入 REST API 包裝
您在指定的回呼函式中傳回的資料。
<script> function gotData(data) { console.log(data); } </script> <script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>
格式
如果設為 export，伺服器就會在
回應。
| 引數 | REST 方法 | 說明 |
|---|---|---|
| 匯出 | GET | 在回應中加入優先順序資訊。 |
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'
下載
僅支援 GET。如何觸發檔案
從網路瀏覽器下載您的資料，請新增 download=。
這會導致 REST 服務新增適當的標頭，以便
就會知道要將資料儲存到檔案。
curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'
逾時
用於限制伺服器端讀取作業的時間。如果讀取 要求未在分配的時間內完成，就會以 HTTP 回應 400 錯誤。當您需要進行小規模的資料傳輸時，這個方式就特別實用 因此最好不要花太久的時間 才能擷取潛在的龐大子樹實際 讀取時間可能會因資料大小和快取而異。
請使用下列格式指定 timeouts：3ms、
3s 或 3min，包含數字和單位。如果不是
已指定15min，最多只能有timeout
已套用。如果 timeout 不是正數或超過數量上限，
要求都會遭到拒絕，並顯示 HTTP 400 錯誤。
WriteSizeLimit
如要限制寫入的大小 可以將
writeSizeLimit 查詢參數指定為
tiny (目標 1 秒)、small (目標 10 秒)、
medium (目標=30 秒)、large (目標=60 秒)。
即時資料庫會估算每個寫入要求的大小並取消作業
請求可能需要的時間會超過目標時間
指定 unlimited 時，會造成異常大量寫入 (酬載最多 256 MB)
系統可能會在資料庫處理
目前作業寫入伺服器後即無法取消寫入。
curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'
如果寫入過大，系統會顯示以下錯誤訊息：
Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.
此外，您可以為整個資料庫設定 defaultWriteSizeLimit
管理執行個體這項限制適用於所有要求，包括來自 SDK 的要求。
建立defaultWriteSizeLimit設為 large 的新資料庫。
您無法使用 Firebase CLI 將 defaultWriteSizeLimit 設為 tiny，
firebase database:settings:set defaultWriteSizeLimit large
orderBy
請參閱指南中這一節， 排序資料 瞭解詳情
limitToFirst、LimitToLast、startAt、endAt、equalTo
請參閱指南中這一節， 篩選資料 瞭解詳情
透過 REST API 串流
Firebase REST 端點支援 事件來源 / 伺服器傳送事件 因此效能相當卓越如要將變更串流至Realtime Database中的單一位置，請按照下列步驟操作： 請完成以下事項：
-
將用戶端的 Accept 標頭設為
"text/event-stream" - 採用 HTTP 重新導向，尤其是 HTTP 狀態碼 307
-
如果位置資訊要求讀取權限，則必須加入
auth參數
接著，伺服器會傳送具名事件做為
要求變更。這類郵件的結構必須符合
EventSource 通訊協定。
event: event name data: JSON encoded data payload
伺服器可能會傳送下列事件：
put
JSON 編碼資料是具有兩個鍵的物件：path 和資料。path 索引鍵會指向 相對於要求網址的相對位置用戶端應該將 在快取中保留該位置的資料與「data」。
patch
JSON 編碼資料是具有兩個鍵的物件：path 和資料。path 索引鍵會指向 相對於要求網址的相對位置針對每個 data，用戶端應將 快取中對應的金鑰，以及訊息中該鍵的資料。
保持運作
這個事件的資料為 null。您無須採取任何行動，
取消
有些非預期的錯誤可能會傳送 `cancel` 事件並終止連線， 原因請參閱系統為這個事件提供的資料。以下列舉幾個可能原因 如下： 1.Firebase Realtime Database Security Rules 不再允許在要求的位置讀取資料。 這個問題的「資料」說明為「權限遭拒」。 2. 寫入作業觸發的事件串流程式傳送了超過我們的限制的大型 JSON 樹狀結構。 512 MB。這項原因的 `data` 為「指定的酬載過大，請 資料較少的位置」
驗證已撤銷
此事件的資料是字串，指出憑證
已過期。系統會在提供的 auth 時傳送這個事件
參數已失效。
以下是伺服器可能會傳送的一系列事件範例：
// Set your entire cache to {"a": 1, "b": 2} event: put data: {"path": "/", "data": {"a": 1, "b": 2}} // Put the new data in your cache under the key 'c', so that the complete cache now looks like: // {"a": 1, "b": 2, "c": {"foo": true, "bar": false}} event: put data: {"path": "/c", "data": {"foo": true, "bar": false}} // For each key in the data, update (or add) the corresponding key in your cache at path /c, // for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}} event: patch data: {"path": "/c", "data": {"foo": 3, "baz": 4}}
優先順序
如果某個位置的優先順序資訊，可以使用
「虛擬子項」名為 .priority。您可以透過以下方式讀取優先順序：
GET 要求，並透過 PUT 要求寫入。
例如，下列要求會擷取
users/tom 個節點：
curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'
如要同時寫入優先順序和資料，您可以新增
對 JSON 酬載的 .priority 子項：
curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \ 'https://[PROJECT_ID].firebaseio/users/tom.json'
如要同時寫入優先順序和原始值 (例如字串)，
您可以新增 .priority 子項，並將基本值設為
在 .value 子項中：
curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \ 'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'
這會寫入 "Tom"，優先順序為 1.0。
優先順序可在 JSON 酬載的任何深度中包含。
伺服器值
您可以使用預留位置值，將伺服器值寫入某個位置，
是具有單一 .sv 鍵的物件。該鍵的值是
選擇要設定的伺服器值類型例如，下列
要求將節點的值設為 Firebase 伺服器的現行值
timestamp：
curl -X PUT -d '{".sv": "timestamp"}' \ 'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'
您也可以使用伺服器值寫入優先順序， 「虛擬子項」路徑。
支援的伺服器值包括：
| 伺服器值 | |
|---|---|
| 時間戳記 | 自 UNIX Epoch 紀元時間起算的時間 (以毫秒為單位)。 |
| 遞增 | 請以下列格式提供整數或浮點差異值：
{ ".sv": {"increment": <delta_value> }}，其能以不可分割的形式
目前的資料庫值遞增。如果資料尚不存在，更新會
轉換為差異值如果任一差異值或現有資料為浮動值
這兩個值都會被解譯為浮點數，並套用至
做為雙精度浮點數雙算數和雙精度浮點值
IEEE 754 語意。如果有正/負整數溢位，系統會計算總和
轉換成雙精度浮點數 |
正在擷取及更新 Firebase Realtime Database Security Rules
REST API 也可用來擷取與更新 Firebase Realtime Database Security Rules： 您的 Firebase 專案。您需要 Firebase 專案的密鑰， 您也可以在 服務帳戶Firebase 專案的面板 以及環境敘述
curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET' curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
驗證要求
根據預設，REST 要求會在不驗證的情況下執行，且只會在
Realtime Database 規則允許公開讀取或寫入權限
實體媒介包括儲存空間陣列
傳統硬碟、磁帶和 USB 隨身碟等如要驗證您的要求，請使用
access_token= 或 auth= 查詢參數。
進一步瞭解如何透過 REST API 進行驗證，詳情請參閱： 驗證 REST 要求。
錯誤狀況
Firebase Database REST API 可傳回下列錯誤代碼，
| HTTP 狀態碼 | |
|---|---|
| 400 錯誤的要求 |
下列其中一項錯誤狀況：
|
| 401 未授權 |
下列其中一項錯誤狀況：
|
| 找不到 404 | 找不到指定的Realtime Database。 |
| 500 內部伺服器錯誤 | 伺服器傳回錯誤。詳情請參閱錯誤訊息 詳細資料。 |
| 503 無法使用服務 | 指定的 Firebase 即時資料庫暫時無法使用， 這代表要求未嘗試 |
| 412 先決條件失敗 | 要求在 if-match 標頭中指定的 ETag 值與伺服器的值不符。 |