正在擷取資料 | Firebase Realtime Database

使用 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 即時資料庫安全性規則，屬於可支援所有請求類型引數可以是 Firebase 應用程式的密鑰或驗證權杖，如「Firebase 專案中的使用者」所述。在以下範例中，我們會以 auth 傳送 GET 要求參數，其中 CREDENTIAL 是 Firebase 應用程式的密鑰或驗證權杖：

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

如果已設定權杖的 debug 旗標，即可在回應的 X-Firebase-Auth-Debug 標頭。

顯示

指定 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'

callback

如要透過網路瀏覽器進行 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'

shallow 無法與任何「篩選資料」搭配使用查詢參數

逾時

用於限制伺服器端讀取作業的時間。如果讀取要求未在分配的時間內完成，就會以 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 參數多個逾時。

在 Firebase 即時資料庫安全性規則中加入索引：如果您在應用程式中使用 orderBy，就必須定義要使用的鍵建立索引時，來源是 Firebase 即時資料庫安全性規則中的 .indexOn 規則。請參閱 .indexOn 規則。

依鍵篩選

也可以使用 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'

如要瞭解資料的排序方式，請參閱資料的排序方式。 null、布林值、字串和物件值如何在使用 orderBy="$value"。

在 Firebase 即時資料庫安全性規則中加入索引：如果您在應用程式中使用 orderBy="$value"，則必須新增 .value 套用至適當索引的規則請參閱 .indexOn 規則。

複雜篩選

我們可以結合多個參數，建立更複雜的查詢。

限制查詢

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 找出所有姓名在皮特拉克之前的恐龍字母順序：

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

startAt 和 endAt 內含，表示「pterodactyl」將比對查詢。

我們可以結合 startAt 和 endAt，以限制查詢的兩個結尾。以下範例可找出名稱開頭為「b」的所有恐龍：

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

上述查詢中使用的 \uf8ff 字元是「 Unicode 範圍。由於位於 Unicode 大部分一般字元之後，這項查詢會比對所有先從 b 開始

需要為資料分頁時，範圍查詢也相當實用。

全面整合使用

我們可以組合這些技術來建立複雜的查詢。舉例來說找出所有小於或等於我們喜愛的恐龍名稱可以說：

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"

資料的排序方式

本節將說明使用這三個篩選參數時的資料排序方式。

REST API 會傳回未排序的結果： JSON 解譯器不會強制根據結果集設定任何順序。orderBy 時可與 startAt、endAt 搭配使用 limitToFirst 或 limitToLast 傳回部分資料，則傳回的結果不會排序。因此，您可能需要手動將因為順序很重要

orderBy

搭配子項鍵名稱使用 orderBy 時，含有指定值的資料子項金鑰的順序如下：

針對指定子項金鑰，具有 null 值的子項會先列出。
指定子項金鑰值為 false 的子項接著會顯示。如果多個子項的值為 false，系統會將其排序按鍵的字母順序排列。
指定子項金鑰值為 true 的子項接著會顯示。如果多個子項的值為 true，其會按照字母順序排序鍵。
含有數值的子項接著會以遞增順序排序。如果有多位子項在指定子節點的數值上相同，而是按索引鍵排序。
字串是由數字後方，並按字母順序排列，但以遞增順序排列。如有多個子節點的指定子節點值相同，系統會依順序並按照字母順序排列
物件會在最後出現，並按照索引鍵順序排列，以遞增順序排列。

篩選結果會以未排序的方式傳回。如果資料的排序很重要，您應該在 Firebase 傳回結果後對應用程式中的結果進行排序。

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 編碼資料會是包含兩個鍵的物件：路徑和資料路徑指向相對於要求網址的位置用戶端應針對資料中的每個鍵，將快取中的對應金鑰替換為訊息中該鍵的資料
保持運作	這個事件的資料為空值，您無須採取任何行動
取消	這個事件的資料為 null 如果 Firebase 即時資料庫安全性規則導致系統停止在要求的位置讀取資料，系統就會傳送這個事件
驗證已撤銷	這個事件的資料是字串，用來指出憑證已過期提供的驗證參數失效時，系統就會傳送這個事件

以下是伺服器可能會傳送的一系列事件範例：

// 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 相關的第三方包裝函式。