Daten werden abgerufen

In diesem Dokument werden die Grundlagen des Abrufens von Daten und des Sortierens und Filterns von Firebase-Daten behandelt.

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 Ihr Unity-Projekt bereits Firebase verwendet, ist es bereits registriert und für Firebase konfiguriert.

  • Wenn Sie kein Unity-Projekt haben, können Sie eine Beispiel-App herunterladen.

• Fügen Sie Ihrem Unity-Projekt das Firebase Unity SDK hinzu, insbesondere FirebaseDatabase.unitypackage.

Eine detaillierte Anleitung für diese ersten Einrichtungsschritte finden Sie unter Firebase zu einem Unity-Projekt hinzufügen.

Das Hinzufügen von Firebase zu Ihrem Unity-Projekt umfasst Aufgaben in der Firebase Konsole und in Ihrem geöffneten Unity-Projekt (Sie laden beispielsweise Firebase-Konfigurationsdateien aus der Konsole 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 in einer FirebaseDatabase-Referenz abgerufen. Der Ereignis-Listener wird einmal für den anfänglichen Status der Daten und dann bei jeder Änderung der Daten aufgerufen.

Hinweis: Standardmäßig ist der Lese- und Schreibzugriff auf Ihre Datenbank eingeschränkt, sodass nur authentifizierte Nutzer Daten lesen oder schreiben können. Wenn Sie ohne Einrichtung von Authentication beginnen möchten, können Sie Ihre Regeln für den öffentlichen Zugriff konfigurieren. Dadurch wird Ihre Datenbank für alle geöffnet, auch für Personen, die Ihre App nicht verwenden. Sie sollten Ihre Datenbank daher wieder einschränken, wenn Sie die Authentifizierung einrichten.

DatabaseReference abrufen

Um Daten aus der Datenbank zu lesen, 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 Aufgabenergebnis enthält einen Snapshot mit allen Daten an diesem Speicherort, einschließlich untergeordneter Daten. Wenn keine Daten vorhanden sind, ist der zurückgegebene Snapshot null.

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWithOnMainThread(task =&gt {
        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 von Elementen abrufen oder auf Ergänzungen einer Liste von Elementen warten. Empfohlene Verwendung mit ChildChanged und ChildRemoved um Änderungen an Listen zu beobachten.
ChildChanged	Auf Änderungen an den Elementen in einer Liste warten. Verwendung mit ChildAdded und ChildRemoved, um Änderungen an Listen zu beobachten.
ChildRemoved	Auf Elemente warten, die aus einer Liste entfernt werden. Verwendung mit ChildAdded und ChildChanged zur Überwachung von Änderungen an Listen.
ChildMoved	Auf Änderungen an der Reihenfolge von Elementen in einer sortierten Liste warten. ChildMoved Ereignisse folgen immer dem ChildChanged Ereignis, das die Änderung der Reihenfolge des Elements verursacht hat (basierend auf der aktuellen Sortiermethode).

ValueChanged-Ereignis

Mit dem ValueChanged Ereignis können Sie Änderungen am Inhalt an einem bestimmten Pfad abonnieren. Dieses Ereignis wird einmal ausgelöst, wenn der Listener angehängt wird, und dann jedes Mal, wenn sich die Daten, einschließlich untergeordneter Elemente, ändern. Der Ereignis-Callback erhält einen Snapshot mit allen Daten an diesem Speicherort, einschließlich untergeordneter Daten. Wenn keine Daten vorhanden sind, ist der zurückgegebene Snapshot null.

Wichtig: Das Ereignis ValueChanged wird jedes Mal ausgelöst, wenn Daten an der angegebenen Datenbankreferenz geändert werden, einschließlich Änderungen an untergeordneten Elementen. Um die Größe Ihrer Snapshots zu begrenzen, hängen Sie sie nur auf der höchsten Ebene an, die für die Beobachtung von Änderungen erforderlich ist. Es wird beispielsweise nicht empfohlen, einen Ereignis-Listener an den Stamm Ihrer Datenbank anzuhängen.

Im folgenden Beispiel ruft ein Spiel die Ergebnisse einer Bestenliste aus der Datenbank ab:

      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 einen DataSnapshot, der die Daten am angegebenen Speicherort in der Datenbank zum Zeitpunkt des Ereignisses enthält. Wenn Sie Value für einen Snapshot aufrufen, wird ein Dictionary<string, object> mit den Daten zurückgegeben. Wenn an diesem Speicherort keine Daten vorhanden sind, gibt der Aufruf von Value null zurück.

In diesem Beispiel wird auch args.DatabaseError untersucht, um festzustellen, ob der Lesevorgang abgebrochen wurde. Ein Lesevorgang kann beispielsweise abgebrochen werden, wenn der Client keine Berechtigung zum Lesen von einem Firebase-Datenbankspeicherort hat. Der DatabaseError gibt an, warum der Fehler aufgetreten ist.

Sie können das Ereignis später mit einer beliebigen DatabaseReference mit demselben Pfad abbestellen. DatabaseReference -Instanzen sind kurzlebig und können als Möglichkeit betrachtet werden, auf einen beliebigen Pfad zuzugreifen und Abfragen auszuführen.

      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 ausgeführt werden, z. B. wenn ein neues untergeordnetes Element mit der Push() Methode hinzugefügt oder ein untergeordnetes Element mit der UpdateChildrenAsync() Methode aktualisiert wird. Diese Ereignisse können zusammen nützlich sein, um Änderungen an einem bestimmten Knoten in einer Datenbank zu beobachten. Ein Spiel kann diese Methoden beispielsweise zusammen verwenden, um die Aktivität in den Kommentaren einer Spielsitzung zu beobachten, wie unten gezeigt:

      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
    }

Das ChildAdded Ereignis wird in der Regel verwendet, um eine Liste von Elementen in einer Firebase-Datenbank abzurufen. Das Ereignis ChildAdded 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. Der Listener erhält einen Snapshot mit den Daten des neuen untergeordneten Elements.

Das ChildChanged Ereignis wird jedes Mal ausgelöst, wenn ein untergeordneter Knoten geändert wird. Dazu gehören auch alle Änderungen an den Nachfolgern 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 ChildRemoved Ereignis wird ausgelöst, wenn ein direkt untergeordnetes Element entfernt wird. Es wird in der Regel 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 Neuanordnung des untergeordneten Elements verursacht. Es wird mit 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 sortiert abrufen. Sie können das sortierte Ergebnis auch auf eine bestimmte Anzahl von Ergebnissen oder einen Bereich von Schlüsseln oder Werten filtern.

Hinweis: Das Filtern und Sortieren kann ressourcenintensiv sein, insbesondere wenn es auf dem Client erfolgt. Wenn Ihre App Abfragen verwendet, definieren Sie die .indexOn Regel, um diese Schlüssel auf dem Server zu indexieren und die Abfrageleistung zu verbessern, wie unter Daten indexieren beschrieben.

Daten sortieren

Um sortierte Daten abzurufen, geben Sie zuerst eine der Sortiermethoden an, um zu bestimmen, wie die Ergebnisse sortiert werden:

Methode	Nutzung
OrderByChild()	Ergebnisse nach dem Wert eines bestimmten untergeordneten Schlüssels sortieren.
OrderByKey()	Ergebnisse nach untergeordneten Schlüsseln sortieren.
OrderByValue()	Ergebnisse nach untergeordneten Werten sortieren.

Sie können jeweils nur eine Sortiermethode verwenden. Wenn Sie in derselben Abfrage mehrere Sortiermethoden aufrufen, wird ein Fehler ausgelöst.

Im folgenden Beispiel wird gezeigt, wie Sie eine Bestenliste abonnieren können, die nach Ergebnis 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 ValueChanged-Ereignis-Listener den Client mit der Bestenliste in der Datenbank synchronisiert, sortiert nach dem Ergebnis jedes Eintrags. 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 von "score" Wert in jedem untergeordneten Element sortiert. Weitere Informationen zur Sortierung anderer Datentypen finden Sie unter So werden Abfragedaten sortiert.

Daten filtern

Um Daten zu filtern, können Sie beim Erstellen einer Abfrage eine beliebige Limit- oder Bereichsmethode 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()	Gibt Elemente zurück, die größer oder gleich dem angegebenen Schlüssel oder Wert sind je nach gewählter Sortiermethode.
EndAt()	Gibt Elemente zurück, die kleiner oder gleich dem angegebenen Schlüssel oder Wert sind je nach gewählter Sortiermethode.
EqualTo()	Gibt Elemente zurück, die gleich dem angegebenen Schlüssel oder Wert sind je nach gewählter Sortiermethode.

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 Abfrage gibt, ist der Snapshot immer noch eine Liste. Er enthält nur ein einzelnes Element.

Anzahl der Ergebnisse begrenzen

Mit den LimitToFirst() und LimitToLast() Methoden können Sie eine maximale Anzahl von untergeordneten Elementen festlegen, die für einen bestimmten Callback synchronisiert werden sollen. Wenn Sie beispielsweise mit LimitToFirst() ein Limit von 100 festlegen, erhalten Sie zunächst 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 aufgenommen werden, und ChildRemoved-Callbacks für Elemente, die aus der Abfrage entfernt werden, sodass die Gesamtzahl bei 100 bleibt.

Der folgende Code gibt beispielsweise das beste Ergebnis 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

Mit StartAt(), EndAt() und EqualTo() können Sie beliebige Start-, End- und Äquivalenzpunkte für Abfragen auswählen. Das kann nützlich sein, um Daten zu paginieren oder Elemente mit untergeordneten Elementen zu finden, die einen bestimmten Wert haben.

So werden Abfragedaten sortiert

In diesem Abschnitt wird erläutert, wie Daten mit den einzelnen Sortiermethoden in der Klasse Query sortiert werden.

OrderByChild

Bei Verwendung von OrderByChild() werden Daten, die den angegebenen untergeordneten Schlüssel enthalten, wie folgt sortiert:

1. Untergeordnete Elemente mit einem null Wert für den angegebenen untergeordneten Schlüssel werden zuerst angezeigt.
2. Als Nächstes folgen untergeordnete Elemente mit dem Wert false für den angegebenen untergeordneten Schlüssel kommen als Nächstes. Wenn mehrere untergeordnete Elemente den Wert false haben, werden sie lexikografischsortiert nach Schlüssel.
3. Als Nächstes folgen untergeordnete Elemente mit dem Wert true für den angegebenen untergeordneten Schlüssel kommen als Nächstes. Wenn mehrere untergeordnete Elemente den Wert true haben, werden sie lexikografisch nach Schlüssel sortiert.
4. 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.
5. Strings folgen nach Zahlen und werden lexikografisch in aufsteigender Reihenfolge sortiert. Wenn mehrere untergeordnete Elemente denselben Wert für den angegebenen untergeordneten Knoten haben, werden sie lexikografisch nach Schlüssel sortiert.
6. Objekte werden zuletzt angezeigt und lexikografisch nach Schlüssel in aufsteigender Reihenfolge sortiert.

OrderByKey

Bei Verwendung von OrderByKey() zum Sortieren Ihrer Daten werden die Daten in aufsteigender Reihenfolge nach Schlüssel zurückgegeben.

1. Untergeordnete Elemente mit einem Schlüssel, der als 32-Bit-Ganzzahl geparst werden kann, werden zuerst angezeigt, sortiert in aufsteigender Reihenfolge.
2. Als Nächstes folgen untergeordnete Elemente mit einem Stringwert als Schlüssel, sortiert lexikografisch in aufsteigender Reihenfolge.

OrderByValue

Bei Verwendung von OrderByValue() werden untergeordnete Elemente nach ihrem Wert sortiert. Die Sortierkriterien sind dieselben wie bei OrderByChild(), außer dass der Wert des Knotens anstelle des Werts eines bestimmten untergeordneten Schlüssels verwendet wird.