儲存資料

事前準備

如要使用 Realtime Database， 請先完成下列步驟：

  • 註冊 Unity 專案並設定使用 Firebase。

    • 如果 Unity 專案已使用 Firebase，則專案已註冊並設定 Firebase。

    • 如果沒有 Unity 專案，可以下載範例應用程式。

  • 將 Firebase  SDK (具體來說是 FirebaseDatabase.unitypackage) 新增至 Unity 專案。Unity

請注意，將 Firebase 新增至 Unity 專案時，您需要在Firebase控制台和開啟的 Unity 專案中執行工作 (例如從控制台下載 Firebase 設定檔，然後移至 Unity 專案)。

儲存資料

將資料寫入 Firebase Realtime Database 的方法有五種：

方法 常見的使用方式
SetValueAsync() 在定義的路徑 (例如 users/<user-id>/<username>) 寫入或取代資料。
SetRawJsonValueAsync() 使用原始 JSON 寫入或取代資料，例如 users/<user-id>/<username>。
Push() 新增至資料清單。每次呼叫 Push() 時，Firebase 都會產生專屬鍵，這個鍵也可以做為專屬 ID，例如 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()，會覆寫指定位置的資料，包括任何子節點。不過，您還是可以更新子項，不必重寫整個物件。如要允許使用者更新個人資料，可以按照下列方式更新使用者名稱：

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

附加至資料清單

在多使用者應用程式中，使用 Push() 方法將資料附加至清單。每當新子項新增至指定的 Firebase 參照時，Push() 方法就會產生專屬鍵。為清單中的每個新元素使用這些自動產生的鍵，多個用戶端就能同時在相同位置新增子項，不會發生寫入衝突。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()，即可同時更新 JSON 樹狀結構中的多個位置，例如這個範例會在兩個位置建立新項目。以這種方式進行的同步更新具有不可分割的特性：所有更新都會成功，或所有更新都會失敗。

刪除資料

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

您也可以指定 null 做為其他寫入作業 (例如 SetValueAsync() 或 UpdateChildrenAsync()) 的值，藉此刪除資料。您可以使用這項技術搭配 UpdateChildrenAsync()，在單次 API 呼叫中刪除多個子項。

瞭解資料的提交時間。

如要瞭解資料何時會提交至 Firebase Realtime Database 伺服器，您可以新增續傳。SetValueAsync() 和 UpdateChildrenAsync() 都會傳回 Task，讓您瞭解作業何時完成。如果呼叫因任何原因而失敗，Tasks IsFaulted 會為 true，且 Exception 屬性會指出發生失敗的原因。

將資料儲存為交易

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

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

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 用戶端隨後會盡力將資料與遠端資料庫伺服器和其他用戶端同步。

因此，所有寫入資料庫的作業都會立即觸發本機事件，然後才將資料寫入伺服器。也就是說，無論網路延遲或連線狀況如何，應用程式都能保持回應。

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

後續步驟