本文將說明擷取資料的基本概念,以及如何排序和篩選 Firebase 資料。
事前準備
如要使用 Realtime Database, 請先完成下列步驟:
註冊 Unity 專案並設定使用 Firebase。
如果 Unity 專案已使用 Firebase,則專案已註冊並設定 Firebase。
如果沒有 Unity 專案,可以下載範例應用程式。
將 Firebase Unity SDK (具體來說是
FirebaseDatabase.unitypackage
) 新增至 Unity 專案。
請注意,將 Firebase 新增至 Unity 專案時,您需要在Firebase控制台和開啟的 Unity 專案中執行工作 (例如從控制台下載 Firebase 設定檔,然後移至 Unity 專案)。
正在擷取資料
您可以呼叫 GetValueAsync() 一次,或附加至 FirebaseDatabase
參照的事件,藉此擷取 Firebase 資料。事件監聽器會針對資料的初始狀態呼叫一次,並且在資料變更時會再次呼叫。
取得 DatabaseReference
如要從資料庫讀取資料,您需要 DatabaseReference
的執行個體:
using Firebase; using Firebase.Database; using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread public class MyScript: MonoBehaviour { void Start() { // Get the root reference location of the database. DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference; } }
讀取資料一次
您可以使用 GetValueAsync
方法,讀取指定路徑內容的靜態快照一次。工作結果會包含快照,其中含有該位置的所有資料,包括子項資料。如果沒有資料,傳回的快照會是 null
。
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .GetValueAsync().ContinueWithOnMainThread(task => { if (task.IsFaulted) { // Handle the error... } else if (task.IsCompleted) { DataSnapshot snapshot = task.Result; // Do something with snapshot... } });
接聽事件
您可以新增事件監聽器,訂閱資料變更:
活動 | 常見用途 |
---|---|
ValueChanged |
讀取及監聽對路徑完整內容的變更。 |
ChildAdded
| 擷取項目清單或聆聽項目清單的新增內容。
建議搭配 ChildChanged 和 ChildRemoved 使用,監控清單的變更。 |
ChildChanged |
監聽清單中項目的變更。搭配 ChildAdded 和 ChildRemoved 使用,即可監控清單的變更。 |
ChildRemoved |
監聽從清單中移除的項目。搭配 ChildAdded 和 ChildChanged 使用,即可監控清單的變更。 |
ChildMoved |
監聽有序清單中項目的順序變更。
ChildMoved 事件一律會接在導致項目順序變更的 ChildChanged 事件之後 (根據目前的排序方式)。 |
ValueChanged 事件
您可以使用 ValueChanged
事件,訂閱指定路徑的內容變更。附加接聽程式時,系統會觸發一次這個事件,之後每當資料 (包括子項) 變更時,系統也會觸發這個事件。事件回呼會傳遞包含該位置所有資料 (包括子項資料) 的快照。如果沒有資料,傳回的快照會是 null
。
以下範例說明遊戲如何從資料庫擷取排行榜的分數:
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
ValueChangedEventArgs
包含 DataSnapshot
,其中包含事件發生時資料庫中指定位置的資料。對快照呼叫 Value
會傳回代表資料的 Dictionary<string, object>
。如果該位置沒有任何資料,呼叫 Value
會傳回 null
。
在本例中,也會檢查 args.DatabaseError
,確認讀取作業是否已取消。舉例來說,如果用戶端沒有從 Firebase 資料庫位置讀取資料的權限,系統就會取消讀取作業。DatabaseError
會指出失敗原因。
日後您可以使用路徑相同的任何 DatabaseReference
取消訂閱事件。DatabaseReference
執行個體是暫時性的,可視為存取任何路徑和查詢的方式。
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged. }
子事件
當節點的子項發生特定作業時,系統會觸發子項事件,例如透過 Push()
方法新增子項,或是透過 UpdateChildrenAsync()
方法更新子項。這些方法結合使用,有助於監聽資料庫中特定節點的變更。舉例來說,遊戲可能會一併使用這些方法來監控遊戲會話的留言活動,如下所示:
var ref = FirebaseDatabase.DefaultInstance .GetReference("GameSessionComments"); ref.ChildAdded += HandleChildAdded; ref.ChildChanged += HandleChildChanged; ref.ChildRemoved += HandleChildRemoved; ref.ChildMoved += HandleChildMoved; } void HandleChildAdded(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildChanged(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildRemoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildMoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
ChildAdded
事件通常用於擷取 Firebase 資料庫中的項目清單。系統會為每個現有子項引發一次 ChildAdded
事件,然後每當有新子項新增至指定路徑時,也會引發一次事件。系統會將含有新子項資料的快照傳遞給監聽器。
每當子項節點遭到修改,系統就會引發 ChildChanged
事件。
包括對子節點後代的任何修改。這通常會與 ChildAdded
和 ChildRemoved
事件搭配使用,以回應項目清單的變更。傳遞至事件監聽器的快照包含子項的更新資料。
移除直接子項時,系統會觸發 ChildRemoved
事件。這通常會與 ChildAdded
和 ChildChanged
回呼搭配使用。傳遞至事件回呼的快照包含已移除子項的資料。
每當更新導致子項重新排序時,系統就會觸發 ChildMoved
事件。ChildChanged
這項功能適用於以 OrderByChild
或 OrderByValue
排序的資料。
排序及篩選資料
您可以使用 Realtime Database Query
類別,依鍵、值或子項的值擷取排序後的資料。您也可以將排序結果篩選為特定結果數,或是特定範圍的鍵或值。
排序資料
如要擷取排序後的資料,請先指定其中一個排序依據方法,決定結果的排序方式:
方法 | 用量 |
---|---|
OrderByChild() |
依指定子項鍵的值排序結果。 |
OrderByKey()
| 依子項鍵排序結果。 |
OrderByValue() |
依子項值排序結果。 |
一次只能使用一種排序依據方法。在同一項查詢中多次呼叫 order-by 方法會擲回錯誤。
以下範例說明如何訂閱依分數排序的分數排行榜。
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
這會定義查詢,與 valuechanged 事件監聽器搭配使用時,可將用戶端與資料庫中的排行榜同步處理,並依據每個項目的分數排序。如要進一步瞭解如何有效率地建構資料,請參閱「建構資料庫」。
對 OrderByChild()
方法的呼叫會指定子項鍵,用來排序結果。在本例中,結果會依據每個子項中 "score"
值的價值排序。如要進一步瞭解其他資料類型的排序方式,請參閱查詢資料的排序方式。
篩選資料
如要篩選資料,建構查詢時,您可以將任何限制或範圍方法與排序方法合併。
方法 | 用量 |
---|---|
LimitToFirst() |
設定要從排序結果清單開頭傳回的項目數量上限。 |
LimitToLast() |
設定要從排序結果清單結尾傳回的項目數量上限。 |
StartAt() |
根據所選的排序依據方法,傳回大於或等於指定鍵或值的項目。 |
EndAt() |
根據所選的排序依據方法,傳回小於或等於指定鍵或值的項目。 |
EqualTo() |
根據所選的排序依據方法,傳回等於指定鍵或值的項目。 |
與排序方法不同,您可以合併多個限制或範圍函式。
舉例來說,您可以結合 StartAt()
和 EndAt()
方法,將結果限制在指定的值範圍內。
即使查詢只找到一個相符項目,快照仍會是清單,只是只包含一個項目。
限制結果數量
您可以使用 LimitToFirst()
和 LimitToLast()
方法,為指定的回呼設定要同步處理的子項數量上限。舉例來說,如果您使用 LimitToFirst()
將限制設為 100,一開始只會收到最多 100 個 ChildAdded
回呼。如果 Firebase 資料庫中儲存的項目少於 100 個,系統會為每個項目觸發 ChildAdded
回呼。
項目變更時,你會收到進入查詢的項目 ChildAdded
回呼,以及退出查詢的項目 ChildRemoved
回呼,因此總數會維持在 100。
舉例來說,下列程式碼會傳回排行榜的最高分數:
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score").LimitToLast(1) .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
依鍵或值篩選
您可以使用 StartAt()
、EndAt()
和 EqualTo()
,為查詢選擇任意的起點、終點和等效點。這項功能可用於資料分頁,或尋找具有特定值的子項目的項目。
查詢資料的排序方式
本節說明 Query
類別中各個排序依據方法如何排序資料。
OrderByChild
使用 OrderByChild()
時,包含指定子項鍵的資料會依下列順序排序:
- 指定子項鍵的
null
值會優先顯示。 - 接著是指定子項鍵的值為
false
的子項。如果多個子項的值為false
,系統會依鍵依字母順序排序。 - 接著是指定子項鍵的值為
true
的子項。如果多個子項的值為true
,系統會依鍵的字典順序排序。 - 接著是數值,並以遞增順序排序。如果多個子項的指定子項節點具有相同的數值,系統會依鍵排序。
- 字串會排在數字後面,並依字典順序遞增排序。如果多個子項在指定的子項節點中具有相同的值,系統會依鍵的字典順序排序。
- 物件會排在最後,並依鍵以遞增順序按字母排序。
OrderByKey
使用 OrderByKey()
排序資料時,系統會依鍵值以遞增順序傳回資料。
- 如果子項的鍵可剖析為 32 位元整數,則會先顯示這些子項,並依遞增順序排序。
- 接著是金鑰為字串值的子項,並依字典順序遞增排序。
OrderByValue
使用 OrderByValue()
時,子項會依值排序。排序條件與 OrderByChild()
相同,但會使用節點的值,而不是指定子項鍵的值。