使用 GET 讀取數據
我們可以通過向其 URL 端點發出GET
請求來從 Firebase 數據庫中讀取數據。讓我們繼續上一節中的博客示例,並閱讀我們所有的博客文章數據:
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
,帶有數字和單位。如果未指定,將應用15min
的最大timeout
。如果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 條消息的數據。如果我們使用limitToLast
,這些將是前 100 個有序消息,如果我們使用limitToFirst
,這些將是最後 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
來查找所有名稱在 Pterodactyl 字典序上位於 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
時,包含指定子鍵的數據將按如下順序排序:
- 具有指定子鍵的
null
值的子項首先出現。 - 接下來是指定子鍵的值為
false
的子項。如果多個孩子的值為false
,則它們按字典順序鍵排序。 - 接下來是指定子鍵的值為
true
的子項。如果多個孩子的值為true
,則它們按字典順序鍵排序。 - 接下來是具有數值的子項,按升序排序。如果指定子節點的多個子節點的數值相同,則按key排序。
- 字符串在數字之後,並按字典順序升序排序。如果指定子節點的多個子節點具有相同的值,則它們按字典順序鍵排序。
- 對象排在最後,並按關鍵字按字典順序升序排序。
orderBy="$key"
當使用orderBy="$key"
參數對數據進行排序時,數據將按 key 升序返回,如下所示。請記住,鍵只能是字符串。
- 具有可以被解析為 32 位整數的鍵的子項排在最前面,按升序排序。
- 以字符串值作為鍵的子項緊隨其後,按字典順序升序排序。
orderBy="$value"
使用orderBy="$value"
參數對數據進行排序時,子項將按其值排序。排序標準與按子鍵排序的數據相同,只是使用節點的值而不是指定子鍵的值。
orderBy="$priority"
使用orderBy="$priority"
參數對數據進行排序時,子項的順序由它們的優先級和鍵確定,如下所示。請記住,優先級值只能是數字或字符串。
- 沒有優先級(默認)的孩子優先。
- 接下來是優先考慮數字的孩子。它們按優先級從小到大按數字排序。
- 以字符串為優先的孩子排在最後。它們按優先級按字典順序排序。
- 每當兩個孩子具有相同的優先級(包括沒有優先級)時,它們就會按鍵排序。數字鍵首先出現(按數字排序),然後是其餘鍵(按字典順序排序)。
有關優先級的更多信息,請參閱API 參考。
從 REST API 流式傳輸
Firebase REST 端點支持EventSource / Server-Sent Events協議,可以輕鬆地將更改流式傳輸到 Firebase 數據庫中的單個位置。
要開始使用流媒體,我們需要執行以下操作:
- 將客戶端的 Accept 標頭設置為
text/event-stream
- 尊重 HTTP 重定向,特別是 HTTP 狀態碼 307
- 如果 Firebase 數據庫位置需要讀取權限,請包括
auth
查詢參數
作為回報,服務器將在請求的 URL 處的數據狀態發生變化時發送命名事件。這些消息的結構符合 EventSource 協議:
event: event name data: JSON encoded data payload
服務器可能會發送以下事件:
放 | JSON 編碼的數據將是一個具有兩個鍵的對象:路徑和數據 路徑指向相對於請求 URL 的位置 客戶端應將其緩存中該位置的所有數據替換為消息中給出的數據 |
修補 | JSON 編碼的數據將是一個具有兩個鍵的對象:路徑和數據 路徑指向相對於請求 URL 的位置 對於數據中的每個鍵,客戶端應將其緩存中的相應鍵替換為消息中該鍵的數據 |
活著 | 此事件的數據為空,無需任何操作 |
取消 | 此事件的數據為空 如果 Firebase 實時數據庫規則導致不再允許在請求的位置進行讀取,則會發送此事件 |
auth_revoked | 此事件的數據是一個字符串,表示憑證已過期 當提供的 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 的第三方包裝器。