Récupération des données

Ce document couvre les bases de la récupération de données et comment trier et filtrer les données Firebase.

Avant que tu commences

Avant de pouvoir utiliser Realtime Database , vous devez :

  • 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 SDK Firebase Unity (en particulier FirebaseDatabase.unitypackage ) à votre projet Unity.

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

Récupération des données

Les données Firebase sont récupérées soit par un appel unique à GetValueAsync(), soit par attachement à 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 et à nouveau chaque fois que les données changent.

Obtenir une référence de base de données

Pour lire les données 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 fois

Vous pouvez utiliser la méthode GetValueAsync pour lire une fois un instantané statique du contenu sur un chemin donné. Le résultat de la tâche contiendra un instantané contenant toutes les données à cet emplacement, y compris les données enfants. S'il n'y a aucune donnée, l'instantané renvoyé est null .

    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...
        }
      });

Écoutez les événements

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

Événement Utilisation typique
ValueChanged Lisez et écoutez les modifications apportées à l'ensemble du contenu d'un chemin.
ChildAdded Récupérez des listes d’éléments ou écoutez les ajouts à une liste d’éléments. Utilisation suggérée avec ChildChanged et ChildRemoved pour surveiller les modifications apportées aux listes.
ChildChanged Écoutez les modifications apportées aux éléments d'une liste. À utiliser avec ChildAdded et ChildRemoved pour surveiller les modifications apportées aux listes.
ChildRemoved Écoutez les éléments supprimés d’une liste. À utiliser avec ChildAdded et ChildChanged pour surveiller les modifications apportées aux listes.
ChildMoved Écoutez les changements dans l’ordre des éléments dans une liste ordonnée. Les événements ChildMoved suivent toujours l'événement ChildChanged qui a provoqué la modification de l'ordre de l'élément (en fonction de votre méthode de tri actuelle).

Événement ValueChanged

Vous pouvez utiliser l'événement ValueChanged pour vous abonner aux modifications du contenu sur un chemin donné. Cet événement est déclenché une fois lorsque l'écouteur est attaché et à nouveau chaque fois que les données, y compris les enfants, changent. 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 aucune donnée, l'instantané renvoyé est null .

L'exemple suivant montre un jeu récupérant 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 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 indiquera pourquoi l’échec s’est produit.

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

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

Événements pour 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 méthode Push() ou un enfant mis à jour via la méthode UpdateChildrenAsync() . 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 indiqué 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'événement ChildAdded 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 à nouveau chaque fois qu'un nouvel enfant est ajouté au chemin spécifié. L'auditeur reçoit un instantané contenant les données du nouvel enfant.

L'événement ChildChanged 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 pour 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'événement ChildMoved est déclenché chaque fois que l'événement ChildChanged est déclenché par une mise à jour qui provoque une réorganisation de l'enfant. Il est utilisé avec les données commandé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 order-by pour déterminer comment les résultats sont classés :

Méthode Usage
OrderByChild() Triez les résultats selon la valeur d’une clé enfant spécifiée.
OrderByKey() Trier les résultats par clés enfants.
OrderByValue() Triez les résultats par valeurs enfants.

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

L'exemple suivant montre comment vous pouvez vous abonner à un classement de scores classé 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
    }

Ceci définit une requête qui, lorsqu'elle est combinée avec un écouteur d'événement valuechanged , synchronise le client avec le classement de la base de données, classé par le score de chaque entrée. Vous pouvez en savoir plus sur la structuration efficace de vos données dans Structurez votre base de données .

L’appel à la méthode OrderByChild() spécifie la clé enfant selon laquelle trier les résultats. Dans ce cas, les résultats sont triés selon la valeur du "score" de chaque enfant. Pour plus d'informations sur la façon dont les autres types de données sont ordonnés, consultez Comment les données de requête sont ordonnées .

Filtrage des 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 construction d'une requête.

Méthode Usage
LimitToFirst() Définit le nombre maximum d'éléments à renvoyer à partir du début de la liste ordonnée des résultats.
LimitToLast() Définit le nombre maximum d'éléments à renvoyer à partir de la fin de la liste ordonnée des résultats.
StartAt() Renvoie les éléments supérieurs ou égaux à la clé ou à la valeur spécifiée en fonction de la méthode de tri choisie.
EndAt() Renvoie les éléments inférieurs ou égaux à la clé ou à la valeur spécifiée en fonction de la méthode de tri choisie.
EqualTo() Renvoie les éléments égaux à la clé ou à la valeur spécifiée en fonction de la méthode de tri choisie.

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 lorsqu'il n'existe 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 méthodes LimitToFirst() et LimitToLast() pour définir un nombre maximum d'enfants à synchroniser pour un rappel donné. Par exemple, si vous utilisez LimitToFirst() pour définir une limite de 100, vous ne recevrez initialement que 100 rappels ChildAdded . Si vous avez moins de 100 éléments stockés dans votre base de données Firebase, un rappel ChildAdded se déclenche pour chaque élément.

À mesure que les é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 afin 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 valeur

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

Comment les données de requête sont ordonnées

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

OrderByChild

Lors de l'utilisation OrderByChild() , les données contenant la clé enfant spécifiée sont classées comme suit :

  1. Les enfants avec une valeur null pour la clé enfant spécifiée viennent en premier.
  2. Les enfants avec une valeur false pour la clé enfant spécifiée viennent ensuite. Si plusieurs enfants ont la valeur false , ils sont triés lexicographiquement par clé.
  3. Les enfants avec une valeur true pour la clé enfant spécifiée viennent ensuite. Si plusieurs enfants ont la valeur true , ils sont triés lexicographiquement par clé.
  4. Les enfants ayant une valeur numérique viennent 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 lexicographiquement par ordre croissant. Si plusieurs enfants ont la même valeur pour le nœud enfant spécifié, ils sont classés lexicographiquement par clé.
  6. Les objets viennent en dernier et sont triés lexicographiquement par clé par 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 possédant une clé pouvant être analysée comme un entier de 32 bits viennent en premier, triés par ordre croissant.
  2. Les enfants avec une valeur de chaîne comme clé viennent ensuite, triés lexicographiquement par ordre croissant.

OrderByValue

Lors de l'utilisation OrderByValue() , les enfants sont classés selon leur valeur. Les critères de classement 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.