Firebase Realtime Database for C++ でデータを保存する

スタートガイド

まだアプリをセットアップしてデータベースにアクセスしていない場合は、最初に Get Started ガイドをご覧ください。

DatabaseReference を取得する

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

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

データの保存

Firebase Realtime Database にデータを書き込むメソッドは次のように 4 種類あります。

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

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

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

基本的な書き込みオペレーションでは、SetValue() を使用してデータを特定の参照に保存できます。そのパスにある既存のデータが置換されます。このメソッドを使用して、以下をサポートするバリアント型を使用して JSON で受け入れられる型を渡すことができます。

  • Null（これはデータを削除します）
  • 整数（64 ビット）
  • 倍精度浮動小数点数
  • ブール値
  • 文字列
  • バリアントのベクトル
  • 文字列のバリアントへのマッピング

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

dbref.Child("users").Child(userId).Child("username").SetValue(name);

リストへのデータの追加

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

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

特定のフィールドの更新

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

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

class LeaderboardEntry {
  std::string uid;
  int score = 0;

 public:
  LeaderboardEntry() {
  }

  LeaderboardEntry(std::string uid, int score) {
    this->uid = uid;
    this->score = score;
  }

  std::map&ltstd::string, Object&gt ToMap() {
    std::map&ltstring, Variant&gt result = new std::map&ltstring, Variant&gt();
    result["uid"] = Variant(uid);
    result["score"] = Variant(score);

    return result;
  }
}

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

void WriteNewScore(std::string userId, int score) {
  // Create new entry at /user-scores/$userid/$scoreid and at
  // /leaderboard/$scoreid simultaneously
  std::string key = dbref.Child("scores").PushChild().GetKey();
  LeaderBoardEntry entry = new LeaderBoardEntry(userId, score);
  std::map&ltstd::string, Variant&gt entryValues = entry.ToMap();

  std::map&ltstring, Variant&gt childUpdates = new std::map&ltstring, Variant&gt();
  childUpdates["/scores/" + key] = entryValues;
  childUpdates["/user-scores/" + userId + "/" + key] = entryValues;

  dbref.UpdateChildren(childUpdates);
}

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

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

データの削除

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

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

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

Firebase Realtime Database サーバーにデータが commit されたタイミングを把握するには、Future の結果が成功したかどうかを確認します。

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

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

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

void AddScoreToLeaders(std::string email,
                       long score,
                       DatabaseReference leaderBoardRef) {
  leaderBoardRef.RunTransaction([](firebase::database::MutableData* mutableData) {
    if (mutableData.children_count() &gt= MaxScores) {
      long minScore = LONG_MAX;
      MutableData *minVal = null;
      std::vector&ltMutableData&gt children = mutableData.children();
      std::vector&ltMutableData&gt::iterator it;
      for (it = children.begin(); it != children.end(); ++it) {
        if (!it->value().is_map())
          continue;
        long childScore = (long)it->Child("score").value().int64_value();
        if (childScore &lt minScore) {
          minScore = childScore;
          minVal = &amp*it;
        }
      }
      if (minScore &gt score) {
        // The new score is lower than the existing 5 scores, abort.
        return kTransactionResultAbort;
      }

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

    // Add the new high score.
    std::map&ltstd::string, Variant&gt newScoreMap =
      new std::map&ltstd::string, Variant&gt();
    newScoreMap["score"] = score;
    newScoreMap["email"] = email;
    children.Add(newScoreMap);
    mutableData->set_value(children);
    return kTransactionResultSuccess;
  });
}

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

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

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

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

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

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

次のステップ