Recupero dei dati con Firebase Realtime Database per C++

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 l'app e di poter accedere al database come descritto nella guida di Get Started.

Recupero dei dati

I dati di Firebase vengono recuperati tramite una chiamata una tantum a GetValue() o tramite l'associazione a un ValueListener in un riferimento FirebaseDatabase. L'ascoltatore di valore viene chiamato una volta per lo stato iniziale dei dati e di nuovo ogni volta che i dati cambiano.

Recuperare un DatabaseReference

Per scrivere dati nel database, devi avere un'istanza di DatabaseReference:

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

Leggi i dati una volta

Puoi utilizzare il metodo GetValue() per leggere un'istantanea statica dei contenuti in un determinato percorso una volta sola. Il risultato dell'attività conterrà uno snapshot contenente tutti i dati in quella posizione, inclusi i dati secondari. Se non sono presenti dati, lo snapshot restituito è null.

  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").GetValue();

Una volta effettuata la richiesta, dobbiamo attendere il completamento del Future per poter leggere il valore. Poiché i giochi in genere vengono eseguiti in un loop e sono meno basati su callback rispetto ad altre applicazioni, in genere esegui un 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. Consulta la documentazione di riferimento di firebase::Future per ulteriori informazioni sui controlli di errore e sui modi per determinare quando il risultato è pronto.

Ascolta gli eventi

Puoi aggiungere ascoltatori da iscriversi alle modifiche ai dati:

Classe base ValueListener

Callback	Utilizzo tipico
OnValueChanged	Leggere e ascoltare le modifiche a tutti i contenuti 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	Rileva le modifiche agli elementi di un elenco. Da utilizzare con OnChildAdded e OnChildRemoved per monitorare le modifiche agli elenchi.
OnChildRemoved	Ascolta gli elementi che vengono rimossi da un elenco. Da utilizzare con OnChildAdded e OnChildChanged per monitorare le modifiche agli elenchi.
OnChildMoved	Rileva le modifiche all'ordine degli elementi in un elenco ordinato. I callback OnChildMoved seguono sempre i callback OnChildChanged a causa della variazione dell'ordine degli elementi (in base al metodo di ordinamento corrente).

Classe ValueListener

Puoi utilizzare i OnValueChanged callback per iscriverti alle modifiche ai contenuti in un determinato percorso. Questo callback viene attivato una volta quando l'ascoltatore è collegato e di nuovo ogni volta che i dati, inclusi i secondari, cambiano. Al callback viene passato uno snapshot contenente tutti i dati in quella posizione, inclusi i dati secondari. Se non sono presenti dati, lo snapshot restituito è null.

Importante: l'evento OnValueChanged viene chiamato ogni volta che i dati vengono modificati nel riferimento del database specificato, incluse le modifiche ai figli. Per limitare le dimensioni degli istantanei, allegali solo al livello più alto necessario per monitorare le modifiche. Ad esempio, non è consigliabile collegare un ascoltatore alla radice del database.

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&ltDataSnapshot&gt contiene i dati nella posizione specificata nel database al momento dell'evento. La chiamata a value() su uno snapshot restituisce un Variant che rappresenta i dati.

In questo esempio, viene sostituito anche il metodo OnCancelled per verificare se la lettura viene annullata. Ad esempio, una lettura può essere annullata se il client non ha l'autorizzazione per leggere da una posizione del database Firebase. database::Error indicarà il motivo dell'errore.

Classe ChildListener

Gli eventi secondari vengono attivati in risposta a operazioni specifiche che si verificano nei figli di un nodo da un'operazione, ad esempio un nuovo figlio aggiunto tramite il metodo PushChild() o un figlio aggiornato tramite il metodo UpdateChildren(). Insieme, questi elementi possono essere utili per ascoltare le modifiche apportate a un node 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 elemento secondario esistente e poi di nuovo ogni volta che viene aggiunto un nuovo elemento secondario al percorso specificato. All'ascoltatore viene passato uno snapshot contenente i dati del nuovo bambino.

Il callback OnChildChanged viene chiamato ogni volta che un nodo secondario viene modificato. Sono incluse eventuali modifiche ai discendenti del nodo figlio. Viene solitamente utilizzato in combinazione con le chiamate OnChildAdded e OnChildRemoved per rispondere alle modifiche a un elenco di elementi. Lo snapshot passato all'ascoltatore contiene i dati aggiornati dell'elemento secondario.

Il callback OnChildRemoved viene attivato quando viene rimosso un elemento figlio immediato. Viene in genere utilizzato in combinazione con i callback OnChildAdded e OnChildChanged. Lo snapshot passato al callback contiene i dati dell'elemento secondario rimosso.

Il callback OnChildMoved viene attivato ogni volta che la chiamata OnChildChanged viene attivata da un aggiornamento che causa il riordinamento del figlio. Viene utilizzato con i dati ordinati con OrderByChild o OrderByValue.

Ordinamento e filtri dei dati

Puoi utilizzare la classe Realtime Database Query per recuperare i dati ordinati per chiave, valore o valore di un elemento secondario. Puoi anche filtrare il risultato ordinato in base a un numero specifico di risultati o a un intervallo di chiavi o valori.

