檢索數據

使用 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 條消息的數據。如果我們使用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來查找名稱在字典序上排在 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與子鍵的名稱一起使用時，包含指定子鍵的數據將按如下方式排序：

1. 指定子鍵的null值的子項排在第一位。
2. 接下來是指定子鍵值為false的子項。如果多個孩子的值為false ，則它們按字典順序按鍵排序。
3. 接下來是指定子鍵值為true的子項。如果多個孩子的值為true ，則它們按字典順序按鍵排序。
4. 接下來是具有數值的孩子，按升序排序。如果指定子節點的多個子節點的數值相同，則按key排序。
5. 字符串在數字之後，並按字典順序升序排序。如果指定子節點的多個子節點具有相同的值，則它們按鍵按字典順序排序。
6. 對象排在最後，並按鍵升序按字典順序排序。

orderBy="$鍵"

當使用orderBy="$key"參數對數據進行排序時，數據將按 key 升序返回，如下所示。請記住，鍵只能是字符串。

1. 具有可以解析為 32 位整數的鍵的孩子排在第一位，按升序排序。
2. 接下來是以字符串值作為鍵的子項，按字典順序升序排序。

orderBy="$值"

使用orderBy="$value"參數對數據進行排序時，子項將按其值排序。排序標準與按子鍵排序的數據相同，只是使用節點的值而不是指定子鍵的值。

orderBy="$優先級"

使用orderBy="$priority"參數對數據進行排序時，子項的排序由其優先級和鍵決定，如下所示。請記住，優先級值只能是數字或字符串。

1. 沒有優先級（默認）的孩子排在第一位。
2. 接下來是優先考慮數字的孩子。它們按優先級數字排序，從小到大。
3. 以字符串為優先級的孩子排在最後。它們按優先級按字典順序排序。
4. 每當兩個孩子具有相同的優先級（包括沒有優先級）時，它們將被按鍵排序。數字鍵排在第一位（按數字排序），然後是其餘鍵（按字典順序排序）。

有關優先級的更多信息，請參閱API 參考。

從 REST API 流式傳輸

Firebase REST 端點支持EventSource / Server-Sent Events協議，可以輕鬆地將更改流式傳輸到 Firebase 數據庫中的單個位置。

要開始流式傳輸，我們需要執行以下操作：

1. 將客戶端的 Accept 標頭設置為text/event-stream
2. 遵守 HTTP 重定向，特別是 HTTP 狀態代碼 307
3. 如果 Firebase 數據庫位置需要讀取權限，請包含auth查詢參數

作為回報，服務器將在請求的 URL 處的數據狀態發生變化時發送命名事件。這些消息的結構符合 EventSource 協議：

event: event name
data: JSON encoded data payload

服務器可能會發送以下事件：

以下是服務器可能發送的一組事件的示例：

// 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 的第三方包裝器。