正在擷取資料

使用 GET 讀取資料

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

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

如果要求成功，系統會傳回 200 OK HTTP 狀態碼，且回應會包含我們擷取的資料。

新增 URI 參數

從 Firebase 資料庫讀取資料時，REST API 會接受多個查詢參數。以下列出最常用的參數。如需完整清單，請參閱 REST API 參考資料。

授權

auth 要求參數可讓您存取受 Firebase Realtime Database Security Rules 保護的資料，且所有要求類型都支援此參數。引數可以是 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。

篩選後的資料會以未排序的形式傳回： 使用 REST API 時，篩選後的結果會以未定義的順序傳回，因為 JSON 解譯器不會強制執行任何排序。如果資料順序很重要，請在 Firebase 傳回結果後，在應用程式中排序。

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 參數會擲回錯誤。

在 Firebase Realtime Database Security Rules 中新增索引： 如果您在應用程式中使用 orderBy，則必須透過 Firebase Realtime Database Security Rules 中的 .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'

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

將索引新增至 Firebase Realtime Database Security Rules： 如果您在應用程式中使用 orderBy="$value"，則必須在適當的索引中將 .value 新增至規則。 參閱 .indexOn 規則的說明文件，瞭解詳情。

複雜篩選

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

限制查詢

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 包含在內，也就是說「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 時，包含指定子項鍵的資料會依下列方式排序：

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" 參數排序資料時，子項的排序方式取決於其優先順序和鍵，如下所示。請注意，優先順序值只能是數字或字串。

數字優先順序會以 IEEE 754 雙精度浮點數的形式儲存及排序。 鍵一律會儲存為字串，且只有在可剖析為 32 位元整數時，才會視為數值。

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

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

put	JSON 編碼資料會是含有兩個鍵的物件：path 和 data path 指向相對於要求網址的位置 用戶端應將快取中該位置的所有資料，替換為訊息中提供的資料
patch	JSON 編碼資料會是含有兩個鍵的物件：path 和 data path 指向相對於要求網址的位置 對於 data 中的每個鍵，用戶端應將快取中的對應鍵替換為訊息中該鍵的資料
保持運作	這個事件的資料為空值，無須採取任何行動
取消	這個事件的資料為空值 如果 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 的第三方包裝函式。