Nota: l'applicazione di filtri e l'ordinamento possono essere costosi, soprattutto se eseguiti sul client. Se la tua app utilizza query, definisci la regola .indexOn per indicizzare queste chiavi sul server e migliorare le prestazioni delle query come descritto in Indicizzazione dei dati.

Ordinare i dati

Per recuperare i dati ordinati, inizia specificando uno dei metodi di ordinamento per determinare l'ordinamento dei risultati:

Metodo	Utilizzo
OrderByChild()	Ordina i risultati in base al valore di una chiave secondaria specificata.
OrderByKey()	Ordina i risultati per chiavi secondarie.
OrderByValue()	Ordina i risultati in base ai valori secondari.

Puoi utilizzare un solo metodo di ordinamento alla volta. La chiamata di un metodo di ordinamento più volte nella stessa query genera un errore.

L'esempio seguente mostra come iscriverti a una classifica con punteggio ordinata in base al 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 ogni voce. Puoi scoprire di più su come strutturare i dati in modo efficiente in Strutturare il database.

La chiamata al metodo OrderByChild() specifica la chiave secondaria in base alla quale ordinare i risultati. In questo caso, i risultati vengono ordinati in base al valore del valore "score" in ogni elemento secondario. Per ulteriori informazioni sull'ordinamento di altri tipi di dati, consulta Come vengono ordinati i dati delle query.

Filtrare i dati

Per filtrare i dati, puoi combinare uno dei metodi di limite o intervallo con un metodo di ordinamento durante la creazione di una query.

Metodo	Utilizzo
LimitToFirst()	Imposta il numero massimo di elementi da restituire dall'inizio dell'elenco ordinato dei risultati.
LimitToLast()	Imposta il numero massimo di elementi da restituire dalla fine dell'elenco ordinato dei risultati.
StartAt()	Restituisce gli elementi maggiori o uguali alla chiave o al valore specificato a seconda del metodo di ordinamento scelto.
EndAt()	Restituisce gli elementi minori o uguali alla chiave o al valore specificato a seconda del metodo di ordinamento scelto.
EqualTo()	Restituisce gli elementi uguali alla chiave o al valore specificato a seconda del metodo di ordinamento scelto.

A differenza dei metodi di ordinamento, puoi combinare più funzioni di limite o intervallo. Ad esempio, puoi combinare i metodi StartAt() e EndAt() per limitare i risultati a un intervallo di valori specificato.

Anche se esiste una sola corrispondenza per la query, lo snapshot è comunque un elenco, ma contiene un solo elemento.

Limita il numero di risultati

Puoi 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 fino a 100 callback LimitToFirst().OnChildAdded Se hai meno di 100 elementi archiviati nel database Firebase, viene attivato un callback OnChildAdded per ogni elemento.

Quando gli elementi cambiano, ricevi OnChildAdded callback per gli elementi che entrano nella query e OnChildRemoved callback per gli elementi che ne escono, in modo che il numero totale rimanga 100.

Ad esempio, il codice seguente restituisce il punteggio più alto di 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

Puoi utilizzare StartAt(), EndAt() e EqualTo() per scegliere punti di inizio, di fine ed equivalenza arbitrari per le query. Questo può essere utile per eseguire la paginazione dei dati o trovare elementi con elementi secondari che hanno un valore specifico.

Come vengono ordinati i dati delle query

Questa sezione spiega come vengono ordinati i dati in base a ciascuno dei metodi di ordinamento della classe Query.

OrderByChild

Quando utilizzi OrderByChild(), i dati che contengono la chiave secondaria specificata sono ordinati come segue:

1. I figli con un valore null per la chiave secondaria specificata vengono visualizzati per primi.
2. Gli elementi secondari con un valore false per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore false, vengono ordinati in ordine alfabetico in base alla chiave.
3. Gli elementi secondari con un valore true per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore true, vengono alfabetizzati in base alla chiave.
4. Seguono gli elementi secondari con un valore numerico, ordinati in ordine crescente. Se più elementi secondari hanno lo stesso valore numerico per il nodo secondario specificato, vengono ordinati in base alla chiave.
5. Le stringhe vengono visualizzate dopo i numeri e sono ordinate in ordine crescente in base alla loro sequenza lessicografica. Se più elementi figlio hanno lo stesso valore per il nodo figlio specificato, vengono ordinati in ordine alfabetico per chiave.
6. Gli oggetti sono gli ultimi e vengono ordinati in ordine lessicografico per chiave in ordine crescente.

OrderByKey

Quando utilizzi OrderByKey() per ordinare i dati, questi vengono restituiti in ordine crescente per chiave.

1. I figli con una chiave che può essere analizzata come numero intero a 32 bit vengono visualizzati per primi, in ordine crescente.
2. Seguono gli elementi secondari con una stringa come chiave, ordinati in ordine lessicografico crescente.

OrderByValue

Quando utilizzi OrderByValue(), gli elementi secondari 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 anziché il valore di una chiave secondaria specificata.

Passaggi successivi

• Risparmio dati