Récupérer des données avec Firebase Realtime Database pour C++

Ce document aborde les principes de base 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

Assurez-vous d'avoir configuré votre application et de pouvoir accéder à la base de données, comme indiqué dans le guide Get Started.

Récupération des données

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

Obtenir un DatabaseReference

Pour écrire des données dans la base de données, vous avez besoin d'une instance de DatabaseReference :

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

Lire les données une seule fois

Vous pouvez utiliser la méthode GetValue() pour lire un instantané statique du contenu d'un chemin donné une seule 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é renvoyé est null.

  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

La requête a été effectuée, mais nous devons attendre que le Future se termine avant de pouvoir lire la valeur. Étant donné que les jeux s'exécutent généralement en boucle et sont moins axés sur les rappels que les autres applications, vous devez généralement interroger pour savoir si l'opération est terminée.

  // In the game loop that polls for the result...

  if (result.status() != firebase::kFutureStatusPending) {
    if (result.status() != firebase::kFutureStatusComplete) {
      LogMessage("ERROR: GetValue() returned an invalid result.");
      // Handle the error...
    } else if (result.error() != firebase::database::kErrorNone) {
      LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
                 result.error_message());
      // Handle the error...
    } else {
      firebase::database::DataSnapshot snapshot = result.result();
      // Do something with the snapshot...
    }
  }

Cela montre une vérification d'erreur de base. Consultez la référence firebase::Future pour en savoir plus sur la vérification d'erreur et sur les moyens de déterminer quand le résultat est prêt.

Écouter les événements

Vous pouvez ajouter des écouteurs pour vous abonner aux modifications des données :

Classe de base ValueListener

Rappel	Utilisation typique
OnValueChanged	Lire et écouter les modifications apportées à l'ensemble du contenu d'un chemin.

Classe de base OnChildListener

OnChildAdded	Récupérer des listes d'éléments ou écouter les éléments ajoutés à une liste Utilisation suggérée avec OnChildChanged et OnChildRemoved pour surveiller les modifications apportées aux listes.
OnChildChanged	Écoutez les modifications apportées aux éléments d'une liste. Utilisez-le avec OnChildAdded et OnChildRemoved pour surveiller les modifications apportées aux listes.
OnChildRemoved	Écoutez les éléments supprimés d'une liste. Utilisez-le avec OnChildAdded et OnChildChanged pour surveiller les modifications apportées aux listes.
OnChildMoved	Écoutez les modifications apportées à l'ordre des éléments d'une liste ordonnée. Les rappels OnChildMoved suivent toujours les rappels OnChildChanged en raison de l'ordre des éléments qui change (en fonction de votre méthode de tri actuelle).

Classe ValueListener

Vous pouvez utiliser les rappels OnValueChanged pour vous abonner aux modifications apportées au contenu d'un chemin donné. Ce rappel est déclenché une fois lorsque l'écouteur est associé, puis chaque fois que les données, y compris les enfants, changent. Le rappel 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.

Important : L'événement OnValueChanged est appelé chaque fois que des données sont modifiées au niveau de la référence de base de données spécifiée, y compris les modifications apportées aux enfants. Pour limiter la taille de vos instantanés, n'associez-les qu'au niveau le plus élevé nécessaire pour observer les modifications. Par exemple, il n'est pas recommandé d'attacher un écouteur à la racine de votre base de données.

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

  class LeadersValueListener : public firebase::database::ValueListener {
   public:
    void OnValueChanged(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
                 error_message);
    }
  };

  // Elsewhere in the code...

  LeadersValueListener* listener = new LeadersValueListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

Le résultat Future&ltDataSnapshot&gt 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 Variant représentant les données.

Dans cet exemple, la méthode OnCancelled est également remplacée 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. Le database::Error indiquera la raison de l'échec.

Classe ChildListener

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 PushChild() ou un enfant mis à jour via la méthode UpdateChildren(). Combinés, ils peuvent être utiles pour écouter les modifications apportées à un nœud spécifique d'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 :

  class SessionCommentsChildListener : public firebase::database::ChildListener {
   public:
    void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
                        const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildRemoved(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot ...
    }
    void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
                 error_code, error_message);
    }
  };

  // elsewhere ....

  SessionCommentsChildListener* listener = new SessionCommentsChildListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

