Bevor Sie beginnen
Bevor Sie Realtime Database verwenden können, müssen Sie:
Registrieren Sie Ihr Unity-Projekt und konfigurieren Sie es für die Verwendung von Firebase.
Wenn Ihr Unity-Projekt Firebase bereits verwendet, ist es bereits für Firebase registriert und konfiguriert.
Wenn Sie kein Unity-Projekt haben, können Sie eine Beispiel-App herunterladen.
Fügen Sie das Firebase Unity SDK (insbesondere
FirebaseDatabase.unitypackage
) zu Ihrem Unity-Projekt hinzu.
Beachten Sie, dass das Hinzufügen von Firebase zu Ihrem Unity-Projekt Aufgaben sowohl in der Firebase-Konsole als auch in Ihrem geöffneten Unity-Projekt umfasst (Sie laden beispielsweise Firebase-Konfigurationsdateien von der Konsole herunter und verschieben sie dann in Ihr Unity-Projekt).
Daten speichern
Es gibt fünf Methoden zum Schreiben von Daten in die Firebase-Echtzeitdatenbank:
Methode | Gemeinsame Verwendungen |
---|---|
SetValueAsync() | Schreiben oder ersetzen Sie Daten in einen definierten Pfad, z. B. users/<user-id>/<username> . |
SetRawJsonValueAsync() | Schreiben oder ersetzen Sie Daten durch rohes Json, wie z. users/<user-id>/<username> . |
Push() | Zu einer Datenliste hinzufügen. Jedes Mal, wenn Sie Push() aufrufen, generiert Firebase einen eindeutigen Schlüssel, der auch als eindeutiger Bezeichner verwendet werden kann, z. B. user-scores/<user-id>/<unique-score-id> . |
UpdateChildrenAsync() | Aktualisieren Sie einige der Schlüssel für einen definierten Pfad, ohne alle Daten zu ersetzen. |
RunTransaction() | Aktualisieren Sie komplexe Daten, die durch gleichzeitige Aktualisierungen beschädigt werden könnten. |
Holen Sie sich eine Datenbankreferenz
Um Daten in die Datenbank zu schreiben, benötigen Sie eine Instanz von 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; } }
Daten in einer Referenz schreiben, aktualisieren oder löschen
Grundlegende Schreiboperationen
Für grundlegende Schreibvorgänge können Sie SetValueAsync()
verwenden, um Daten in einem angegebenen Verweis zu speichern und alle vorhandenen Daten in diesem Pfad zu ersetzen. Sie können diese Methode verwenden, um Typen zu übergeben, die den verfügbaren JSON-Typen wie folgt entsprechen:
-
string
-
long
-
double
-
bool
-
Dictionary<string, Object>
-
List<Object>
Wenn Sie ein typisiertes C#-Objekt verwenden, können Sie das integrierte JsonUtility.ToJson()
verwenden, um das Objekt in unformatiertes Json zu konvertieren und SetRawJsonValueAsync()
aufzurufen. Beispielsweise haben Sie möglicherweise eine Benutzerklasse, die wie folgt aussieht:
public class User { public string username; public string email; public User() { } public User(string username, string email) { this.username = username; this.email = email; } }
Sie können einen Benutzer mit SetRawJsonValueAsync()
wie folgt hinzufügen:
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); }
Die Verwendung SetValueAsync()
oder SetRawJsonValueAsync()
auf diese Weise überschreibt Daten an der angegebenen Position, einschließlich aller untergeordneten Knoten. Sie können jedoch ein untergeordnetes Objekt aktualisieren, ohne das gesamte Objekt neu zu schreiben. Wenn Sie Benutzern erlauben möchten, ihre Profile zu aktualisieren, können Sie den Benutzernamen wie folgt aktualisieren:
mDatabaseRef.Child("users").Child(userId).Child("username").SetValueAsync(name);
An eine Datenliste anhängen
Verwenden Sie die Push()
Methode, um Daten in Mehrbenutzeranwendungen an eine Liste anzuhängen. Die Push()
Methode generiert jedes Mal einen eindeutigen Schlüssel, wenn der angegebenen Firebase-Referenz ein neues untergeordnetes Element hinzugefügt wird. Durch die Verwendung dieser automatisch generierten Schlüssel für jedes neue Element in der Liste können mehrere Clients gleichzeitig Kinder an derselben Stelle hinzufügen, ohne dass es zu Schreibkonflikten kommt. Der von Push()
generierte eindeutige Schlüssel basiert auf einem Zeitstempel, sodass Listenelemente automatisch chronologisch geordnet werden.
Sie können den Verweis auf die neuen Daten verwenden, die von der Push()
Methode zurückgegeben werden, um den Wert des automatisch generierten Schlüssels des untergeordneten Elements abzurufen oder Daten für das untergeordnete Element festzulegen. Der Aufruf von Key
für eine Push()
-Referenz gibt den Wert des automatisch generierten Schlüssels zurück.
Aktualisieren Sie bestimmte Felder
Um gleichzeitig in bestimmte untergeordnete Knoten eines Knotens zu schreiben, ohne andere untergeordnete Knoten zu überschreiben, verwenden Sie die UpdateChildrenAsync()
Methode.
Beim Aufrufen von UpdateChildrenAsync()
können Sie untergeordnete Werte auf niedrigerer Ebene aktualisieren, indem Sie einen Pfad für den Schlüssel angeben. Wenn Daten zur besseren Skalierung an mehreren Speicherorten gespeichert werden, können Sie alle Instanzen dieser Daten mithilfe von Datenauffächerung aktualisieren. Ein Spiel könnte beispielsweise eine LeaderboardEntry
Klasse wie diese haben:
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; } }
Um einen Leaderboard-Eintrag zu erstellen und ihn gleichzeitig mit dem letzten Ergebnis-Feed und der eigenen Ergebnisliste des Benutzers zu aktualisieren, verwendet das Spiel Code wie diesen:
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); }
In diesem Beispiel wird Push()
verwendet, um einen Eintrag im Knoten zu erstellen, der Einträge für alle Benutzer unter /scores/$key
enthält, und gleichzeitig den Schlüssel mit Key
abzurufen. Der Schlüssel kann dann verwendet werden, um einen zweiten Eintrag in den Ergebnissen des Benutzers unter /user-scores/$userid/$key
zu erstellen.
Mithilfe dieser Pfade können Sie mit einem einzigen Aufruf von UpdateChildrenAsync()
simultane Aktualisierungen an mehreren Speicherorten in der JSON-Struktur durchführen, so wie in diesem Beispiel der neue Eintrag an beiden Speicherorten erstellt wird. Auf diese Weise durchgeführte gleichzeitige Aktualisierungen sind atomar: Entweder sind alle Aktualisierungen erfolgreich oder alle Aktualisierungen schlagen fehl.
Daten löschen
Die einfachste Methode zum Löschen von Daten besteht darin RemoveValue()
für einen Verweis auf den Speicherort dieser Daten aufzurufen.
Sie können auch löschen, indem Sie null
als Wert für einen anderen Schreibvorgang wie SetValueAsync()
oder UpdateChildrenAsync()
angeben. Sie können diese Technik mit UpdateChildrenAsync()
verwenden, um mehrere untergeordnete Elemente in einem einzigen API-Aufruf zu löschen.
Wissen, wann Ihre Daten übertragen werden.
Um zu wissen, wann Ihre Daten an den Firebase Realtime Database-Server übertragen werden, können Sie eine Fortsetzung hinzufügen. Sowohl SetValueAsync()
als auch UpdateChildrenAsync()
geben eine Task
zurück, die es Ihnen ermöglicht zu wissen, wann der Vorgang abgeschlossen ist. Wenn der Aufruf aus irgendeinem Grund nicht erfolgreich ist, ist Tasks IsFaulted
wahr, wobei die Eigenschaft Exception
angibt, warum der Fehler aufgetreten ist.
Speichern Sie Daten als Transaktionen
Wenn Sie mit Daten arbeiten, die durch gleichzeitige Änderungen beschädigt werden könnten, wie z. B. inkrementelle Zähler, können Sie eine Transaktionsoperation verwenden. Sie geben dieser Operation eine Func
. Diese Func
nimmt den aktuellen Zustand der Daten als Argument und gibt den neuen gewünschten Zustand zurück, den Sie schreiben möchten. Wenn ein anderer Client an den Speicherort schreibt, bevor Ihr neuer Wert erfolgreich geschrieben wurde, wird Ihre Aktualisierungsfunktion erneut mit dem neuen aktuellen Wert aufgerufen, und der Schreibvorgang wird wiederholt.
In einem Spiel könnten Sie beispielsweise Benutzern erlauben, eine Rangliste mit den fünf höchsten Punktzahlen zu aktualisieren:
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); }); }
Die Verwendung einer Transaktion verhindert, dass die Rangliste falsch ist, wenn mehrere Benutzer gleichzeitig Punkte aufzeichnen oder der Client veraltete Daten hatte. Wenn die Transaktion abgelehnt wird, gibt der Server den aktuellen Wert an den Client zurück, der die Transaktion mit dem aktualisierten Wert erneut ausführt. Dies wiederholt sich, bis die Transaktion akzeptiert wird oder zu viele Versuche unternommen wurden.
Daten offline schreiben
Wenn ein Client seine Netzwerkverbindung verliert, funktioniert Ihre App weiterhin ordnungsgemäß.
Jeder Client, der mit einer Firebase-Datenbank verbunden ist, verwaltet seine eigene interne Version aller aktiven Daten. Wenn Daten geschrieben werden, werden sie zuerst in diese lokale Version geschrieben. Der Firebase-Client synchronisiert diese Daten dann nach bestem Wissen und Gewissen mit den Remote-Datenbankservern und mit anderen Clients.
Daher lösen alle Schreibvorgänge in die Datenbank sofort lokale Ereignisse aus, bevor Daten auf den Server geschrieben werden. Das bedeutet, dass Ihre App unabhängig von Netzwerklatenz oder Konnektivität reaktionsfähig bleibt.
Sobald die Konnektivität wiederhergestellt ist, empfängt Ihre App die entsprechenden Ereignisse, sodass der Client mit dem aktuellen Serverstatus synchronisiert wird, ohne benutzerdefinierten Code schreiben zu müssen.
Nächste Schritte
,Bevor Sie beginnen
Bevor Sie Realtime Database verwenden können, müssen Sie:
Registrieren Sie Ihr Unity-Projekt und konfigurieren Sie es für die Verwendung von Firebase.
Wenn Ihr Unity-Projekt Firebase bereits verwendet, ist es bereits für Firebase registriert und konfiguriert.
Wenn Sie kein Unity-Projekt haben, können Sie eine Beispiel-App herunterladen.
Fügen Sie das Firebase Unity SDK (insbesondere
FirebaseDatabase.unitypackage
) zu Ihrem Unity-Projekt hinzu.
Beachten Sie, dass das Hinzufügen von Firebase zu Ihrem Unity-Projekt Aufgaben sowohl in der Firebase-Konsole als auch in Ihrem geöffneten Unity-Projekt umfasst (Sie laden beispielsweise Firebase-Konfigurationsdateien von der Konsole herunter und verschieben sie dann in Ihr Unity-Projekt).
Daten speichern
Es gibt fünf Methoden zum Schreiben von Daten in die Firebase-Echtzeitdatenbank:
Methode | Gemeinsame Verwendungen |
---|---|
SetValueAsync() | Schreiben oder ersetzen Sie Daten in einen definierten Pfad, z. B. users/<user-id>/<username> . |
SetRawJsonValueAsync() | Schreiben oder ersetzen Sie Daten durch rohes Json, wie z. users/<user-id>/<username> . |
Push() | Zu einer Datenliste hinzufügen. Jedes Mal, wenn Sie Push() aufrufen, generiert Firebase einen eindeutigen Schlüssel, der auch als eindeutiger Bezeichner verwendet werden kann, z. B. user-scores/<user-id>/<unique-score-id> . |
UpdateChildrenAsync() | Aktualisieren Sie einige der Schlüssel für einen definierten Pfad, ohne alle Daten zu ersetzen. |
RunTransaction() | Aktualisieren Sie komplexe Daten, die durch gleichzeitige Aktualisierungen beschädigt werden könnten. |
Holen Sie sich eine Datenbankreferenz
Um Daten in die Datenbank zu schreiben, benötigen Sie eine Instanz von 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; } }
Daten in einer Referenz schreiben, aktualisieren oder löschen
Grundlegende Schreiboperationen
Für grundlegende Schreibvorgänge können Sie SetValueAsync()
verwenden, um Daten in einem angegebenen Verweis zu speichern und alle vorhandenen Daten in diesem Pfad zu ersetzen. Sie können diese Methode verwenden, um Typen zu übergeben, die den verfügbaren JSON-Typen wie folgt entsprechen:
-
string
-
long
-
double
-
bool
-
Dictionary<string, Object>
-
List<Object>
Wenn Sie ein typisiertes C#-Objekt verwenden, können Sie das integrierte JsonUtility.ToJson()
verwenden, um das Objekt in unformatiertes Json zu konvertieren und SetRawJsonValueAsync()
aufzurufen. Beispielsweise haben Sie möglicherweise eine Benutzerklasse, die wie folgt aussieht:
public class User { public string username; public string email; public User() { } public User(string username, string email) { this.username = username; this.email = email; } }
Sie können einen Benutzer mit SetRawJsonValueAsync()
wie folgt hinzufügen:
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); }
Die Verwendung SetValueAsync()
oder SetRawJsonValueAsync()
auf diese Weise überschreibt Daten an der angegebenen Position, einschließlich aller untergeordneten Knoten. Sie können jedoch ein untergeordnetes Objekt aktualisieren, ohne das gesamte Objekt neu zu schreiben. Wenn Sie Benutzern erlauben möchten, ihre Profile zu aktualisieren, können Sie den Benutzernamen wie folgt aktualisieren:
mDatabaseRef.Child("users").Child(userId).Child("username").SetValueAsync(name);
An eine Datenliste anhängen
Verwenden Sie die Push()
Methode, um Daten in Mehrbenutzeranwendungen an eine Liste anzuhängen. Die Push()
Methode generiert jedes Mal einen eindeutigen Schlüssel, wenn der angegebenen Firebase-Referenz ein neues untergeordnetes Element hinzugefügt wird. Durch die Verwendung dieser automatisch generierten Schlüssel für jedes neue Element in der Liste können mehrere Clients gleichzeitig Kinder an derselben Stelle hinzufügen, ohne dass es zu Schreibkonflikten kommt. Der von Push()
generierte eindeutige Schlüssel basiert auf einem Zeitstempel, sodass Listenelemente automatisch chronologisch geordnet werden.
Sie können den Verweis auf die neuen Daten verwenden, die von der Push()
Methode zurückgegeben werden, um den Wert des automatisch generierten Schlüssels des untergeordneten Elements abzurufen oder Daten für das untergeordnete Element festzulegen. Der Aufruf von Key
für eine Push()
-Referenz gibt den Wert des automatisch generierten Schlüssels zurück.
Aktualisieren Sie bestimmte Felder
Um gleichzeitig in bestimmte untergeordnete Knoten eines Knotens zu schreiben, ohne andere untergeordnete Knoten zu überschreiben, verwenden Sie die UpdateChildrenAsync()
Methode.
Beim Aufrufen von UpdateChildrenAsync()
können Sie untergeordnete Werte auf niedrigerer Ebene aktualisieren, indem Sie einen Pfad für den Schlüssel angeben. Wenn Daten zur besseren Skalierung an mehreren Speicherorten gespeichert werden, können Sie alle Instanzen dieser Daten mithilfe von Datenauffächerung aktualisieren. Ein Spiel könnte beispielsweise eine LeaderboardEntry
Klasse wie diese haben:
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; } }
Um einen Leaderboard-Eintrag zu erstellen und ihn gleichzeitig mit dem letzten Ergebnis-Feed und der eigenen Ergebnisliste des Benutzers zu aktualisieren, verwendet das Spiel Code wie diesen:
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); }
In diesem Beispiel wird Push()
verwendet, um einen Eintrag im Knoten zu erstellen, der Einträge für alle Benutzer unter /scores/$key
enthält, und gleichzeitig den Schlüssel mit Key
abzurufen. Der Schlüssel kann dann verwendet werden, um einen zweiten Eintrag in den Ergebnissen des Benutzers unter /user-scores/$userid/$key
zu erstellen.
Mithilfe dieser Pfade können Sie mit einem einzigen Aufruf von UpdateChildrenAsync()
simultane Aktualisierungen an mehreren Speicherorten in der JSON-Struktur durchführen, z. B. wie dieses Beispiel den neuen Eintrag an beiden Speicherorten erstellt. Auf diese Weise durchgeführte gleichzeitige Aktualisierungen sind atomar: Entweder sind alle Aktualisierungen erfolgreich oder alle Aktualisierungen schlagen fehl.
Daten löschen
Die einfachste Methode zum Löschen von Daten besteht darin RemoveValue()
für einen Verweis auf den Speicherort dieser Daten aufzurufen.
Sie können auch löschen, indem Sie null
als Wert für einen anderen Schreibvorgang wie SetValueAsync()
oder UpdateChildrenAsync()
angeben. Sie können diese Technik mit UpdateChildrenAsync()
verwenden, um mehrere untergeordnete Elemente in einem einzigen API-Aufruf zu löschen.
Wissen, wann Ihre Daten übertragen werden.
Um zu wissen, wann Ihre Daten an den Firebase Realtime Database-Server übertragen werden, können Sie eine Fortsetzung hinzufügen. Sowohl SetValueAsync()
als auch UpdateChildrenAsync()
geben eine Task
zurück, die es Ihnen ermöglicht zu wissen, wann der Vorgang abgeschlossen ist. Wenn der Aufruf aus irgendeinem Grund nicht erfolgreich ist, ist Tasks IsFaulted
wahr, wobei die Eigenschaft Exception
angibt, warum der Fehler aufgetreten ist.
Speichern Sie Daten als Transaktionen
Wenn Sie mit Daten arbeiten, die durch gleichzeitige Änderungen beschädigt werden könnten, wie z. B. inkrementelle Zähler, können Sie eine Transaktionsoperation verwenden. Sie geben dieser Operation eine Func
. Diese Func
nimmt den aktuellen Zustand der Daten als Argument und gibt den neuen gewünschten Zustand zurück, den Sie schreiben möchten. Wenn ein anderer Client an den Speicherort schreibt, bevor Ihr neuer Wert erfolgreich geschrieben wurde, wird Ihre Aktualisierungsfunktion erneut mit dem neuen aktuellen Wert aufgerufen, und der Schreibvorgang wird wiederholt.
In einem Spiel könnten Sie beispielsweise Benutzern erlauben, eine Rangliste mit den fünf höchsten Punktzahlen zu aktualisieren:
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); }); }
Die Verwendung einer Transaktion verhindert, dass die Rangliste falsch ist, wenn mehrere Benutzer gleichzeitig Punkte aufzeichnen oder der Client veraltete Daten hatte. Wenn die Transaktion abgelehnt wird, gibt der Server den aktuellen Wert an den Client zurück, der die Transaktion mit dem aktualisierten Wert erneut ausführt. Dies wiederholt sich, bis die Transaktion akzeptiert wird oder zu viele Versuche unternommen wurden.
Daten offline schreiben
Wenn ein Client seine Netzwerkverbindung verliert, funktioniert Ihre App weiterhin ordnungsgemäß.
Jeder Client, der mit einer Firebase-Datenbank verbunden ist, verwaltet seine eigene interne Version aller aktiven Daten. Wenn Daten geschrieben werden, werden sie zuerst in diese lokale Version geschrieben. Der Firebase-Client synchronisiert diese Daten dann nach bestem Wissen und Gewissen mit den Remote-Datenbankservern und mit anderen Clients.
Daher lösen alle Schreibvorgänge in die Datenbank sofort lokale Ereignisse aus, bevor Daten auf den Server geschrieben werden. Das bedeutet, dass Ihre App unabhängig von Netzwerklatenz oder Konnektivität reaktionsfähig bleibt.
Sobald die Konnektivität wiederhergestellt ist, empfängt Ihre App die entsprechenden Ereignisse, sodass der Client mit dem aktuellen Serverstatus synchronisiert wird, ohne benutzerdefinierten Code schreiben zu müssen.