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

正在擷取資料
bookmark_border 透過集合功能整理內容你可以依據偏好儲存及分類內容。

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