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

透過 C++ 適用的 Firebase 即時資料庫節省資料

開始使用

如果您尚未設定應用程式及存取資料庫，請先參閱 Get Started 指南。

取得 DatabaseReference

如要將資料寫入資料庫，您需要 DatabaseReference 的執行個體：

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

正在儲存資料

將資料寫入 Firebase 即時資料庫的方法有四種：

方式	常見的使用方式
`SetValue()`	將資料寫入或取代已定義的路徑，例如 `users/<user-id>/<username>`。
`PushChild()`	新增至資料清單。每次呼叫 `Push()` 時，Firebase 都會產生一組專屬金鑰，這組金鑰也能做為專屬 ID，例如 `user-scores/<user-id>/<unique-score-id>`。
`UpdateChildren()`	更新已定義路徑的部分鍵，而不替換所有資料。
`RunTransaction()`	更新可能因為並行更新而損毀的複雜資料。

寫入、更新或刪除參照中的資料

基本寫入作業

針對基本的寫入作業，您可以使用 SetValue() 將資料儲存至指定的參照，取代該路徑中的所有現有資料。您可以使用這個方法透過支援的 Variant 類型傳遞 JSON 接受的類型：

空值 (這會刪除資料)
整數 (64 位元)
雙精度浮點數
布林值
Strings
變體向量
將字串對應至 Variants

透過這種方式使用 SetValue() 會覆寫指定位置的資料，包括任何子節點。不過，您仍可更新子項，不必重寫整個物件。如要允許使用者更新個人資料，可以按照下列方式更新使用者名稱：

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

附加至資料清單

使用 PushChild() 方法，將資料附加至多使用者應用程式中的清單。每當在指定的 Firebase 參考資料中加入新的子項時，PushChild() 方法就會產生專屬金鑰。透過針對清單中的每個新元素使用自動產生的金鑰，多個用戶端即可同時將子項新增至相同位置，而不會發生寫入衝突。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<std::string, Object> ToMap() {
    std::map<string, Variant> result = new std::map<string, Variant>();
    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<std::string, Variant> entryValues = entry.ToMap();

  std::map<string, Variant> childUpdates = new std::map<string, Variant>();
  childUpdates["/scores/" + key] = entryValues;
  childUpdates["/user-scores/" + userId + "/" + key] = entryValues;

  dbref.UpdateChildren(childUpdates);
}

此範例使用 PushChild() 在包含 /scores/$key 中所有使用者項目的節點建立一個項目，並同時使用 key() 擷取金鑰。這樣就能在 /user-scores/$userid/$key 使用者分數中建立第二個項目。

您可以使用這些路徑，透過單一呼叫 UpdateChildren() 對 JSON 樹狀結構中的多個位置進行同時更新，例如這個範例如何在兩個位置建立新項目。這種方式同時進行的更新也是不可分割的：所有更新成功或所有更新都會失敗。

刪除資料

刪除資料最簡單的方法是對該資料位置的參照呼叫 RemoveValue()。

您也可以指定 null Variant 做為其他寫入作業 (例如 SetValue() 或 UpdateChildren()) 的值來刪除。您可以搭配 UpdateChildren() 使用此技巧，在單一 API 呼叫中刪除多個子項。

瞭解資料何時修訂。

如要瞭解資料何時提交至 Firebase 即時資料庫伺服器，請查看 Future 的結果是否成功。

將資料儲存為交易

處理可能會因為並行修改而損毀的資料 (例如漸進式計數器) 時，您可以使用交易作業。您可以為此作業提供 DoTransaction 函式。這個更新函式會將資料目前的狀態做為引數，並傳回您要寫入的新所需狀態。如果其他用戶端在成功寫入新值之前寫入位置，系統會以新的目前值再次呼叫更新函式，並重試寫入。

舉例來說，在遊戲中，您可以允許使用者更新分數最高的五分的排行榜：

void AddScoreToLeaders(std::string email,
                       long score,
                       DatabaseReference leaderBoardRef) {
  leaderBoardRef.RunTransaction([](firebase::database::MutableData* mutableData) {
    if (mutableData.children_count() >= MaxScores) {
      long minScore = LONG_MAX;
      MutableData *minVal = null;
      std::vector<MutableData> children = mutableData.children();
      std::vector<MutableData>::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 < minScore) {
          minScore = childScore;
          minVal = &*it;
        }
      }
      if (minScore > 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<std::string, Variant> newScoreMap =
      new std::map<std::string, Variant>();
    newScoreMap["score"] = score;
    newScoreMap["email"] = email;
    children.Add(newScoreMap);
    mutableData->set_value(children);
    return kTransactionResultSuccess;
  });
}

若使用交易，如果多位使用者同時記錄分數或用戶端包含過時的資料，可以防止排行榜不正確。如果交易遭拒，伺服器會將目前的值傳回用戶端，用戶端會使用更新後的值再次執行交易。系統會重複此動作，直到接受交易或嘗試次數過多。

離線寫入資料

如果用戶端的網路連線中斷，您的應用程式會繼續正常運作。

每個連接至 Firebase 資料庫的用戶端，都會維護自己的任何有效資料的內部版本。寫入資料時，系統會先將資料寫入這個本機版本。接著，Firebase 用戶端會「盡可能」將這些資料與遠端資料庫伺服器和其他用戶端同步處理。

因此，在將任何資料寫入伺服器之前，所有寫入資料庫的作業會立即觸發本機事件。換句話說，無論網路延遲或連線狀況，應用程式都會持續回應。

重新建立連線後，應用程式會收到一組適當的事件，讓用戶端與目前的伺服器狀態同步，而不必編寫任何自訂程式碼。

後續步驟

擷取資料