Récupérer des données

Ce document explique les bases de la récupération des données, ainsi que la façon de trier et de filtrer les données Firebase.

Avant de commencer

Avant de pouvoir utiliser Realtime Database, vous devez effectuer les opérations suivantes :

• Enregistrez votre projet Unity et configurez-le pour utiliser Firebase.

  • Si votre projet Unity utilise déjà Firebase, il est déjà enregistré et configuré pour Firebase.

  • Si vous n'avez pas de projet Unity, vous pouvez télécharger un exemple d'application.

• Ajoutez le Firebase Unity SDK (plus précisément, FirebaseDatabase.unitypackage) à votre projet Unity.

Notez que l'ajout de Firebase à votre projet Unity implique des tâches à la fois dans la Firebase console et dans votre projet Unity ouvert (par exemple, vous téléchargez des fichiers de configuration Firebase depuis la console, puis vous les déplacez dans votre projet Unity).

Récupérer des données

Les données Firebase sont récupérées par un appel unique à GetValueAsync() ou en s'attachant à un événement sur une référence FirebaseDatabase. L'écouteur d'événements est appelé une fois pour l'état initial des données, puis chaque fois que les données changent.

Obtenir une DatabaseReference

Pour lire des données à partir de la base de données, vous avez besoin d'une instance de 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;
  }
}

Lire les données une seule fois

Vous pouvez utiliser la GetValueAsync méthode pour lire une seule fois un instantané statique du contenu d'un chemin d'accès donné. Le résultat de la tâche contient un instantané contenant toutes les données à cet emplacement, y compris les données enfants. S'il n'y a pas de données, l'instantané renvoyé est 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...
        }
      });

Écouter les événements

Vous pouvez ajouter des écouteurs d'événements pour vous abonner aux modifications des données :

Événement ValueChanged

Vous pouvez utiliser l'ValueChanged événement pour vous abonner aux modifications du contenu d'un chemin d'accès donné. Cet événement est déclenché une fois lorsque l'écouteur est associé, puis chaque fois que les données, y compris les enfants, sont modifiées. Le rappel d'événement reçoit un instantané contenant toutes les données à cet emplacement, y compris les données enfants. S'il n'y a pas de données, l'instantané renvoyé est null.

L'exemple suivant montre un jeu qui récupère les scores d'un classement à partir de la base de données :

      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 contient un DataSnapshot qui contient les données à l'emplacement spécifié dans la base de données au moment de l'événement. L'appel de Value sur un instantané renvoie un Dictionary<string, object> représentant les données. Si aucune donnée n'existe à l'emplacement, l'appel de Value renvoie null.

Dans cet exemple, args.DatabaseError est également examiné pour voir si la lecture est annulée. Par exemple, une lecture peut être annulée si le client n'est pas autorisé à lire à partir d'un emplacement de base de données Firebase. DatabaseError indique la raison de l'échec.

Vous pouvez ensuite vous désabonner de l'événement à l'aide de n'importe quel DatabaseReference ayant le même chemin d'accès. Les instances DatabaseReference sont éphémères et peuvent être considérées comme un moyen d'accéder à n'importe quel chemin d'accès et à n'importe quelle requête.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged.
    }

Événements enfants

Les événements enfants sont déclenchés en réponse à des opérations spécifiques qui se produisent sur les enfants d'un nœud à partir d'une opération telle qu'un nouvel enfant ajouté via la Push() méthode ou un enfant mis à jour via la UpdateChildrenAsync() méthode. Chacun de ces éléments peut être utile pour écouter les modifications apportées à un nœud spécifique dans une base de données. Par exemple, un jeu peut utiliser ces méthodes ensemble pour surveiller l'activité dans les commentaires d'une session de jeu, comme illustré ci-dessous :

      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
    }

L'ChildAdded événement est généralement utilisé pour récupérer une liste d' éléments dans une base de données Firebase. L'événement ChildAdded est déclenché une fois pour chaque enfant existant, puis chaque fois qu'un nouvel enfant est ajouté au chemin d'accès spécifié. L'écouteur reçoit un instantané contenant les données du nouvel enfant.

L'ChildChanged événement est déclenché chaque fois qu'un nœud enfant est modifié. Cela inclut toutes les modifications apportées aux descendants du nœud enfant. Il est généralement utilisé conjointement avec les événements ChildAdded et ChildRemoved pour répondre aux modifications apportées à une liste d'éléments. L'instantané transmis à l'écouteur d'événements contient les données mises à jour de l'enfant.

L'événement ChildRemoved est déclenché lorsqu'un enfant immédiat est supprimé. Il est généralement utilisé conjointement avec les rappels ChildAdded et ChildChanged. L'instantané transmis au rappel d'événement contient les données de l'enfant supprimé.

