正在擷取資料

使用 GET 讀取資料

我們可以向其網址端點發出 GET 要求,讀取 Firebase 資料庫中的資料。接著,我們將繼續使用上一節的網誌範例,並讀取所有網誌文章資料:

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

成功的要求會以 200 OK HTTP 狀態碼表示,回應中也會包含我們要擷取的資料。

新增 URI 參數

當 REST API 從 Firebase 資料庫讀取資料時,會接受多個查詢參數。以下列出最常用的參數。如需完整清單,請參閱 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 錯誤。當您預期資料傳輸量較小,且不想等待太久才能擷取可能龐大的子集時,這項功能就格外實用。實際讀取時間可能會因資料大小和快取而異。

請使用下列格式指定 timeouts3ms3s3min,並附上數字和單位。如果未指定,系統會套用 15min 的最大 timeout。如果 timeout 不是正值,或超過上限,系統會拒絕要求並傳回 HTTP 400 錯誤。在以下範例中,GET 要求包含 10 秒的 timeout

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

篩選資料

我們可以建立查詢,根據各種因素篩選資料。首先,您必須使用 orderBy 參數指定資料篩選方式。接著,您可以將 orderBy 與其他五個參數結合:limitToFirstlimitToLaststartAtendAtequalTo

由於 Firebase 的所有成員都認為恐龍很酷,我們會使用恐龍資料的範例資料庫片段,說明如何篩選資料:

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

我們可以透過三種方式篩選資料:依據子項鍵。查詢會以其中一個參數開頭,然後必須與下列一或多個參數結合:startAtendAtlimitToFirstlimitToLastequalTo

依指定子項鍵篩選

我們可以將該鍵傳遞至 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" 參數,按照節點的鍵篩選節點。以下範例會擷取名稱開頭為 am 的所有恐龍:

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、布林值、字串和物件值,請參閱「資料排序方式」。

複雜篩選

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

限制查詢

limitToFirstlimitToLast 參數用於設定可接收資料的子項數量上限。如果我們設定 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'

範圍查詢

使用 startAtendAtequalTo 時,我們可以為查詢選擇任意起點和終點。舉例來說,如果我們想找出所有身高至少三公尺的恐龍,可以結合 orderBystartAt

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'

我們可以結合 startAtendAt,限制查詢的兩端。以下範例會找出名稱開頭為「b」的所有恐龍:

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

當您需要分頁顯示資料時,範圍查詢也相當實用。

全面整合使用

我們可以結合所有這些技巧來建立複雜的查詢。舉例來說,假設您想找出所有身高低於或等於 Stegosaurus 的恐龍名稱:

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. 物件會列在最後,並依字母順序依鍵遞增排序。
系統會以無序方式傳回篩選後的結果。如果資料的順序很重要,您應該在結果從 Firebase 傳回後,在應用程式中對結果進行排序。

orderBy="$key"

使用 orderBy="$key" 參數排序資料時,系統會依鍵值依序傳回資料,如下所示。請注意,鍵只能是字串。

  1. 可解析為 32 位元整數的鍵會先排在前面,並以遞增順序排序。
  2. 接著是使用字串值做為鍵的子項,以字典順序遞增排序。

orderBy="$value"

使用 orderBy="$value" 參數排序資料時,子項會依據其值排序。排序條件與依子項鍵排序的資料相同,只是使用節點值,而非指定子項鍵的值。

orderBy="$priority"

使用 orderBy="$priority" 參數排序資料時,子項的排序會根據其優先順序和鍵決定,如下所示。請注意,優先順序值只能是數字或字串。

  1. 優先順序為 0 的子項會優先處理。
  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

伺服器可能會傳送下列事件:

put 經過 JSON 編碼的資料會是物件,其中包含兩個鍵:路徑和資料
路徑會指向相對於要求網址的位置
用戶端應將快取中該位置的所有資料,替換為訊息中提供的資料
patch JSON 編碼資料會是物件,其中包含兩個鍵:路徑和資料
路徑會指向相對於要求網址的位置
對於資料中的每個鍵,用戶端應將快取中的對應鍵,替換為訊息中該鍵的資料
保持運作 此事件的資料為空值,因此無須採取任何行動
取消 此事件的資料為空值
如果 Firebase Realtime Database Security Rules 導致無法再讀取要求位置,系統就會傳送此事件
auth_revoked 這個事件的資料是字串,表示憑證已過期
當提供的驗證參數不再有效時,系統就會傳送這個事件

以下是伺服器可能傳送的一組事件範例:

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