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

儲存資料

事前準備

使用即時資料庫前，您必須先完成以下事項：

註冊 Unity 專案，並將其設定為使用 Firebase。
- 如果您的 Unity 專案已使用 Firebase，表示該專案已完成註冊並設定 Firebase。
- 如果您沒有 Unity 專案，可以下載範例應用程式。
在 Unity 專案中新增 Firebase Unity SDK (尤其是 FirebaseDatabase.unitypackage)。

請注意，將 Firebase 新增至 Unity 專案涉及到 Firebase 主控台和開放式 Unity 專案中的工作 (例如從主控台下載 Firebase 設定檔，再移至 Unity 專案)。

正在儲存資料

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

方式	常見的使用方式
`SetValueAsync()`	將資料寫入或取代已定義的路徑，例如 `users/<user-id>/<username>`。
`SetRawJsonValueAsync()`	使用 `users/<user-id>/<username>` 等原始 Json 寫入或取代資料。
`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 即時資料庫伺服器，您可以新增連續程序。SetValueAsync() 和 UpdateChildrenAsync() 都會傳回 Task，讓您知道作業何時完成。如果因任何原因導致呼叫失敗，Task 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 用戶端會「盡可能」將這些資料與遠端資料庫伺服器和其他用戶端同步處理。

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

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