本文檔介紹了檢索資料以及如何排序和過濾 Firebase 資料的基礎知識。
在你開始之前
確保您已設定應用程式並可以存取Get Started指南中所述的資料庫。
檢索資料
Firebase 資料透過一次呼叫GetValue()或附加到FirebaseDatabase參考上的ValueListener來檢索。值偵聽器在資料的初始狀態下被呼叫一次，並在資料發生變化時再次呼叫。
取得資料庫參考
若要將資料寫入資料庫，您需要一個DatabaseReference實例：
// Get the root reference location of the database.
firebase::database::DatabaseReference dbref = database->GetReference();
讀取一次數據
您可以使用GetValue()方法讀取給定路徑中內容的靜態快照一次。任務結果將包含一個快照，其中包含該位置的所有數據，包括子數據。如果沒有數據，則傳回的快照為null 。
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").GetValue();
此時請求已發出，但我們必須等待 Future 完成才能讀取該值。由於遊戲通常在循環中運行，並且比其他應用程式更少回調驅動，因此您通常會輪詢是否完成。
// In the game loop that polls for the result...
if (result.status() != firebase::kFutureStatusPending) {
if (result.status() != firebase::kFutureStatusComplete) {
LogMessage("ERROR: GetValue() returned an invalid result.");
// Handle the error...
} else if (result.error() != firebase::database::kErrorNone) {
LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
result.error_message());
// Handle the error...
} else {
firebase::database::DataSnapshot snapshot = result.result();
// Do something with the snapshot...
}
}
這顯示了一些基本的錯誤檢查，請參閱firebase::Future參考以獲取有關錯誤檢查的更多資訊以及確定結果何時準備就緒的方法。
監聽事件
您可以新增偵聽器來訂閱資料變更：
ValueListener基底類別
| 打回來 | 典型用法 |
|---|---|
OnValueChanged | 讀取並監聽路徑整個內容的變更。 |
OnChildListener基底類別
OnChildAdded | 檢索項目清單或偵聽項目清單的新增內容。建議與OnChildChanged和OnChildRemoved一起使用來監視清單的變更。 |
OnChildChanged | 監聽清單中項目的變更。與OnChildAdded和OnChildRemoved一起使用來監視清單的變更。 |
OnChildRemoved | 偵聽從清單中刪除的項目。與OnChildAdded和OnChildChanged一起使用來監視清單的變更。 |
OnChildMoved | 偵聽有序清單中項目順序的變更。由於專案的順序發生變化（基於目前的排序方式）， OnChildMoved回調始終遵循OnChildChanged回調。 |
值監聽器類
您可以使用OnValueChanged回呼來訂閱給定路徑中內容的變更。當附加偵聽器時會觸發此回調一次，每次資料（包括子項目）發生變更時都會觸發一次。向回調傳遞包含該位置的所有資料（包括子資料）的快照。如果沒有數據，則傳回的快照為null 。
以下範例示範了一個從資料庫中檢索排行榜分數的遊戲：
class LeadersValueListener : public firebase::database::ValueListener {
public:
void OnValueChanged(
const firebase::database::DataSnapshot& snapshot) override {
// Do something with the data in snapshot...
}
void OnCancelled(const firebase::database::Error& error_code,
const char* error_message) override {
LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
error_message);
}
};
// Elsewhere in the code...
LeadersValueListener* listener = new LeadersValueListener();
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").AddValueListener(listener);
Future<DataSnaphot>結果包含事件發生時資料庫中指定位置的資料。對快照呼叫value()傳回表示資料的Variant 。
在此範例中，也重寫了OnCancelled方法以查看讀取是否被取消。例如，如果用戶端無權從 Firebase 資料庫位置讀取，則可以取消讀取。 database::Error將指示發生故障的原因。
子監聽器類別
子事件是為了回應節點子節點發生的特定操作而觸發的，這些操作例如透過PushChild()方法新增的新子節點或透過UpdateChildren()方法更新的子節點。這些中的每一個都可以用於偵聽資料庫中特定節點的變更。例如，遊戲可能會同時使用這些方法來監視遊戲會話評論中的活動，如下所示：
class SessionCommentsChildListener : public firebase::database::ChildListener {
public:
void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
const char* previous_sibling) override {
// Do something with the data in snapshot ...
}
void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
const char* previous_sibling) override {
// Do something with the data in snapshot ...
}
void OnChildRemoved(
const firebase::database::DataSnapshot& snapshot) override {
// Do something with the data in snapshot ...
}
void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
const char* previous_sibling) override {
// Do something with the data in snapshot ...
}
void OnCancelled(const firebase::database::Error& error_code,
const char* error_message) override {
LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
error_code, error_message);
}
};
// elsewhere ....
SessionCommentsChildListener* listener = new SessionCommentsChildListener();
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("GameSessionComments").AddChildListener(listener);
OnChildAdded回呼通常用於檢索 Firebase 資料庫中的項目清單。 OnChildAdded回調為每個現有子項呼叫一次，然後每次將新子項新增至指定路徑時再次呼叫。偵聽器會收到包含新子項目資料的快照。
每當修改子節點時都會呼叫OnChildChanged回調。這包括對子節點的後代的任何修改。它通常與OnChildAdded和OnChildRemoved呼叫結合使用，以回應項目清單的變更。傳遞給偵聽器的快照包含子層級的更新資料。
當直接子項被刪除時，會觸發OnChildRemoved回呼。它通常與OnChildAdded和OnChildChanged回調結合使用。傳遞給回呼的快照包含已刪除子項目的資料。
每當因導致子項重新排序的更新而引發OnChildChanged呼叫時，都會觸發OnChildMoved回呼。它與透過OrderByChild或OrderByValue排序的資料一起使用。
排序和過濾數據
您可以使用即時資料庫Query類別來擷取按鍵、按值或按子值排序的資料。您也可以將排序結果過濾為特定數量的結果或一系列鍵或值。
對資料進行排序
若要擷取排序的數據，請先指定排序方法之一來確定結果的排序方式：
| 方法 | 用法 |
|---|---|
OrderByChild() | 依指定子鍵的值對結果進行排序。 | OrderByKey() | 按子鍵對結果進行排序。 |
OrderByValue() | 依子值對結果進行排序。 |
您一次只能使用一種排序方式。在同一查詢中多次呼叫 order-by 方法會引發錯誤。
以下範例示範如何訂閱按分數排序的分數排行榜。
firebase::database::Query query =
dbRef.GetReference("Leaders").OrderByChild("score");
// To get the resulting DataSnapshot either use query.GetValue() and poll the
// future, or use query.AddValueListener() and register to handle the
// OnValueChanged callback.
這定義了一個firebase::Query ，當與ValueListener結合使用時，會將客戶端與資料庫中的排行榜同步，並按每個條目的分數排序。您可以在建立資料庫中閱讀有關有效建立資料的更多資訊。
對OrderByChild()方法的呼叫指定用於對結果進行排序的子鍵。在這種情況下，結果會依照每個子項中的"score"值排序。有關其他資料類型如何排序的詳細信息，請參閱查詢資料如何排序。
過濾數據
要過濾數據，您可以在建構查詢時將任何限製或範圍方法與排序方法結合。
| 方法 | 用法 |
|---|---|
LimitToFirst() | 設定從有序結果清單開頭傳回的最大項目數。 |
LimitToLast() | 設定從有序結果清單末尾傳回的最大項目數。 |
StartAt() | 根據所選的排序方法，傳回大於或等於指定鍵或值的項目。 |
EndAt() | 根據所選的排序方法，傳回小於或等於指定鍵或值的項目。 |
EqualTo() | 根據所選的排序方法，傳回等於指定鍵或值的項目。 |
與排序方法不同，您可以組合多個限製或範圍函數。例如，您可以組合StartAt()和EndAt()方法將結果限制為指定的值範圍。
即使查詢只有一個符合項，快照仍然是一個清單；它只包含一個項目。
限制結果數量
您可以使用LimitToFirst()和LimitToLast()方法來設定給定回呼要同步的子級的最大數量。例如，如果您使用LimitToFirst()將限制設為 100，則最初最多只會收到 100 個OnChildAdded回呼。如果您的 Firebase 資料庫中儲存的項目少於 100 個，則每個項目都會觸發OnChildAdded回呼。
當專案發生變更時，您會收到針對進入查詢的專案的OnChildAdded回調，以及針對退出查詢的專案OnChildRemoved回調，以便總數保持在 100。
例如，下面的程式碼會傳回排行榜的最高分：
firebase::database::Query query =
dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);
// To get the resulting DataSnapshot either use query.GetValue() and poll the
// future, or use query.AddValueListener() and register to handle the
// OnValueChanged callback.
按鍵或值過濾
您可以使用StartAt() 、 EndAt()和EqualTo()為查詢選擇任意起始點、結束點和等價點。這對於對資料進行分頁或尋找具有特定值的子項目非常有用。
查詢資料如何排序
本節說明如何透過Query類別中的每個 order-by 方法對資料進行排序。
OrderByChild
使用OrderByChild()時，包含指定子鍵的資料會依下列方式排序：
- 指定子鍵的值為
null子項排在第一位。 - 接下來是指定子鍵值為
false的子項。如果多個子項的值為false，則它們按鍵按字典順序排序。 - 接下來是指定子鍵值為
true的子項。如果多個子項的值為true，則它們按鍵按字典順序排序。 - 接下來是具有數值的子項，依升序排序。如果指定子節點的多個子節點具有相同的數值，則它們會按鍵排序。
- 字串位於數字之後，並依字典順序升序排序。如果指定子節點的多個子節點具有相同的值，則它們按鍵按字典順序排序。
- 物件排在最後，並依字典順序按鍵升序排序。
OrderByKey
當使用OrderByKey()對資料進行排序時，資料將按鍵升序傳回。
- 具有可解析為 32 位元整數的鍵的子項排在前面，按升序排序。
- 接下來是以字串值作為鍵的子項，依字典順序升序排列。
OrderByValue
使用OrderByValue()時，子項會依其值排序。排序標準與OrderByChild()中的相同，只是使用節點的值而不是指定子鍵的值。