データの取得

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

準備

Firebase Realtime Database を使用するには、Firebase プロジェクトを作成してから、Firebase Unity SDK パッケージを Unity プロジェクトに追加する必要があります。

設定

前提条件

Android

iOS

  • Unity 5.0 以降
  • Xcode 7.0 以降

Unity プロジェクトをまだ用意していない場合は、いずれかのクイックスタート サンプルをダウンロードし、特定の Firebase 機能をお試しいただけます。クイックスタートを使用する場合は、次のステップでバンドル識別子が必要になるため、プロジェクト設定からバンドル識別子を忘れずに取得してください。

Firebase コンソールでアプリを設定する

アプリに Firebase を追加するには、Firebase プロジェクトと、アプリ用の Firebase 設定ファイルが必要です。

Firebase プロジェクトをまだ用意していない場合は、Firebase コンソールで Firebase プロジェクトを作成します。モバイルアプリと関連付けられた既存の Google プロジェクトがある場合は、[Google プロジェクトをインポート] をクリックします。それ以外の場合は、[新規プロジェクトを作成] をクリックします。

Android

  1. [Android アプリに Firebase を追加] をクリックし、設定手順に沿って操作します。既存の Google プロジェクトをインポートする場合、このステップは自動的に実行されることがあります。その場合は、設定ファイルをダウンロードするだけでかまいません。
  2. プロンプトが表示されたら、アプリのパッケージ名を入力します。必ずアプリで使用しているパッケージ名を入力してください。パッケージ名を設定できるのは、アプリを Firebase プロジェクトに追加するときだけです。
  3. 指示されたら google-services.json ファイルをダウンロードします。このファイルはいつでも再ダウンロードできます。
  4. このファイルを、プロジェクトのアセット フォルダ内の任意の場所にコピーします。

iOS

  1. [iOS アプリに Firebase を追加] をクリックして設定手順に沿って操作します。既存の Google プロジェクトをインポートする場合、このステップは自動的に実行されることがあります。その場合は、設定ファイルをダウンロードするだけでかまいません。
  2. プロンプトが表示されたら、アプリのバンドル ID を入力してください。必ずアプリで使用しているバンドル ID を入力してください。バンドル ID を設定できるのは、アプリを Firebase プロジェクトに追加するときだけです。
  3. 指示されたら GoogleService-Info.plist ファイルをダウンロードします。このファイルはいつでも再ダウンロードできます。
  4. プロジェクトに GoogleService-Info.plist ファイルを追加します。

  5. Firebase コンソールからダウンロードした GoogleService-Info.plist を、Unity プロジェクトの任意のフォルダにドラッグします。

アプリに Firebase Unity SDK を追加する

  1. Firebase Unity SDK をダウンロードします。
  2. [Assets] > [Import Package] > [Custom Package] メニュー項目を選択します。
  3. 先にダウンロードした Firebase Unity SDK から FirebaseDatabase.unitypackage パッケージをインポートします。
  4. [Import Unity Package] ウィンドウが表示されたら [Import] ボタンをクリックします。

アプリをビルドする

Android

  1. [File] > [Build Settings] メニュー項目を選択します。
  2. [Platform] リストから [Android] を選択します。
  3. [Switch Platform] をクリックし、ターゲット プラットフォームとして [Android] を選択します。
  4. Unity ステータスバーの右下隅にあるスピナー(コンパイル中)アイコンが停止するまで待ちます。
  5. [Build and Run] をクリックします。

iOS

  1. [File] > [Build Settings] メニュー項目を選択します。
  2. [Platform] リストから [iOS] を選択します。
  3. [Switch Platform] をクリックし、ターゲット プラットフォームとして [iOS] を選択します。
  4. Unity ステータスバーの右下隅にあるスピナー(コンパイル中)アイコンが停止するまで待ちます。
  5. [Build and Run] をクリックします。

データの取得

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

DatabaseReference を取得する

データベースからデータを読み取るには、次に示す DatabaseReference のインスタンスが必要です。

using Firebase;
using Firebase.Database;
using Firebase.Unity.Editor;

public class MyScript: MonoBehaviour {
  void Start() {
    // Set up the Editor before calling into the realtime database.
    FirebaseApp.DefaultInstance.SetEditorDatabaseUrl("https://YOUR-FIREBASE-APP.firebaseio.com/");

    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

データの 1 回読み取り

GetValueAsync メソッドを使用して、特定のパスにあるコンテンツの静的スナップショットを 1 回読み取ることができます。タスクの結果には、その場所にあるすべてのデータ(子のデータも含む)を含んでいるスナップショットが含まれます。データが存在しない場合、返されるスナップショットは null です。

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWith(task =&gt {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

イベントをリッスンする

データの変更をサブスクライブするイベント リスナーを追加できます。

イベント 一般的な使用方法
ValueChanged パスのコンテンツ全体に対する変更の読み取りとリッスンを行います。
ChildAdded アイテムのリストを取得するか、アイテムのリストへの追加がないかリッスンします。ChildChangedChildRemoved と併用して、リストに対する変更をモニタリングすることをおすすめします。
ChildChanged リスト内のアイテムに対する変更がないかリッスンします。ChildAddedChildRemoved と併用して、リストに対する変更をモニタリングします。
ChildRemoved リストから削除されるアイテムがないかリッスンします。ChildAddedChildChanged と併用して、リストに対する変更をモニタリングします。
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() の場合と同じです。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。