データの取得

このドキュメントでは、データの取得に関する基本と、Firebase データの並べ替えとフィルタリングの方法について説明します。

始める前に

Realtime Database を使用するには、次の作業が必要です。

  • Firebase を使用するように Unity プロジェクトを登録して構成する。

    • Unity プロジェクトですでに Firebase を使用している場合、この登録と構成はすでに行われています。

    • Unity プロジェクトがない場合は、サンプルアプリをダウンロードできます。

  • Unity プロジェクトに Firebase Unity SDK（具体的には FirebaseDatabase.unitypackage）を追加する。

Firebase を Unity プロジェクトに追加するには、Firebase コンソールと開いている Unity プロジェクトの両方でタスクを行う必要があります（コンソールから Firebase 構成ファイルをダウンロードし、それを Unity プロジェクトに移動するなど）。

データの取得

Firebase データは、GetValueAsync() へのワンタイム コールまたは FirebaseDatabase 参照でイベントにアタッチして取得します。イベント リスナーはデータの初期状態で 1 回呼び出されます。さらに、データが変更されると、そのたびに再度呼び出されます。

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;
  }
}

データの 1 回読み取り

GetValueAsync メソッドを使用して、特定のパスにあるコンテンツの静的スナップショットを 1 回だけ読み取ることができます。タスクの結果には、その場所にあるすべてのデータ（子のデータも含む）を含んでいるスナップショットが含まれます。データが存在しない場合、返されるスナップショットは 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 イベントは常に、（現在の order-by メソッドに基づく）アイテムの並べ替え変更の原因となった ChildChanged イベントに後続します。

ValueChanged イベント

ValueChanged イベントを使用して、特定のパスのコンテンツの変更をサブスクライブできます。このイベントはリスナーがアタッチされたときに 1 回トリガーされます。さらに、データ（子も含む）が変更されると、そのたびに再びトリガーされます。イベントのコールバックには、その場所にあるすべてのデータ（子のデータも含む）を含んでいるスナップショットが渡されます。データが存在しない場合、返されるスナップショットは 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.
    }

child イベント

Push() メソッドによる新しい子の追加や、UpdateChildrenAsync() メソッドによる子の更新など、ノードの子に対して発生した特定のオペレーションに応じて child イベントがトリガーされます。それぞれのイベントを組み合わせると、データベース内の特定のノードに対する変更をリッスンする場合に役立つことがあります。たとえばゲームでは、以下に示すように、これらのメソッドを組み合わせて使用してゲーム セッションのコメントでのアクティビティをモニタリングできます。

      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 イベントは既存の子ごとに 1 回発生します。さらに、指定されたパスに新しい子が追加されると、そのたびに再び発生します。リスナーには、新しい子のデータを含んでいるスナップショットが渡されます。

子ノードが変更されると、そのたびに ChildChanged イベントが発生します。この変更には、子ノードの子孫に対する変更も含まれます。これは通常、アイテムのリストに対する変更に応答するために、ChildAdded イベントおよび ChildRemoved イベントと組み合わせて使用します。イベント リスナーに渡されるスナップショットには、子の更新済みデータが含まれています。

ChildRemoved イベントは直接の子が削除されるとトリガーされます。通常は、ChildAdded および ChildChanged のコールバックと組み合わせて使用します。イベントのコールバックに渡されるスナップショットには、削除された子のデータが含まれています。

ChildMoved イベントは、子の再並べ替えが起きる更新によって ChildChanged イベントがトリガーされると、そのたびにトリガーされます。このイベントは OrderByChild または OrderByValue によるデータの並べ替えで使用されます。

データの並べ替えとフィルタリング

Realtime Database Query クラスを使用すると、キー、値、または子の値で並べ替えられたデータを取得できます。また、並べ替えられた結果を、特定の件数またはある範囲のキーや値に限定するようフィルタリングできます。

データを並べ替える

並べ替えられたデータを取得するには、最初にいずれかの order-by メソッドを指定して、結果の並べ替え方法を決定します。

メソッド 用途
OrderByChild() 指定した子キーの値で結果を並べ替えます。
OrderByKey() 子キーで結果を並べ替えます。
OrderByValue() 子の値によって結果を並べ替えます。

同時に使用できる order-by メソッドは 1 つだけです。同じクエリで 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" の値によって並べ替えられます。他の種類のデータを並べ替える方法の詳細については、クエリデータが並べ替えられる仕組みをご覧ください。

データのフィルタリング

データをフィルタリングするために、クエリの構築時に、制限メソッドまたは範囲メソッドのいずれかを order-by メソッドと組み合わせることができます。

メソッド 用途
LimitToFirst() 並べ替えられた結果リストの先頭から返すアイテムの最大数を設定します。
LimitToLast() 並べ替えられた結果リストの末尾から返すアイテムの最大数を設定します。
StartAt() 選択した order-by メソッドに応じて、指定したキーまたは値以上のアイテムを返します。
EndAt() 選択した order-by メソッドに応じて、指定したキーまたは値以下のアイテムを返します。
EqualTo() 選択した order-by メソッドに応じて、指定したキーまたは値に等しいアイテムを返します。

order-by メソッドとは異なり、複数の制限関数または範囲関数を組み合わせることができます。たとえば、StartAt() メソッドと EndAt() メソッドを組み合わせて、結果を特定の範囲の値に制限できます。

クエリで一致が 1 つしかない場合でも、スナップショットは 1 つのアイテムだけを含むリストです。

結果の個数を制限する

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 クラスのそれぞれの order-by メソッドでデータがどのように並べ替えられるのかを説明します。

OrderByChild

OrderByChild() を使用すると、指定した子キーを含むデータは次のように並べ替えられます。

  1. 指定した子キーに null 値を持つ子が最初に来ます。
  2. 指定した子キーの値が false である子が次に来ます。複数の子が値 false を持つ場合、キーで辞書順に並べ替えられます。
  3. 指定した子キーの値が true である子が次に来ます。複数の子が値 true を持つ場合、キーで辞書順に並べ替えられます。
  4. 数値を持つ子が次に来ます。ただし、昇順に並べ替えられます。指定した子ノードに同じ数値を持つ複数の子がある場合、キーで並べ替えられます。
  5. 文字列は数値の後に来て、辞書順で昇順に並べ替えられます。指定した子ノードに同じ値を持つ複数の子がある場合、キーで辞書順に並べ替えられます。
  6. オブジェクトが最後に来て、キー名の辞書順で昇順に並べ替えられます。

OrderByKey

OrderByKey() を使用してデータを並べ替えると、キー名で昇順にデータが返されます。

  1. 32 ビット整数として解析できるキーを持つ子が最初に来ます。ただし、昇順に並べ替えられます。
  2. 文字列値をキーとして持つ子が次に来ます。ただし、辞書順で昇順に並べ替えられます。

OrderByValue

OrderByValue() を使用すると、子がその値で並べ替えられます。並べ替えの条件は、指定した子キーの値の代わりにノードの値が使用されるという点を除いて、OrderByChild() の場合と同じです。