本文說明擷取資料的基本概念,以及如何排序及篩選資料 Firebase 資料。
事前準備
使用前 即時資料庫, 請完成下列操作:
註冊 Unity 專案,並將其設定為使用 Firebase。
如果您的 Unity 專案已在使用 Firebase, 已完成註冊和設定程序。
如果您沒有 Unity 專案,可以 範例應用程式。
將 Firebase Unity SDK (特別是
FirebaseDatabase.unitypackage
) 新增至 Unity 專案
請注意,將 Firebase 新增至 Unity 專案時,必須一併執行以下兩者的工作: Firebase 控制台,在開啟的 Unity 專案中 (例如,您可以從控制台下載 Firebase 設定檔,然後 放入您的 Unity 專案中)。
正在擷取資料
系統會透過對 GetValueAsync() 的一次性呼叫或
附加至事件的 FirebaseDatabase
參照上。事件監聽器為
模型的初始狀態會呼叫一次,在資料變更時再次呼叫。
取得 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
排序的資料使用。
排序及篩選資料
您可以使用即時資料庫 Query
類別來擷取按照以下條件排序的資料:
索引鍵、值或子項的值你也可以篩選
在特定數量的結果或索引鍵範圍內排序的結果
輕鬆分配獎金
排序資料
如要擷取經過排序的資料,請先指定其中一種排序方法,以便 決定結果的排序方式:
方法 | 用量 |
---|---|
OrderByChild() |
按照指定子鍵的值排序結果。 |
OrderByKey()
| 按子項鍵排序結果。 |
OrderByValue() |
按照子項值排序結果。 |
一次只能使用「一個」排序方法。依訂單呼叫方法 重複計算錯誤。
以下範例說明如何訂閱分數 。
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 }
這會定義在與值變更事件監聽器合併使用的查詢時,所定義的查詢。 將用戶端與資料庫中排行榜同步,並依 分數。 如要進一步瞭解如何有效率地建立資料結構,請參閱 建立資料庫。
OrderByChild()
方法的呼叫會指定要排序的子項鍵
產生結果在此情況下,結果會按照 "score"
的值排序。
每個子項的值如要進一步瞭解其他資料類型的排序方式,
請參閱查詢資料的排序方式。
篩選資料
如要篩選資料,可以使用任何限製或範圍方法, 依順序排序查詢。
方法 | 用量 |
---|---|
LimitToFirst() |
設定從 結果的排序清單。 |
LimitToLast() |
設定從訂單結尾傳回的項目數量上限 結果清單。 |
StartAt() |
傳回大於或等於指定鍵或值的項目 視所選的訂單而定 |
EndAt() |
傳回小於或等於指定鍵或值的項目 視所選的訂單而定 |
EqualTo() |
傳回與指定鍵或值相等的項目 視所選的訂單而定 |
有別於逐一排序的方法,您可以合併多個限製或範圍函式。
例如,您可以結合 StartAt()
和 EndAt()
方法
將結果傳回指定範圍內的值
即使查詢只有一個符合項目,快照仍會 清單;只會包含單一項目
限制結果數量
您可以使用 LimitToFirst()
和 LimitToLast()
方法設定
要為特定回呼同步處理的子項數量上限。舉例來說
您使用 LimitToFirst()
將限制設為 100,一開始只會接收
至 100 個 ChildAdded
回呼。如果您儲存的項目少於 100 個
Firebase 資料庫,每個項目都會觸發 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()
相同,但節點值
,而不是指定子鍵的值。