In diesem Dokument werden die Grundlagen des Abrufens von Daten und die Sortierung und Filterung von Firebase-Daten erläutert.
Hinweis
Bevor Sie Realtime Database verwenden können, müssen Sie Folgendes tun:
Registrieren Sie Ihr Unity-Projekt und konfigurieren Sie es für die Verwendung von Firebase.
Wenn in Ihrem Unity-Projekt bereits Firebase verwendet wird, 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 Ihrem Unity-Projekt das Firebase Unity SDK (insbesondere
FirebaseDatabase.unitypackage
) hinzu.
Das Hinzufügen von Firebase zu Ihrem Unity-Projekt umfasst Aufgaben sowohl in der FirebaseConsole als auch in Ihrem geöffneten Unity-Projekt. Sie laden beispielsweise Firebase-Konfigurationsdateien aus der Console herunter und verschieben sie dann in Ihr Unity-Projekt.
Daten abrufen
Firebase-Daten werden entweder durch einen einmaligen Aufruf von GetValueAsync() oder durch Anhängen an ein Ereignis mit einer FirebaseDatabase
-Referenz abgerufen. Der Event-Listener wird einmal für den Anfangszustand der Daten und bei jeder Änderung der Daten einmal aufgerufen.
Datenbankreferenz abrufen
Zum Lesen von Daten aus der Datenbank benötigen Sie eine Instanz von DatabaseReference
:
using Firebase; using Firebase.Database; using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread public class MyScript: MonoBehaviour { void Start() { // Get the root reference location of the database. DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference; } }
Daten einmal lesen
Mit der GetValueAsync
-Methode können Sie einmal einen statischen Snapshot des Inhalts an einem bestimmten Pfad lesen. Das Ergebnis der Aufgabe enthält einen Snapshot mit allen Daten an diesem Speicherort, einschließlich untergeordneter Daten. Wenn keine Daten vorhanden sind, wird als Snapshot null
zurückgegeben.
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .GetValueAsync().ContinueWithOnMainThread(task => { if (task.IsFaulted) { // Handle the error... } else if (task.IsCompleted) { DataSnapshot snapshot = task.Result; // Do something with snapshot... } });
Auf Ereignisse warten
Sie können Ereignis-Listener hinzufügen, um Änderungen an Daten zu abonnieren:
Ereignis | Typische Verwendung |
---|---|
ValueChanged |
Änderungen am gesamten Inhalt eines Pfads lesen und beobachten. |
ChildAdded
| Listen mit Elementen abrufen oder nach Elementen suchen, die einer Liste hinzugefügt wurden
Empfohlene Verwendung mit ChildChanged und ChildRemoved , um Änderungen an Listen zu beobachten. |
ChildChanged |
Auf Änderungen an den Elementen in einer Liste achten Verwenden Sie ihn zusammen mit ChildAdded und ChildRemoved , um Änderungen an Listen zu beobachten. |
ChildRemoved |
Prüfen, ob Elemente aus einer Liste entfernt werden Verwenden Sie ChildAdded und ChildChanged , um Änderungen an Listen im Blick zu behalten. |
ChildMoved |
Beobachten von Änderungen an der Reihenfolge der Elemente in einer sortierten Liste
ChildMoved -Ereignisse folgen immer dem ChildChanged -Ereignis, durch das sich die Reihenfolge des Artikels geändert hat (basierend auf Ihrer aktuellen Sortiermethode). |
Ereignis „ValueChanged“
Mit dem Ereignis ValueChanged
können Sie Änderungen am Inhalt eines bestimmten Pfads abonnieren. Dieses Ereignis wird einmal ausgelöst, wenn der Listener angehängt wird, und dann jedes Mal, wenn sich die Daten, einschließlich der untergeordneten Elemente, ändern. Dem Ereignis-Callback wird ein Snapshot mit allen Daten an diesem Speicherort übergeben, einschließlich untergeordneter Daten. Wenn keine Daten vorhanden sind, wird null
zurückgegeben.
Im folgenden Beispiel wird ein Spiel veranschaulicht, bei dem die Punktzahlen einer Bestenliste aus der Datenbank abgerufen werden:
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
ValueChangedEventArgs
enthält ein DataSnapshot
, das die Daten am angegebenen Speicherort in der Datenbank zum Zeitpunkt des Ereignisses enthält. Wenn Sie Value
für einen Snapshot aufrufen, wird eine Dictionary<string, object>
zurückgegeben, die die Daten darstellt.
Wenn am Standort keine Daten vorhanden sind, gibt das Aufrufen von Value
null
zurück.
In diesem Beispiel wird auch args.DatabaseError
geprüft, um festzustellen, ob die Lesevorgänge abgebrochen werden. Ein Lesevorgang kann beispielsweise abgebrochen werden, wenn der Client keine Berechtigung zum Lesen aus einem Firebase-Datenbankstandort hat. DatabaseError
gibt an, warum der Fehler aufgetreten ist.
Sie können sich später mit einer beliebigen DatabaseReference
mit demselben Pfad vom Ereignis abmelden. DatabaseReference
-Instanzen sind sitzungsbasiert und können als Möglichkeit zum Zugriff auf jeden Pfad und jede Abfrage betrachtet werden.
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged. }
Untergeordnete Ereignisse
Untergeordnete Ereignisse werden als Reaktion auf bestimmte Vorgänge ausgelöst, die mit den untergeordneten Elementen eines Knotens durch einen Vorgang stattfinden, z. B. wenn ein neues untergeordnetes Element über die Methode Push()
hinzugefügt oder ein untergeordnetes Element über die Methode UpdateChildrenAsync()
aktualisiert wird. Zusammen können sie nützlich sein, um Änderungen an einem bestimmten Knoten in einer Datenbank zu beobachten. In einem Spiel können diese Methoden beispielsweise kombiniert werden, um die Aktivität in den Kommentaren einer Spielsitzung zu überwachen, wie unten dargestellt:
var ref = FirebaseDatabase.DefaultInstance .GetReference("GameSessionComments"); ref.ChildAdded += HandleChildAdded; ref.ChildChanged += HandleChildChanged; ref.ChildRemoved += HandleChildRemoved; ref.ChildMoved += HandleChildMoved; } void HandleChildAdded(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildChanged(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildRemoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildMoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
In der Regel wird das Ereignis ChildAdded
verwendet, um eine Liste von Elementen in einer Firebase-Datenbank abzurufen. Das ChildAdded
-Ereignis wird einmal für jedes vorhandene untergeordnete Element und dann jedes Mal ausgelöst, wenn dem angegebenen Pfad ein neues untergeordnetes Element hinzugefügt wird. Dem Listener wird ein Snapshot mit den Daten des neuen untergeordneten Elements übergeben.
Das Ereignis ChildChanged
wird jedes Mal ausgelöst, wenn ein untergeordneter Knoten geändert wird.
Dazu gehören auch alle Änderungen an Nachkommen des untergeordneten Knotens. Es wird in der Regel in Verbindung mit den Ereignissen ChildAdded
und ChildRemoved
verwendet, um auf Änderungen an einer Liste von Elementen zu reagieren. Der an den Ereignis-Listener übergebene Snapshot enthält die aktualisierten Daten für das untergeordnete Element.
Das Ereignis ChildRemoved
wird ausgelöst, wenn ein unmittelbares untergeordnetes Element entfernt wird.
Sie wird normalerweise in Verbindung mit den Callbacks ChildAdded
und ChildChanged
verwendet. Der an den Ereignis-Callback übergebene Snapshot enthält die Daten für das entfernte untergeordnete Element.
Das ChildMoved
-Ereignis wird ausgelöst, wenn das ChildChanged
-Ereignis durch eine Aktualisierung ausgelöst wird, die eine Neusortierung des untergeordneten Elements zur Folge hat. Sie wird für Daten verwendet, die mit OrderByChild
oder OrderByValue
sortiert sind.
Daten sortieren und filtern
Mit der Klasse Realtime Database Query
können Sie Daten nach Schlüssel, Wert oder Wert eines untergeordneten Elements abrufen. Sie können das sortierte Ergebnis auch nach einer bestimmten Anzahl von Ergebnissen oder einem Bereich von Schlüsseln oder Werten filtern.
Daten sortieren
Wenn Sie sortierte Daten abrufen möchten, müssen Sie zuerst eine der Sortierungsmethoden angeben, um zu bestimmen, wie die Ergebnisse sortiert werden:
Methode | Nutzung |
---|---|
OrderByChild() |
Sortiert die Ergebnisse nach dem Wert eines bestimmten untergeordneten Schlüssels. |
OrderByKey()
| Ergebnisse nach untergeordneten Schlüsseln sortieren |
OrderByValue() |
Ergebnisse nach untergeordneten Werten sortieren |
Sie können jeweils nur eine Sortiermethode verwenden. Wenn Sie eine Methode zum Sortieren mehrmals in derselben Abfrage aufrufen, wird ein Fehler ausgegeben.
Im folgenden Beispiel wird gezeigt, wie du dich für eine Bestenliste mit Punkten anmelden kannst, die nach Punkten sortiert ist.
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
Dadurch wird eine Abfrage definiert, die in Kombination mit einem Ereignis-Listener für „valuechanged“ den Client mit der Bestenliste in der Datenbank synchronisiert, die nach dem Wert jedes Eintrags sortiert ist. Weitere Informationen zum effizienten Strukturieren Ihrer Daten finden Sie unter Datenbank strukturieren.
Der Aufruf der Methode OrderByChild()
gibt den untergeordneten Schlüssel an, nach dem die Ergebnisse sortiert werden sollen. In diesem Fall werden die Ergebnisse nach dem Wert des "score"
-Werts in den einzelnen untergeordneten Elementen sortiert. Weitere Informationen zur Sortierung anderer Datentypen finden Sie unter Sortierung von Abfragedaten.
Daten filtern
Wenn Sie Daten filtern möchten, können Sie beim Erstellen einer Abfrage eine beliebige der Methoden zum Begrenzen oder Bestimmen des Bereichs mit einer Sortiermethode kombinieren.
Methode | Nutzung |
---|---|
LimitToFirst() |
Legt die maximale Anzahl der Elemente fest, die vom Anfang der sortierten Ergebnisliste zurückgegeben werden sollen. |
LimitToLast() |
Legt die maximale Anzahl der Elemente fest, die vom Ende der sortierten Ergebnisliste zurückgegeben werden sollen. |
StartAt() |
Je nach ausgewählter Sortiermethode werden Elemente zurückgegeben, die größer oder gleich dem angegebenen Schlüssel oder Wert sind. |
EndAt() |
Gibt Elemente zurück, die kleiner oder gleich dem angegebenen Schlüssel oder Wert sind, je nach ausgewählter Sortiermethode. |
EqualTo() |
Je nach ausgewählter Sortiermethode werden Elemente zurückgegeben, die dem angegebenen Schlüssel oder Wert entsprechen. |
Im Gegensatz zu den Sortiermethoden können Sie mehrere Limit- oder Bereichsfunktionen kombinieren.
Sie können beispielsweise die Methoden StartAt()
und EndAt()
kombinieren, um die Ergebnisse auf einen bestimmten Wertebereich zu beschränken.
Auch wenn es nur eine Übereinstimmung für die Suchanfrage gibt, ist der Snapshot immer eine Liste. Er enthält nur ein einzelnes Element.
Anzahl der Ergebnisse begrenzen
Mit den Methoden LimitToFirst()
und LimitToLast()
können Sie eine maximale Anzahl von untergeordneten Elementen festlegen, die für einen bestimmten Rückruf synchronisiert werden sollen. Wenn Sie beispielsweise mit LimitToFirst()
ein Limit von 100 festlegen, erhalten Sie anfangs nur bis zu 100 ChildAdded
-Callbacks. Wenn in Ihrer Firebase-Datenbank weniger als 100 Elemente gespeichert sind, wird für jedes Element ein ChildAdded
-Callback ausgelöst.
Wenn sich Elemente ändern, erhalten Sie ChildAdded
-Callbacks für Elemente, die in die Abfrage eingegeben werden, und ChildRemoved
-Callbacks für Elemente, die aus der Abfrage entfernt werden. Dadurch bleibt die Gesamtzahl bei 100.
Der folgende Code gibt beispielsweise den höchsten Wert aus einer Bestenliste zurück:
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score").LimitToLast(1) .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
Nach Schlüssel oder Wert filtern
Sie können StartAt()
, EndAt()
und EqualTo()
verwenden, um beliebige Start-, End- und Äquivalenzpunkte für Abfragen auszuwählen. Das kann nützlich sein, um Daten zu paginatieren oder Elemente mit untergeordneten Elementen mit einem bestimmten Wert zu finden.
Sortierung von Abfragedaten
In diesem Abschnitt wird erläutert, wie Daten mit den einzelnen Sortierungsmethoden in der Query
-Klasse sortiert werden.
OrderByChild
Bei Verwendung von OrderByChild()
werden Daten, die den angegebenen untergeordneten Schlüssel enthalten, so geordnet:
- Untergeordnete Elemente mit einem
null
-Wert für den angegebenen untergeordneten Schlüssel werden zuerst angezeigt. - Als Nächstes folgen untergeordnete Elemente mit dem Wert
false
für den angegebenen untergeordneten Schlüssel. Wenn mehrere untergeordnete Elemente den Wertfalse
haben, werden sie lexikografisch nach Schlüssel sortiert. - Als Nächstes kommen untergeordnete Elemente mit dem Wert
true
für den angegebenen untergeordneten Schlüssel. Wenn mehrere untergeordnete Elemente den Werttrue
haben, werden sie nach Schlüssel sortiert. - Als Nächstes folgen untergeordnete Elemente mit einem numerischen Wert, sortiert in aufsteigender Reihenfolge. Wenn mehrere untergeordnete Elemente denselben numerischen Wert für den angegebenen untergeordneten Knoten haben, werden sie nach Schlüssel sortiert.
- Strings folgen nach Zahlen und werden alphabetisch in aufsteigender Reihenfolge sortiert. Wenn mehrere untergeordnete Elemente denselben Wert für den angegebenen untergeordneten Knoten haben, werden sie lexikografisch nach Schlüssel sortiert.
- Objekte kommen zuletzt und werden in aufsteigender Reihenfolge nach Schlüssel sortiert.
OrderByKey
Wenn Sie Ihre Daten mit OrderByKey()
sortieren, werden sie in aufsteigender Reihenfolge nach Schlüssel zurückgegeben.
- Untergeordnete Elemente mit einem Schlüssel, der als 32‑Bit-Ganzzahl geparst werden kann, werden zuerst in aufsteigender Reihenfolge sortiert.
- Als Nächstes folgen untergeordnete Elemente mit einem Stringwert als Schlüssel, sortiert in aufsteigender lexikografischer Reihenfolge.
OrderByValue
Bei Verwendung von OrderByValue()
werden untergeordnete Elemente nach ihrem Wert sortiert. Die Sortierungskriterien sind dieselben wie in OrderByChild()
, mit der Ausnahme, dass der Wert des Knotens anstelle des Werts eines angegebenen untergeordneten Schlüssels verwendet wird.