正在擷取資料

使用 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 時，含有指定值的資料 子項金鑰的順序如下：

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

orderBy="$key"

使用 orderBy="$key" 參數排序資料時，系統會傳回資料 ，如下所示。請注意，金鑰只能包含字串。

1. 具有索引鍵可剖析為 32 位元整數的子項，其會先以遞增方式排序 順序。
2. 具有字串值的子項，在其索引鍵出現時，則按照字母順序遞增排序 順序。

orderBy="$value"

使用 orderBy="$value" 參數排序資料時，子項會是 來排序。排序條件與子項鍵排序的資料相同。 但會使用節點的值取代指定子鍵的值。

orderBy="$priority"

使用 orderBy="$priority" 參數排序資料時， 子項取決於其優先順序和索引鍵，如下所示。請記住，優先級值 只能是數字或字串。

1. 沒有優先順序 (預設) 的子項會先顯示。
2. 下一個優先順序為數字的孩子。這些項目會依優先順序排序，由小到大。
3. 以字串做為其優先順序的子項會持續排列。排序依據為字母順序 優先順序。
4. 如果兩個子項有相同的優先順序 (包括無優先順序)，就會按照索引鍵排序。 數字鍵會先排序 (以數字排序)，接著是其餘的鍵 (以字典順序排序)。

如要進一步瞭解優先順序，請參閱 API 參考資料。

透過 REST API 串流

Firebase REST 端點支援 EventSource/伺服器傳送事件通訊協定，可輕鬆將變更串流傳送至 Firebase 資料庫中的單一位置。

如要開始直播，請完成下列事項：

1. 將用戶端的 Accept 標頭設為 text/event-stream
2. 採用 HTTP 重新導向，尤其是 HTTP 狀態碼 307
3. 如果 Firebase 資料庫位置需要auth 讀取權限

在回傳時，伺服器會傳送命名事件，因為要求的網址資料狀態會有所變更。這些郵件的結構符合 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 的第三方包裝函式。