Questo documento illustra le nozioni di base sul recupero dei dati e su come ordinare e filtrare i dati di Firebase.
Prima di iniziare
Assicurati di aver configurato la tua app e di poter accedere al database come indicato nella Guida Get Started .
Recupero dati
I dati di Firebase vengono recuperati da una singola chiamata a GetValue() o dal collegamento a un ValueListener su un riferimento FirebaseDatabase . Il value listener viene chiamato una volta per lo stato iniziale dei dati e di nuovo ogni volta che i dati cambiano.
Ottieni un riferimento al database
Per scrivere i dati nel database, è necessaria un'istanza di DatabaseReference :
// Get the root reference location of the database.
firebase::database::DatabaseReference dbref = database->GetReference();
Leggere i dati una volta
È possibile utilizzare il metodo GetValue() per leggere una sola volta un'istantanea statica dei contenuti in un determinato percorso. Il risultato dell'attività conterrà uno snapshot contenente tutti i dati in quella posizione, inclusi i dati figlio. Se non sono presenti dati, lo snapshot restituito è null .
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").GetValue();
Al punto la richiesta è stata fatta ma dobbiamo attendere il completamento del Future prima di poter leggere il valore. Poiché i giochi in genere vengono eseguiti in un ciclo e sono meno richiamati rispetto ad altre applicazioni, in genere eseguirai il polling per il completamento.
// 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...
}
}
Questo mostra alcuni controlli di errore di base, vedere il riferimento firebase::Future per ulteriori informazioni sul controllo degli errori e modi per determinare quando il risultato è pronto.
Ascolta gli eventi
Puoi aggiungere ascoltatori a cui iscriversi in caso di modifiche ai dati:
Classe di base ValueListener
| Richiamare | Uso tipico |
|---|---|
OnValueChanged | Leggere e ascoltare le modifiche all'intero contenuto di un percorso. |
Classe base OnChildListener
OnChildAdded | Recupera elenchi di elementi o ascolta le aggiunte a un elenco di elementi. Utilizzo consigliato con OnChildChanged e OnChildRemoved per monitorare le modifiche agli elenchi. |
OnChildChanged | Ascolta le modifiche agli elementi in un elenco. Utilizzare con OnChildAdded e OnChildRemoved per monitorare le modifiche agli elenchi. |
OnChildRemoved | Ascolta gli elementi che vengono rimossi da un elenco. Utilizzare con OnChildAdded e OnChildChanged per monitorare le modifiche agli elenchi. |
OnChildMoved | Ascolta le modifiche all'ordine degli elementi in un elenco ordinato. I callback OnChildMoved seguono sempre i callback OnChildChanged a causa della modifica dell'ordine dell'elemento (in base al metodo order-by corrente). |
Classe ValueListener
È possibile utilizzare i callback OnValueChanged per sottoscrivere le modifiche ai contenuti in un determinato percorso. Questa richiamata viene attivata una volta quando il listener è collegato e di nuovo ogni volta che i dati, inclusi i figli, cambiano. Al callback viene passato uno snapshot contenente tutti i dati in quella posizione, inclusi i dati figlio. Se non sono presenti dati, lo snapshot restituito è null .
L'esempio seguente mostra un gioco che recupera i punteggi di una classifica dal database:
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);
Il risultato Future<DataSnaphot> contiene i dati nella posizione specificata nel database al momento dell'evento. La chiamata value() su uno snapshot restituisce un Variant che rappresenta i dati.
In questo esempio, viene eseguito l'override anche del metodo OnCancelled per verificare se la lettura è stata annullata. Ad esempio, una lettura può essere annullata se il client non dispone dell'autorizzazione per leggere da una posizione del database Firebase. Il database::Error indicherà perché si è verificato l'errore.
Classe ChildListener
Gli eventi figlio vengono attivati in risposta a operazioni specifiche che si verificano sui figli di un nodo da un'operazione come un nuovo figlio aggiunto tramite il metodo PushChild() o un figlio aggiornato tramite il metodo UpdateChildren() . Ognuno di questi insieme può essere utile per ascoltare le modifiche a un nodo specifico in un database. Ad esempio, un gioco potrebbe utilizzare questi metodi insieme per monitorare l'attività nei commenti di una sessione di gioco, come mostrato di seguito:
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);
Il callback OnChildAdded viene in genere utilizzato per recuperare un elenco di elementi in un database Firebase. Il callback OnChildAdded viene chiamato una volta per ogni figlio esistente e poi di nuovo ogni volta che viene aggiunto un nuovo figlio al percorso specificato. Al listener viene passato uno snapshot contenente i dati del nuovo figlio.
Il callback OnChildChanged viene chiamato ogni volta che viene modificato un nodo figlio. Ciò include qualsiasi modifica ai discendenti del nodo figlio. Viene in genere utilizzato insieme alle chiamate OnChildAdded e OnChildRemoved per rispondere alle modifiche apportate a un elenco di elementi. Lo snapshot passato al listener contiene i dati aggiornati per il figlio.
Il callback OnChildRemoved viene attivato quando viene rimosso un figlio immediato. Viene in genere utilizzato insieme ai callback OnChildAdded e OnChildChanged . Lo snapshot passato al callback contiene i dati per il figlio rimosso.
Il callback OnChildMoved viene attivato ogni volta che la chiamata OnChildChanged viene generata da un aggiornamento che causa il riordino del figlio. Viene utilizzato con i dati ordinati con OrderByChild o OrderByValue .
Ordinamento e filtraggio dei dati
È possibile utilizzare la classe Realtime Database Query per recuperare i dati ordinati per chiave, per valore o per valore di un figlio. Puoi anche filtrare il risultato ordinato in base a un numero specifico di risultati o a un intervallo di chiavi o valori.
Ordina i dati
Per recuperare i dati ordinati, iniziare specificando uno dei metodi order-by per determinare come vengono ordinati i risultati:
| Metodo | Utilizzo |
|---|---|
OrderByChild() | Ordina i risultati in base al valore di una chiave figlio specificata. | OrderByKey() | Ordina i risultati per chiavi figlio. |
OrderByValue() | Ordina i risultati per valori figlio. |
Puoi utilizzare un solo metodo order-by alla volta. La chiamata di un metodo order-by più volte nella stessa query genera un errore.
L'esempio seguente mostra come puoi iscriverti a una classifica dei punteggi ordinata per punteggio.
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.
Questo definisce un firebase::Query che, se combinato con un ValueListener, sincronizza il client con la classifica nel database, ordinata in base al punteggio di ciascuna voce. Puoi leggere ulteriori informazioni su come strutturare i tuoi dati in modo efficiente in Struttura il tuo database .
La chiamata al metodo OrderByChild() specifica la chiave figlio in base alla quale ordinare i risultati. In questo caso, i risultati vengono ordinati in base al valore del valore "score" in ciascun figlio. Per ulteriori informazioni su come vengono ordinati altri tipi di dati, vedere Come vengono ordinati i dati delle query .
Filtraggio dei dati
Per filtrare i dati, puoi combinare qualsiasi metodo limit o range con un metodo order-by durante la costruzione di una query.
| Metodo | Utilizzo |
|---|---|
LimitToFirst() | Imposta il numero massimo di elementi da restituire dall'inizio dell'elenco ordinato di risultati. |
LimitToLast() | Imposta il numero massimo di elementi da restituire dalla fine dell'elenco ordinato di risultati. |
StartAt() | Restituisce elementi maggiori o uguali alla chiave o al valore specificato a seconda del metodo di ordinazione scelto. |
EndAt() | Restituisce gli elementi inferiori o uguali alla chiave o al valore specificato a seconda del metodo di ordinazione scelto. |
EqualTo() | Restituisce elementi uguali alla chiave o al valore specificato a seconda del metodo di ordinazione scelto. |
A differenza dei metodi order-by, è possibile combinare più funzioni limite o intervallo. Ad esempio, è possibile combinare i metodi StartAt() e EndAt() per limitare i risultati a un intervallo di valori specificato.
Anche quando c'è solo una singola corrispondenza per la query, lo snapshot è ancora un elenco; contiene solo un singolo elemento.
Limita il numero di risultati
È possibile utilizzare i metodi LimitToFirst() e LimitToLast() per impostare un numero massimo di elementi secondari da sincronizzare per un determinato callback. Ad esempio, se utilizzi LimitToFirst() per impostare un limite di 100, inizialmente riceverai solo fino a 100 richiamate OnChildAdded . Se hai meno di 100 elementi archiviati nel database Firebase, viene attivata una richiamata OnChildAdded per ciascun elemento.
Man mano che gli elementi cambiano, ricevi callback OnChildAdded per gli elementi che entrano nella query e callback OnChildRemoved per gli elementi che ne escono in modo che il numero totale rimanga a 100.
Ad esempio, il codice seguente restituisce il punteggio più alto da una classifica:
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.
Filtra per chiave o valore
È possibile utilizzare StartAt() , EndAt() e EqualTo() per scegliere punti iniziali, finali e di equivalenza arbitrari per le query. Questo può essere utile per impaginare i dati o trovare elementi con figli che hanno un valore specifico.
Come vengono ordinati i dati delle query
Questa sezione spiega come i dati vengono ordinati in base a ciascuno dei metodi order-by nella classe Query .
OrderByChild
Quando si utilizza OrderByChild() , i dati che contengono la chiave figlio specificata vengono ordinati come segue:
- Gli elementi figlio con un valore
nullper la chiave figlio specificata vengono per primi. - I bambini con un valore
falseper la chiave figlio specificata vengono dopo. Se più figli hanno un valorefalse, vengono ordinati lessicograficamente per chiave. - I bambini con un valore
trueper la chiave figlio specificata vengono dopo. Se più figli hanno un valoretrue, vengono ordinati lessicograficamente per chiave. - Seguono i bambini con un valore numerico, ordinati in ordine crescente. Se più figli hanno lo stesso valore numerico per il nodo figlio specificato, vengono ordinati per chiave.
- Le stringhe vengono dopo i numeri e sono ordinate lessicograficamente in ordine crescente. Se più figli hanno lo stesso valore per il nodo figlio specificato, vengono ordinati lessicograficamente per chiave.
- Gli oggetti vengono per ultimi e sono ordinati lessicograficamente per chiave in ordine crescente.
OrderByKey
Quando si utilizza OrderByKey() per ordinare i dati, i dati vengono restituiti in ordine crescente per chiave.
- I bambini con una chiave che può essere analizzata come numero intero a 32 bit vengono prima, ordinati in ordine crescente.
- Seguono i bambini con un valore stringa come chiave, ordinati lessicograficamente in ordine crescente.
OrderByValue
Quando si utilizza OrderByValue() , i figli vengono ordinati in base al loro valore. I criteri di ordinamento sono gli stessi di OrderByChild() , tranne per il fatto che viene utilizzato il valore del nodo invece del valore di una chiave figlio specificata.