Google 致力于为黑人社区推动种族平等。查看具体举措

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 la base de données en temps réel , 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 ne disposez pas d' un projet Unity, vous pouvez télécharger une application de l' échantillon .

  • Ajouter l' unité Firebase SDK (spécifiquement, FirebaseDatabase.unitypackage ) à votre projet Unity.

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

Récupération des données

Firebase données sont récupérées soit par un appel d'une durée de GetValueAsync () ou de la fixation d'un événement sur un FirebaseDatabase référence. L'écouteur d'événement 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 GetValueAsync méthode pour lire un instantané statique du contenu à un chemin donné une fois. 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 pas de données, l'instantané retournée 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...
        }
      });

Écouter les événements

Vous pouvez ajouter des écouteurs d'événement 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 changements aux listes.
ChildChanged Écoutez les modifications apportées aux éléments d'une liste. Utilisation avec ChildAdded et ChildRemoved pour surveiller les changements aux listes.
ChildRemoved Écoutez les éléments supprimés d'une liste. Utilisation avec ChildAdded et ChildChanged pour surveiller les changements aux listes.
ChildMoved Écoutez les modifications apportées à l'ordre des éléments dans une liste ordonnée. ChildMoved événements suivent toujours le ChildChanged événement qui a causé l'ordre de changement de l'élément ( en fonction de votre commande par méthode actuelle).

Événement ValueChanged

Vous pouvez utiliser le ValueChanged événement pour souscrire à des changements du contenu à 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 pas de données, l'instantané retournée est null .

L'exemple suivant illustre 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. Appel de Value sur un instantané renvoie un Dictionary<string, object> représentant les données. Si aucune donnée existe à l'emplacement, appelant Value des rendements 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'a pas l'autorisation de lire à partir d'un emplacement de base de données Firebase. Le DatabaseError indiquera pourquoi l'échec.

Vous pouvez ensuite vous désabonner de l'événement en utilisant une DatabaseReference qui a le même chemin. DatabaseReference cas sont éphémères et peuvent être considérés comme un moyen d'accéder à un chemin et requête.

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

Événements enfants

Les événements d'enfants sont déclenchées en réponse à des opérations spécifiques qui se produisent aux enfants d'un noeud à partir d' une opération, comme un enfant nouveau ajouté par l'intermédiaire du Push() méthode ou un être mis à jour par l'enfant 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
    }

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

Le 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 ChildAdded et ChildRemoved événements pour répondre aux modifications apportées à une liste d'éléments. L'instantané transmis à l'écouteur d'événement contient les données mises à jour pour l'enfant.

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

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

Trier et filtrer les données

Vous pouvez utiliser la base de données en temps réel de Query de classe pour récupérer des données triées par clé, en valeur, ou valeur d'un enfant. Vous pouvez également filtrer le résultat trié en fonction d'un nombre spécifique de résultats ou d'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 comment les résultats sont classés :

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

Vous ne pouvez utiliser qu'un seul ordre par la méthode à 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 inscrire à un classement de score 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'il est combiné avec un écouteur d'événement valueChanged synchronise le client avec le leaderboard dans la base de données, commandé par le score de chaque entrée. Vous pouvez en savoir plus sur la structuration de vos données de manière efficace dans la structure de votre base de données .

L'appel à la OrderByChild() méthode spécifie la clé de l' enfant à l' ordre par les résultats. Dans ce cas, les résultats sont triés par la valeur du "score" valeur de chaque enfant. Pour plus d' informations sur d' autres types de données sont ordonnées, voir comment la requête des données est ordonnée .

Filtrage des données

Pour filtrer les données, vous pouvez combiner l'une des méthodes 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 maximal d'éléments à renvoyer à partir du début de la liste ordonnée des résultats.
LimitToLast() Définit le nombre maximal 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 selon 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 des é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 StartAt() et EndAt() méthodes pour limiter les résultats à une plage de valeurs.

Même lorsqu'il n'y a qu'une seule correspondance pour la requête, l'instantané est toujours une liste ; il ne contient qu'un seul élément.

Limiter le nombre de résultats

Vous pouvez utiliser le LimitToFirst() et LimitToLast() méthodes pour définir un nombre maximum d'enfants pour être synchronisés un rappel donné. Par exemple, si vous utilisez LimitToFirst() pour définir une limite de 100, vous recevez d' abord que jusqu'à 100 ChildAdded callbacks. Si vous avez moins de 100 éléments stockés dans la base de données Firebase, un ChildAdded feux de rappel pour chaque élément.

Comme éléments changent, vous recevez ChildAdded callbacks pour les éléments qui entrent dans la requête et ChildRemoved callbacks pour les articles qui abandonnent pour que le nombre total de séjours à 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() choisir départ arbitraire, la fin et les points d'équivalence pour les requêtes. Cela peut être utile pour paginer des données ou rechercher des éléments avec des enfants qui ont 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 chacun de l'ordre par des méthodes dans la Query classe.

OrderByChild

Lors de l' utilisation OrderByChild() , les données qui contient la clé de l' enfant spécifié est ordonné comme suit:

  1. Les enfants ayant une null valeur de la clé de l' enfant spécifié viennent en premier.
  2. Les enfants ayant une valeur de false pour la clé de l' enfant spécifié viennent ensuite. Si plusieurs enfants ont une valeur de false , ils sont triés lexicographique par clé.
  3. Les enfants ayant une valeur de true pour la clé de l' enfant spécifié viennent ensuite. Si plusieurs enfants ont une valeur de true , ils sont classés par ordre lexicographique clé.
  4. Les enfants avec 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 arrivent en dernier et sont triés lexicographiquement par clé dans l'ordre croissant.

OrderByKey

Lors de l' utilisation OrderByKey() pour trier vos données, les données sont renvoyées en ordre croissant par clé.

  1. Les enfants avec une clé qui peut ê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

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