使用 GET 讀取資料
我們可以向其網址發出 GET
要求,來讀取 Firebase 資料庫的資料
端點我們繼續回到前一節的網誌範例,
網誌文章資料:
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
成功的要求會以 200 OK
HTTP 狀態碼表示,
回應會包含我們擷取的資料。
新增 URI 參數
從 Firebase 資料庫讀取資料時,REST API 可接受多個查詢參數。 以下列出最常用的參數。如需完整清單,請參閱 REST API 參考資料。
auth
auth
要求參數可讓您存取受以下保護的資料:
Firebase Realtime Database Security Rules,且為
可支援所有請求類型引數可以是 Firebase 應用程式的密鑰或
驗證權杖,如「Firebase 專案中的使用者」所述。在以下範例中,我們會以 auth
傳送 GET
要求
參數,其中 CREDENTIAL
是 Firebase 應用程式的密鑰或
驗證權杖:
curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'
列印
指定 print=pretty
會以使用者可理解的格式傳回資料。
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
指定 print=silent
會在成功時傳回 204 No Content
。
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'
回呼
如要透過網路瀏覽器進行 REST 呼叫,您可以可以使用
JSONP,用於將回應包裝為 JavaScript
回呼函式。新增 callback=
,讓 REST API 在您指定的回呼函式中包裝傳回的資料。例如:
<script> function gotData(data) { console.log(data); } </script> <script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">
淺層
這是一項進階功能,可以幫助您處理大型資料集,完全不需要
全部下載。如要使用此功能,請新增 shallow=true
做為參數。這麼做會限制
傳回的資料深度。如果位置資料是 JSON 原始版本 (字串、數字、
或布林值)。如果位置的資料快照是 JSON
物件,每個鍵的值都會截斷為 true。例如,使用以下資料:
{ "message": { "user": { "name": "Chris" }, "body": "Hello!" } } // A request to /message.json?shallow=true // would return the following: { "user": true, "body": true } // A request to /message/body.json?shallow=true // would simply return: "Hello!"
您可以提出以下 curl
要求來試用看看:
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'
逾時
您可以使用這項屬性限制伺服器端讀取作業所需的時間。如果讀取要求未在指定時間內完成,就會終止並傳回 HTTP 400 錯誤。當您需要進行小規模的資料傳輸時,這個方式就特別實用 因此最好不要花太久的時間 才能擷取潛在的龐大子樹實際 讀取時間可能會因資料大小和快取而異。
請使用下列格式指定 timeouts
:3ms
、
3s
或 3min
,包含數字和單位。如果不是
已指定15min
,最多只能有timeout
已套用。如果 timeout
不是正值,或超過上限,系統會拒絕要求並傳回 HTTP 400 錯誤。在以下範例中,GET
要求包含
timeout
/10 秒。
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'
篩選資料
我們可以建立查詢,根據各種因素篩選資料。首先,請使用 orderBy
指定篩選資料的方式
參數。然後,將 orderBy
與另外五個參數的任一種合併:
limitToFirst
、limitToLast
、startAt
、endAt
、
和 equalTo
。
Firebase 全體人員都認為恐龍很酷 來自恐龍事實範例的資料庫片段 可以篩選資料:
{ "lambeosaurus": { "height": 2.1, "length": 12.5, "weight": 5000 }, "stegosaurus": { "height": 4, "length": 9, "weight": 2500 } }
篩選資料的方式有三種:依子項鍵、索引鍵或依據
value。查詢的開頭是下列其中一個參數,而且必須和下列一或多個參數合併:startAt
、endAt
、limitToFirst
、limitToLast
或 equalTo
。
依指定子項鍵篩選
我們可以按照常見子項金鑰篩選節點,方法是將該鍵傳遞至 orderBy
參數。例如,如要擷取高度大於 3 的所有恐龍,我們可以執行以下作業:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'
任何沒有我們篩選的子項鍵的節點,都會以 null
的值排序。如果想進一步瞭解我們如何
如何排序,請參閱資料的排序方式。
Firebase 也支援依深層巢狀子項排序的查詢,而不只是子項一層的子項。如果您有如下的深層巢狀資料,這種做法就非常實用:
{ "lambeosaurus": { "dimensions": { "height" : 2.1, "length" : 12.5, "weight": 5000 } }, "stegosaurus": { "dimensions": { "height" : 4, "length" : 9, "weight" : 2500 } } }
如要查詢高度,我們會使用物件的完整路徑,而非單一索引鍵:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'
查詢一次只能依一個鍵進行篩選。使用 orderBy
參數多個
逾時。
依鍵值篩選
也可以使用 orderBy="$key"
參數,依鍵篩選節點。
下列範例會擷取名稱開頭為字母 a
到 m
的所有恐龍:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'
依值篩選
我們可以使用 orderBy="$value"
,按子項鍵的值篩選節點
參數。假設恐龍正在進行恐龍運動比賽,我們會以以下格式追蹤他們的分數:
{ "scores": { "bruhathkayosaurus": 55, "lambeosaurus": 21, "linhenykus": 80, "pterodactyl": 93, "stegosaurus": 5, "triceratops": 22 } }
為了擷取分數高於 50 的所有恐龍,我們可以提出下列要求:
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'
如要瞭解使用 orderBy="$value"
時,如何排序 null
、布林值、字串和物件值,請參閱「資料排序方式」。
複雜篩選
我們可以結合多個參數,建立更複雜的查詢。
限制查詢
limitToFirst
和 limitToLast
參數是用來設定
可接收資料的子項數量上限。如果將上限設為 100,我們只會
最多可接收 100 個相符的子項。如果在我們的網站上儲存的訊息少於 100 則
資料庫中,內含每個子項。不過,如果訊息超過 100 則,我們只會收到其中 100 則的資料。如果系統根據
使用 limitToFirst
或最近 100 則已排序訊息 (如果使用
limitToLast
。
使用恐龍資料庫和 orderBy
,我們可以找到兩種最重的恐龍:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'
同樣地,我們也可以使用 limitToFirst
找出兩隻最短的恐龍:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'
我們也可以使用 orderBy="$value"
執行限制查詢。如果您要建立
排行榜前三名的恐龍運動競爭對手
包括:
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'
範圍查詢
使用 startAt
、endAt
和 equalTo
可讓我們選擇
任意幾個起點和終點舉例來說
高度至少為 3 公尺的恐龍,我們可以將 orderBy
和
startAt
:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'
我們可以使用 endAt
找出所有名稱在字典順序上位於 Pterodactyl 之前的恐龍:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'
我們可以結合 startAt
和 endAt
,以限制查詢的兩個結尾。
以下範例可找出名稱開頭為「b」的所有恐龍:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'
需要為資料分頁時,範圍查詢也相當實用。
全面整合使用
我們可以組合這些技術來建立複雜的查詢。舉例來說 找出所有小於或等於我們喜愛的恐龍名稱 可以說:
MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"` curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"
資料的排序方式
本節說明使用三個篩選參數時,資料的排序方式。
orderBy
搭配子項鍵名稱使用 orderBy
時,含有指定值的資料
子項金鑰的順序如下:
-
針對指定子項金鑰,具有
null
值的子項會先列出。 -
指定子項金鑰值為
false
的子項接著會顯示。如果有多個子項的值為false
,系統會依據鍵以字典順序排序。 -
指定子項金鑰值為
true
的子項接著會顯示。如果 多個子項的值為true
,其會按照字母順序排序 鍵。 - 含有數值的子項接著會以遞增順序排序。如果有多位子項 在指定子節點的數值上相同,而是按索引鍵排序。
- 字串是由數字後方,並按字母順序排列,但以遞增順序排列。如有多個 子節點的指定子節點值相同,系統會依順序 並按照字母順序排列
- 物件會在最後出現,並按照索引鍵順序排列,以遞增順序排列。
orderBy="$key"
使用 orderBy="$key"
參數排序資料時,系統會傳回資料
,如下所示。請注意,金鑰只能包含字串。
- 具有索引鍵可剖析為 32 位元整數的子項,其會先以遞增方式排序 順序。
- 具有字串值的子項,在其索引鍵出現時,則按照字母順序遞增排序 順序。
orderBy="$value"
使用 orderBy="$value"
參數排序資料時,子項會是
來排序。排序條件與子項鍵排序的資料相同。
但會使用節點的值取代指定子鍵的值。
orderBy="$priority"
使用 orderBy="$priority"
參數排序資料時,
子項取決於其優先順序和索引鍵,如下所示。請記住,優先級值
只能是數字或字串。
- 沒有優先順序 (預設) 的子項會先顯示。
- 下一個優先順序為數字的孩子。這些項目會依優先順序排序,由小到大。
- 以字串做為其優先順序的子項會持續排列。排序依據為字母順序 優先順序。
- 如果兩個子項有相同的優先順序 (包括無優先順序),就會按照索引鍵排序。 數字鍵會先排序 (以數字排序),接著是其餘的鍵 (以字典順序排序)。
如要進一步瞭解優先順序,請參閱 API 參考資料。
透過 REST API 串流
Firebase REST 端點支援 EventSource/伺服器傳送事件通訊協定,可輕鬆將變更串流傳送至 Firebase 資料庫中的單一位置。
如要開始直播,請完成下列事項:
-
將用戶端的 Accept 標頭設為
text/event-stream
- 採用 HTTP 重新導向,尤其是 HTTP 狀態碼 307
-
如果 Firebase 資料庫位置需要
auth
讀取權限
在回傳時,伺服器會傳送命名事件,因為要求的網址資料狀態會有所變更。這些郵件的結構符合 EventSource 通訊協定:
event: event name data: JSON encoded data payload
伺服器可能會傳送下列事件:
put | JSON 編碼資料會是包含兩個鍵的物件:路徑和資料 路徑指向相對於要求網址的位置 用戶端應將快取位置的所有資料替換成訊息中提供的資料 |
patch | JSON 編碼資料會是包含兩個鍵的物件:路徑和資料 路徑指向相對於要求網址的位置 用戶端應針對資料中的每個鍵,將快取中的對應金鑰替換為訊息中該鍵的資料 |
保持運作 | 這個事件的資料為空值,您無須採取任何行動 |
取消 | 此事件的資料為空值 如果 Firebase Realtime Database Security Rules 導致無法再讀取要求位置,系統就會傳送此事件 |
驗證已撤銷 | 這個事件的資料是字串,用來指出憑證已過期 提供的驗證參數失效時,系統就會傳送這個事件 |
以下是伺服器可能會傳送的一系列事件範例:
// 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}}
如果您使用 Go,請試試 Firego,這是 Firebase REST 和 Streaming API 的第三方包裝函式。