Le rappel OnChildAdded est généralement utilisé pour récupérer une liste d'éléments dans une base de données Firebase. Le rappel OnChildAdded est appelé une fois pour chaque enfant existant, puis à chaque fois qu'un nouvel enfant est ajouté au chemin spécifié. L'écouteur reçoit un instantané contenant les données du nouvel enfant.

Le rappel OnChildChanged est appelé chaque fois qu'un nœud enfant est modifié. Cela inclut toute modification apportée aux descendants du nœud enfant. Il est généralement utilisé conjointement avec les appels OnChildAdded et OnChildRemoved pour répondre aux modifications apportées à une liste d'éléments. L'instantané transmis au listener contient les données mises à jour pour l'enfant.

Le rappel OnChildRemoved est déclenché lorsqu'un enfant immédiat est supprimé. Il est généralement utilisé en association avec les rappels OnChildAdded et OnChildChanged. L'instantané transmis au rappel contient les données de l'enfant supprimé.

Le rappel OnChildMoved est déclenché chaque fois que l'appel OnChildChanged 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 les résultats triés pour obtenir un nombre spécifique de résultats ou une plage de clés ou de valeurs.

Remarque : Le filtrage et le tri peuvent être coûteux, en particulier lorsqu'ils sont effectués sur le client. Si votre application utilise des requêtes, définissez la règle .indexOn pour indexer ces clés sur le serveur et améliorer les performances des requêtes, comme décrit dans Indexer vos données.

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 l'ordre des résultats :

Méthode	Utilisation
OrderByChild()	Trie les résultats en fonction de 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'une seule méthode order-by à 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 s'abonner à un classement des scores, trié par score.

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score");

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

Cela définit un firebase::Query qui, lorsqu'il est combiné à un ValueListener, synchronise le client avec le classement dans la base de données, trié par 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 selon laquelle trier les résultats. Dans ce cas, les résultats sont triés par la valeur "score" de 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 l'une des méthodes de limite ou de plage avec une méthode d'ordre lorsque vous créez une requête.

Méthode	Utilisation
LimitToFirst()	Définit le nombre maximal d'éléments à renvoyer depuis le 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 dont la clé ou la valeur est supérieure ou égale à celle spécifiée, selon la méthode de tri choisie.
EndAt()	Renvoie les éléments dont la clé ou la valeur sont inférieures ou égales à celles spécifiées, selon la méthode de tri choisie.
EqualTo()	Renvoie les éléments égaux à la clé ou à la valeur spécifiées, en fonction de la méthode de tri choisie.

Contrairement aux méthodes order-by, vous pouvez combiner plusieurs fonctions limit ou range. 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'un seul résultat pour la requête, l'instantané reste une liste, mais 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 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 OnChildAdded au maximum. Si votre base de données Firebase contient moins de 100 éléments, un rappel OnChildAdded est déclenché pour chaque élément.

À mesure que les éléments changent, vous recevez des rappels OnChildAdded pour les éléments qui entrent dans la requête et des rappels OnChildRemoved 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 :

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

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 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 order-by de la classe Query.

OrderByChild

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

1. Les enfants dont la valeur null correspond à la clé enfant spécifiée sont affichés en premier.
2. Viennent ensuite les enfants dont la valeur est false pour la clé enfant spécifiée. Si plusieurs enfants ont une valeur de false, ils sont triés lexicographiquement par clé.
3. Viennent ensuite les enfants dont la valeur est true pour la clé enfant spécifiée. Si plusieurs enfants ont une valeur de true, ils sont triés de façon lexicographique par clé.
4. Les enfants avec une valeur numérique suivent, 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 par ordre lexicographique croissant. Si plusieurs enfants ont la même valeur pour le nœud enfant spécifié, ils sont triés de façon lexicographique par clé.
6. Les objets sont placés en dernier et triés de manière lexicographique par clé, dans l'ordre croissant.

OrderByKey

Lorsque vous utilisez OrderByKey() pour trier vos données, celles-ci sont renvoyées par clé dans l'ordre croissant.

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

OrderByValue

Lorsque vous utilisez OrderByValue(), les enfants sont classés par ordre de 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.

Étapes suivantes

• Enregistrer des données