使用 GET 讀取數據
我們可以透過向 Firebase 資料庫的 URL 端點發出GET
請求來讀取資料。讓我們繼續上一節中的部落格範例並閱讀我們所有的部落格文章資料:
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
成功的請求將由200 OK
HTTP 狀態碼指示,並且回應將包含我們正在檢索的資料。
新增 URI 參數
從 Firebase 資料庫讀取資料時,REST API 接受多個查詢參數。下面列出了最常用的參數。有關完整列表,請參閱REST API參考 。
授權
auth
請求參數允許存取受Firebase 即時資料庫安全規則保護的數據,並且所有請求類型都支援。此參數可以是您的 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'
打回來
若要從 Web 瀏覽器跨網域進行 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
,並附有數字和單位。如果未指定,則將套用最大timeout
15min
。如果timeout
不為正數或超過最大值,則請求將被拒絕,並出現 HTTP 400 錯誤。在以下範例中, GET
請求包含 10 秒的timeout
。
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 } }
我們可以透過以下三種方式之一過濾資料:按子鍵、按鍵或按值。查詢以這些參數之一開始,然後必須與以下一個或多個參數組合: 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
,這些將是最後 100 個有序訊息。
使用我們的恐龍事實資料庫和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
允許我們為查詢選擇任意起點和終點。例如,如果我們想找到所有身高至少三公尺的恐龍,我們可以結合orderBy
和startAt
:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'
我們可以使用endAt
來找出所有依字典順序排列在翼手龍之前的恐龍:
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
時,包含指定子鍵的資料將如下排序:
- 指定子鍵的值為
null
子項排在第一位。 - 接下來是指定子鍵值為
false
的子項。如果多個子項的值為false
,則它們按鍵按字典順序排序。 - 接下來是指定子鍵值為
true
的子項。如果多個子項的值為true
,則它們按鍵按字典順序排序。 - 接下來是具有數值的子項,依升序排序。如果指定子節點的多個子節點具有相同的數值,則它們會按鍵排序。
- 字串位於數字之後,並依字典順序升序排序。如果指定子節點的多個子節點具有相同的值,則它們按鍵按字典順序排序。
- 物件排在最後,並依字典順序按鍵升序排序。
orderBy="$key"
當使用orderBy="$key"
參數對資料進行排序時,資料將按 key 升序傳回,如下所示。請記住,鍵只能是字串。
- 具有可解析為 32 位元整數的鍵的子項排在前面,按升序排序。
- 接下來是以字串值作為鍵的子項,依字典順序升序排列。
orderBy=“$值”
當使用orderBy="$value"
參數對資料進行排序時,子項將按其值排序。排序標準與按子鍵排序的資料相同,只是使用節點的值而不是指定子鍵的值。
orderBy="$優先權"
當使用orderBy="$priority"
參數對資料進行排序時,子項的順序由其優先權和鍵決定,如下所示。請記住,優先權值只能是數字或字串。
- 沒有優先順序(預設)的孩子首先出現。
- 接下來是優先考慮數字的孩子。它們按優先順序從小到大按數字排序。
- 優先考慮繩子的孩子排在最後。它們按優先順序按字典順序排序。
- 每當兩個孩子具有相同的優先順序(包括沒有優先順序)時,它們就會按鍵排序。數字鍵排在前面(按數字排序),然後是其餘鍵(按字典順序排序)。
有關優先順序的更多信息,請參閱API 參考。
從 REST API 進行串流傳輸
Firebase REST 端點支援EventSource / 伺服器傳送事件協議,可輕鬆地將變更串流傳輸到 Firebase 資料庫中的單一位置。
要開始串流傳輸,我們需要執行以下操作:
- 將客戶端的 Accept header 設定為
text/event-stream
- 尊重 HTTP 重新導向,特別是 HTTP 狀態碼 307
- 如果 Firebase 資料庫位置需要讀取權限,請包含
auth
查詢參數
作為回報,伺服器將在請求的 URL 處的資料狀態發生變化時發送命名事件。這些訊息的結構符合EventSource協定:
event: event name data: JSON encoded data payload
伺服器可能會發送以下事件:
放 | JSON 編碼的資料將是一個具有兩個鍵的物件:路徑和數據 路徑指向相對於請求 URL 的位置 客戶端應使用訊息中給出的數據替換其快取中該位置的所有數據 |
修補 | JSON 編碼的資料將是一個具有兩個鍵的物件:路徑和數據 路徑指向相對於請求 URL 的位置 對於資料中的每個鍵,客戶端應將其快取中的相應鍵替換為訊息中該鍵的數據 |
活著 | 此事件的資料為空,無需執行任何操作 |
取消 | 該事件的數據為空 如果 Firebase 即時資料庫安全性規則導致不再允許在請求的位置進行讀取,則會傳送此事件 |
授權撤銷 | 此事件的資料是一個字串,指示憑證已過期 當提供的 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}}
如果您使用 Go,請查看Firego ,它是 Firebase REST 和 Streaming API 的第三方包裝器。