L'ChildMoved événement est déclenché chaque fois que l'ChildChanged événement est déclenché par une mise à jour qui entraîne le réordonnancement de l'enfant. Il est utilisé avec des données triées avec OrderByChild ou OrderByValue.

Trier et filtrer les données

Vous pouvez utiliser la classe Realtime Database Query pour récupérer des données triées par clé, par valeur ou par valeur d'un enfant. Vous pouvez également filtrer le résultat trié sur un nombre spécifique de résultats ou une plage de clés ou de valeurs.

Trier les données

Pour récupérer des données triées, commencez par spécifier l'une des méthodes de tri pour déterminer l'ordre des résultats :

Vous ne pouvez utiliser qu'une seule méthode de tri à la fois. L'appel d'une méthode de tri plusieurs fois dans la même requête génère une erreur.

L'exemple suivant montre comment vous pouvez vous abonner à un classement des scores trié par score.

      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
    }

Cela définit une requête qui, combinée à un écouteur d'événements valuechanged synchronise le client avec le classement dans la base de données, trié par le score de chaque entrée. Pour en savoir plus sur la structuration efficace de vos données, consultez Structurer votre base de données.

L'appel à la méthode OrderByChild() spécifie la clé enfant par laquelle trier les résultats. Dans ce cas, les résultats sont triés par la valeur de la "score" valeur dans chaque enfant. Pour en savoir plus sur l'ordre des autres types de données, consultez Ordre des données de requête.

Filtrer les données

Pour filtrer les données, vous pouvez combiner n'importe quelle méthode de limite ou de plage avec une méthode de tri lors de la création d'une requête.

Contrairement aux méthodes de tri, vous pouvez combiner plusieurs fonctions de limite ou de plage. Par exemple, vous pouvez combiner les méthodes StartAt() et EndAt() pour limiter les résultats à une plage de valeurs spécifiée.

Même s'il n'y a qu'une seule correspondance pour la requête, l'instantané reste une liste. Il ne contient qu'un seul élément.

Limiter le nombre de résultats

Vous pouvez utiliser les LimitToFirst() et LimitToLast() méthodes pour définir un nombre maximal d'enfants à synchroniser pour un rappel donné. Par exemple, si vous utilisez LimitToFirst() pour définir une limite de 100, vous ne recevez initialement que 100 rappels ChildAdded au maximum. Si vous avez moins de 100 éléments stockés dans votre base de données Firebase, un rappel ChildAdded est déclenché pour chaque élément.

Lorsque des éléments changent, vous recevez des rappels ChildAdded pour les éléments qui entrent dans la requête et des rappels ChildRemoved pour les éléments qui en sortent, de sorte que le nombre total reste à 100.

Par exemple, le code ci-dessous renvoie le meilleur score d'un classement :

      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
    }

Filtrer par clé ou par valeur

Vous pouvez utiliser StartAt(), EndAt() et EqualTo() pour choisir des points de départ, de fin et d'équivalence arbitraires pour les requêtes. Cela peut être utile pour paginer des données ou trouver des éléments avec des enfants ayant une valeur spécifique.

Ordre des données de requête

Cette section explique comment les données sont triées par chacune des méthodes de tri de la classe Query.

OrderByChild

Lorsque vous utilisez OrderByChild() , les données contenant la clé enfant spécifiée sont triées comme suit :

1. Les enfants dont la valeur de la clé enfant spécifiée est null apparaissent en premier.
2. Les enfants dont la valeur de la clé enfant spécifiée est false apparaissent ensuite. Si plusieurs enfants ont la valeur false, ils sont triés de manière lexicographique par clé.
3. Les enfants dont la valeur de true pour la clé enfant spécifiée apparaissent ensuite. Si plusieurs enfants ont la valeur true, ils sont triés de manière lexicographique par clé.
4. Les enfants ayant une valeur numérique apparaissent ensuite, triés par ordre croissant. Si plusieurs enfants ont la même valeur numérique pour le nœud enfant spécifié, ils sont triés par clé.
5. Les chaînes viennent après les nombres et sont triées de manière lexicographique par ordre croissant. Si plusieurs enfants ont la même valeur pour le nœud enfant spécifié, ils sont triés de manière lexicographique par clé.
6. Les objets apparaissent en dernier et sont triés de manière lexicographique par clé dans l'ordre croissant.

OrderByKey

Lorsque vous utilisez OrderByKey() pour trier vos données, les données sont renvoyées par ordre croissant par clé.

1. Les enfants dont la clé peut être analysée comme un entier 32 bits apparaissent en premier, triés par ordre croissant.
2. Les enfants dont la clé est une valeur de chaîne apparaissent ensuite, triés de manière lexicographique par ordre croissant.

OrderByValue

Lorsque vous utilisez OrderByValue() , les enfants sont triés par leur valeur. Les critères de tri sont les mêmes que dans OrderByChild(), sauf que la valeur du nœud est utilisée à la place de la valeur d'une clé enfant spécifiée.