在你開始之前
在使用即時資料庫之前,您需要:
註冊您的 Unity 專案並將其配置為使用 Firebase。
如果您的 Unity 專案已使用 Firebase,則它已針對 Firebase 進行註冊和設定。
如果您沒有 Unity 項目,可以下載範例應用程式。
將Firebase Unity SDK (具體來說,
FirebaseDatabase.unitypackage
)新增到您的 Unity 專案中。
請注意,將 Firebase 新增至 Unity 專案涉及Firebase 控制台和開啟的 Unity 專案中的任務(例如,從控制台下載 Firebase 設定文件,然後將它們移至 Unity 專案中)。
儲存數據
將資料寫入 Firebase 即時資料庫有五種方法:
方法 | 常見用途 |
---|---|
SetValueAsync() | 將資料寫入或替換到定義的路徑,例如users/<user-id>/<username> 。 |
SetRawJsonValueAsync() | 使用原始 Json 寫入或替換數據,例如users/<user-id>/<username> 。 |
Push() | 新增到資料列表。每次呼叫Push() 時,Firebase 都會產生一個唯一鍵,該鍵也可以用作唯一標識符,例如user-scores/<user-id>/<unique-score-id> 。 |
UpdateChildrenAsync() | 更新已定義路徑的一些鍵,而不替換所有資料。 |
RunTransaction() | 更新可能因並發更新而損壞的複雜資料。 |
取得資料庫參考
若要將資料寫入資料庫,您需要一個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
,讓您知道操作何時完成。如果因任何原因呼叫失敗,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 用戶端會「盡力」將該資料與遠端資料庫伺服器和其他用戶端同步。
因此,在將任何資料寫入伺服器之前,對資料庫的所有寫入都會立即觸發本機事件。這意味著無論網路延遲或連接如何,您的應用程式都保持回應。
重新建立連線後,您的應用程式會收到適當的事件集,以便用戶端與目前伺服器狀態同步,而無需編寫任何自訂程式碼。