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
Assurez-vous que vous avez configuré votre application et que vous pouvez 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 soit par un appel unique à GetValue() , soit en les attachant à un ValueListener sur une référence FirebaseDatabase . L'écouteur de valeur 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 é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 fois
Vous pouvez utiliser la méthode GetValue() pour lire une fois un instantané statique du contenu d'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 pas de données, l'instantané renvoyé est null .
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").GetValue();
Au moment où la demande a été faite, nous devons attendre que 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 interrogerez généralement l'achèvement.
// 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 quelques vérifications d'erreurs de base, voir la référence firebase::Future pour plus d'informations sur la vérification des erreurs et les moyens de déterminer quand le résultat est prêt.
Écoutez les événements
Vous pouvez ajouter des écouteurs pour s'abonner aux modifications apportées aux données :
Classe de base ValueListener
| Rappeler | Utilisation typique |
|---|---|
OnValueChanged | Lisez et écoutez les modifications apportées à l'intégralité du contenu d'un chemin. |
Classe de base OnChildListener
OnChildAdded | Récupérez des listes d'éléments ou écoutez les ajouts à une liste d'éléments. 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. À utiliser avec OnChildAdded et OnChildRemoved pour surveiller les modifications apportées aux listes. |
OnChildRemoved | Écoutez les éléments supprimés d'une liste. À utiliser avec OnChildAdded et OnChildChanged pour surveiller les modifications apportées aux listes. |
OnChildMoved | Écoutez les modifications apportées à l'ordre des éléments dans une liste ordonnée. Les rappels OnChildMoved suivent toujours les rappels OnChildChanged en raison du changement de commande de l'article (en fonction de votre méthode de commande actuelle). |
Classe ValueListenerValueListener class
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 attaché et à nouveau 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 .
L'exemple suivant illustre un jeu récupérant 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<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").AddValueListener(listener);
Le résultat Future<DataSnaphot> 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 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. La database::Error indiquera pourquoi l'échec s'est produit.
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() . Chacun de ces ensembles 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 :
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<firebase::database::DataSnapshot> 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 à nouveau 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 toutes les modifications apportées 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 à l'écouteur 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é conjointement 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 provoque la réorganisation de l'enfant. Il est utilisé avec des données ordonné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 sur 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 triés :
| Méthode | Usage |
|---|---|
OrderByChild() | Trier les résultats par la valeur d'une clé enfant spécifiée. | OrderByKey() | Trier les résultats par clés enfants. |
OrderByValue() | Trier 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 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 de score classé 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é avec un ValueListener, 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 Structurer votre base de données .
L'appel à la méthode OrderByChild() spécifie la clé enfant par laquelle ordonner les résultats. Dans ce cas, les résultats sont triés par la valeur de la valeur "score" dans chaque enfant. Pour plus d'informations sur la façon dont les autres types de données sont triés, voir Comment les données de requête sont triées .
Filtrage des données
Pour filtrer les données, vous pouvez combiner n'importe laquelle 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 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 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 selon 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'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 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 recevez initialement que 100 rappels OnChildAdded . Si vous avez moins de 100 éléments stockés dans votre base de données Firebase, un rappel OnChildAdded se déclenche pour chaque élément.
Au fur et à 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 afin 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 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 rechercher des éléments avec des enfants qui ont une valeur spécifique.
Comment les données de la requête sont triées
Cette section explique comment les données sont triées par chacune des méthodes de tri dans la classe Query .
OrderByChild
Lors de l'utilisation OrderByChild() , les données contenant la clé enfant spécifiée sont triées comme suit :
- Les enfants avec une valeur
nullpour la clé enfant spécifiée viennent en premier. - Les enfants avec une valeur
falsepour la clé enfant spécifiée viennent ensuite. Si plusieurs enfants ont la valeurfalse, ils sont triés lexicographiquement par clé. - Les enfants avec une valeur
truepour la clé enfant spécifiée viennent ensuite. Si plusieurs enfants ont la valeurtrue, ils sont triés lexicographiquement par clé. - 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é.
- 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 triés lexicographiquement par clé.
- Les objets viennent en dernier et sont triés lexicographiquement par clé dans l'ordre croissant.
OrderByKey
Lorsque vous utilisez OrderByKey() pour trier vos données, les données sont renvoyées dans l'ordre croissant par clé.
- Les enfants avec une clé qui peut être analysée comme un entier 32 bits viennent en premier, triés par ordre croissant.
- 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 triés par 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.