本頁面由 Cloud Translation API 翻譯而成。

正在擷取資料

本文說明擷取資料的基本概念，以及如何排序及篩選資料 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() 相同，但節點值，而不是指定子鍵的值。