データを保存する

始める前に

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

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

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

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

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

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

データの保存

Firebase Realtime Database にデータを書き込む方法は次の 5 つです。

メソッド 一般的な使用例
SetValueAsync() 定義されたパスに対してデータの書き込みまたは置換を行います（例: users/<user-id>/<username>）。
SetRawJsonValueAsync() 未加工の JSON を使用してデータの書き込みまたは置換を行います（例: users/<user-id>/<username>）。
Push() データのリストに追加します。Push() を呼び出すたびに、user-scores/<user-id>/<unique-score-id> のような一意の識別子としても使用できる一意のキーが生成されます。
UpdateChildrenAsync() データのすべてを置換することなく、定義済みのパスのキーの一部を更新します。
RunTransaction() 同時更新によって破損する可能性がある複合データを更新します。

DatabaseReference を取得する

データベースにデータを書き込むには、DatabaseReference のインスタンスが必要です。

using Firebase;
using Firebase.Database;

public class MyScript: MonoBehaviour {
  void Start() {
    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

参照でのデータの書き込み、更新、削除

基本的な書き込みオペレーション

基本的な書き込みオペレーションでは、SetValueAsync() を使用してデータを特定の参照に保存できます。そのパスにある既存のデータが置換されます。このメソッドを使用すると、次のような、使用可能な JSON 型に対応する型を渡すことができます。

  • string
  • long
  • double
  • bool
  • Dictionary<string, Object>
  • List<Object>

型付きの C# オブジェクトを使用する場合は、組み込みの JsonUtility.ToJson() を使用してオブジェクトを未加工の JSON に変換し、SetRawJsonValueAsync() を呼び出します。たとえば、次のような User クラスがあるとします。

public class User {
    public string username;
    public string email;

    public User() {
    }

    public User(string username, string email) {
        this.username = username;
        this.email = email;
    }
}

次のように SetRawJsonValueAsync() でユーザーを追加できます。

private void writeNewUser(string userId, string name, string email) {
    User user = new User(name, email);
    string json = JsonUtility.ToJson(user);

    mDatabaseRef.Child("users").Child(userId).SetRawJsonValueAsync(json);
}

この方法で SetValueAsync() または SetRawJsonValueAsync() を使用すると、指定された場所にあるデータ（子ノードを含む）が上書きされます。ただし、オブジェクト全体を書き換えずに子を更新することもできます。ユーザーに自分のプロフィールの更新を許可する場合、次のように username を更新できます。

mDatabaseRef.Child("users").Child(userId).Child("username").SetValueAsync(name);

リストへのデータの追加

マルチユーザー アプリケーションでリストにデータを追加するには Push() メソッドを使用します。Push() メソッドは指定した Firebase 参照に新しい子が追加されるたびに、一意のキーを生成します。この自動生成されたキーをリスト内の新しい各要素に使用することで、書き込みの競合を伴わずに複数のクライアントが同時に子を同じ場所に追加できます。Push() によって生成される一意のキーはタイムスタンプに基づいているため、リストのアイテムは自動的に時系列で並べ替えられます。

Push() メソッドによって返された新しいデータを参照することで、子の自動生成されたキーの値を取得することも、子のデータを設定することもできます。Push() 参照の Key を呼び出すと、自動生成されたキーの値が返されます。

特定のフィールドの更新

他の子ノードを上書きすることなく、ノードの特定の複数の子に同時に書き込むには、UpdateChildrenAsync() メソッドを使用します。

UpdateChildrenAsync() の呼び出し時に、キーのパスを指定して下位レベルの子の値を更新できます。スケーラビリティを向上させるためにデータが複数の場所に保存されている場合、データのファンアウトを使用してそのデータのすべてのインスタンスを更新できます。たとえば、次のようにゲームで LeaderboardEntry クラスが定義されているとします。

public class LeaderboardEntry {
    public string uid;
    public int score = 0;

    public LeaderboardEntry() {
    }

    public LeaderboardEntry(string uid, int score) {
        this.uid = uid;
        this.score = score;
    }

    public Dictionary<string, Object> ToDictionary() {
        Dictionary<string, Object> result = new Dictionary<string, Object>();
        result["uid"] = uid;
        result["score"] = score;

        return result;
    }
}

LeaderboardEntry を作成するのと同時に、それを最新のスコアフィードとユーザー自身のスコアリストに更新するには、ゲームで次のようなコードを使用します。

private void WriteNewScore(string userId, int score) {
    // Create new entry at /user-scores/$userid/$scoreid and at
    // /leaderboard/$scoreid simultaneously
    string key = mDatabase.Child("scores").Push().Key;
    LeaderBoardEntry entry = new LeaderBoardEntry(userId, score);
    Dictionary<string, Object> entryValues = entry.ToDictionary();

    Dictionary<string, Object> childUpdates = new Dictionary<string, Object>();
    childUpdates["/scores/" + key] = entryValues;
    childUpdates["/user-scores/" + userId + "/" + key] = entryValues;

    mDatabase.UpdateChildrenAsync(childUpdates);
}

この例では、Push() を使用して、/scores/$key にある全ユーザーのエントリが格納されているノード内にエントリを作成すると同時に、Key でキーを取得しています。その後、このキーを使用して、/user-scores/$userid/$key にあるユーザーのスコアに別のエントリを作成できます。

これらのパスを使用すると、上記の例で両方の場所に新しいエントリを作成したように、UpdateChildrenAsync() を 1 回呼び出すだけで JSON ツリー内の複数の場所に対して更新を同時に実行できます。この方法による同時更新はアトミック（不可分）です。つまり、すべての更新が成功するか、すべての更新が失敗するかのどちらかです。

データの削除

データを削除する最も簡単な方法は、そのデータの場所への参照の RemoveValue() を呼び出すことです。

また、他の書き込みオペレーション（SetValueAsync() や UpdateChildrenAsync() など）の値として null を指定する方法でも削除できます。この方法と UpdateChildrenAsync() を併用すると、API を 1 回呼び出すだけで複数の子を削除できます。

データが commit（確定）されたタイミングの把握

Firebase Realtime Database サーバーにデータが commit されたタイミングを把握するには、継続を追加します。SetValueAsync() と UpdateChildrenAsync() はどちらも Task を返します。これを使用して、オペレーションが完了したタイミングを把握できます。呼び出しがなんらかの理由で正常に完了しなかった場合、Task の IsFaulted が true になり、Exception プロパティがその理由を示します。

トランザクションとしてのデータの保存

増分カウンタなど、同時変更によって破損する可能性があるデータを操作する場合は、トランザクション オペレーションを使用します。このオペレーションでは Func を指定します。この Func は更新用の関数であり、データの現在の状態を引数として取り、書き込む新しい状態を返します。新しい値が正常に書き込まれる前に別のクライアントがその場所に書き込んだ場合、現在の新しい値を使用して更新用の関数が再度呼び出され、書き込みが再試行されます。

例えば、ゲーム内でユーザーが上位の 5 つのスコアでリーダーボードを更新できるようにすることができます。

private void AddScoreToLeaders(string email, 
                               long score,
                               DatabaseReference leaderBoardRef) {

    leaderBoardRef.RunTransaction(mutableData => {
      List<object> leaders = mutableData.Value as List<object>

      if (leaders == null) {
        leaders = new List<object>();
      } else if (mutableData.ChildrenCount >= MaxScores) {
        long minScore = long.MaxValue;
        object minVal = null;
        foreach (var child in leaders) {
          if (!(child is Dictionary<string, object>)) continue;
          long childScore = (long)
                      ((Dictionary<string, object>)child)["score"];
          if (childScore < minScore) {
            minScore = childScore;
            minVal = child;
          }
        }
        if (minScore > score) {
          // The new score is lower than the existing 5 scores, abort.
          return TransactionResult.Abort();
        }

        // Remove the lowest score.
        leaders.Remove(minVal);
      }

      // Add the new high score.
      Dictionary<string, object> newScoreMap =
                       new Dictionary<string, object>();
      newScoreMap["score"] = score;
      newScoreMap["email"] = email;
      leaders.Add(newScoreMap);
      mutableData.Value = leaders;
      return TransactionResult.Success(mutableData);
    });
}

トランザクションを使用することで、複数のユーザーが同時にスコアを記録した場合や、クライアントのデータが古くなった場合でも、リーダーボードを正確に保ちます。トランザクションが拒否された場合、サーバーは現在の値をクライアントに返します。クライアントは更新された値でトランザクションを再度実行します。この処理は、トランザクションが受け入れられるか、試行の回数が上限に達するまで繰り返されます。

オフラインでのデータの書き込み

クライアントでネットワーク接続が切断された場合でも、アプリは引き続き適切に機能します。

Firebase データベースに接続しているクライアントはそれぞれ、アクティブ データの内部バージョンを独自に保持しています。データが書き込まれると、まず、このローカル バージョンに書き込まれます。次に Firebase クライアントは、「ベスト エフォート」ベースでそのデータをリモート データベース サーバーや他のクライアントと同期します。

その結果、データベースへの書き込みが発生すると、実際にサーバーへデータが書き込まれるよりも早く、ローカル イベントが直ちにトリガーされます。つまり、ネットワークのレイテンシや接続に関係なく、アプリは応答性の高い状態を維持します。

接続が再確立されると、アプリは適切な一連のイベントを受け取り、クライアントが現在のサーバー状態と同期されます。この処理のためにカスタムコードを記述する必要はありません。

次のステップ