Recupero dei dati con Firebase Realtime Database per C++

Questo documento tratta le nozioni di base sul recupero dei dati e su come ordinarli e filtrarli.

Prima di iniziare

Assicurati di aver configurato l'app e di poter accedere al database come descritto nella guida Get Started.

Recupero dei dati in corso…

I dati di Firebase vengono recuperati tramite una chiamata una tantum a GetValue() o collegandosi a un ValueListener su un riferimento FirebaseDatabase. Il listener di valori viene chiamato una volta per lo stato iniziale dei dati e di nuovo ogni volta che i dati cambiano.

Recuperare un DatabaseReference

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

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

Lettura dei dati una sola volta

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

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

Nel momento in cui è stata effettuata la richiesta, ma dobbiamo attendere il completamento di Future prima di poter leggere il valore. Poiché i giochi vengono eseguiti in genere in un ciclo e sono meno basati su callback rispetto ad altre applicazioni, in genere esegui 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...
    }
  }

Vengono mostrati alcuni controlli di base degli errori. Consulta il riferimento firebase::Future per ulteriori informazioni sul controllo degli errori e sui modi per determinare quando il risultato è pronto.

Ascolta gli eventi

Puoi aggiungere listener per ricevere notifiche in caso di modifiche ai dati:

ValueListener classe base

Callback	Utilizzo tipico
OnValueChanged	Leggi e ascolta le modifiche all'intero contenuto di un percorso.

OnChildListener classe base

OnChildAdded	Recuperare elenchi di elementi o ascoltare le aggiunte a un elenco di elementi. Utilizzo consigliato con OnChildChanged e OnChildRemoved per monitorare le modifiche apportate agli elenchi.
OnChildChanged	Ascolta le modifiche apportate agli elementi di un elenco. Utilizza con OnChildAdded e OnChildRemoved per monitorare le modifiche agli elenchi.
OnChildRemoved	Ascolta gli elementi rimossi da un elenco. Utilizza 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 dovuti alla modifica dell'ordine dell'elemento (in base al metodo di ordinamento corrente).

Classe ValueListener

Puoi utilizzare i OnValueChangedcallback per iscriverti alle modifiche ai contenuti in un determinato percorso. Questo callback viene attivato una volta quando il listener è collegato e di nuovo ogni volta che i dati, inclusi i figli, cambiano. La callback riceve 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 al database specificato, incluse le modifiche ai nodi secondari. Per limitare le dimensioni degli snapshot, allega solo il livello più alto necessario per monitorare le modifiche. Ad esempio, collegare un listener alla radice del database non è consigliato.

Il seguente esempio 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&ltfirebase::database::DataSnapshot&gt 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 di 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à il motivo dell'errore.

Classe ChildListener

Gli eventi secondari vengono attivati in risposta a operazioni specifiche che interessano i figli di un nodo da un'operazione come l'aggiunta di un nuovo figlio tramite il metodo PushChild() o l'aggiornamento di un figlio tramite il metodo UpdateChildren(). Ciascuno di questi elementi può essere utile per ascoltare le modifiche a un nodo specifico di 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&ltfirebase::database::DataSnapshot&gt 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 secondario. Sono incluse eventuali modifiche ai nodi secondari del nodo principale. Viene in genere utilizzato in combinazione con le 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 bambino.

Il callback OnChildRemoved viene attivato quando viene rimosso un elemento figlio immediato. Viene in genere utilizzato insieme ai callback OnChildAdded e OnChildChanged. Lo snapshot passato al callback contiene i dati del bambino 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 dati ordinati con OrderByChild o OrderByValue.

Ordinare e filtrare i dati

Puoi utilizzare la classe Realtime Database Query per recuperare i dati ordinati per chiave, per valore o per 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 :il filtraggio 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'ordine dei risultati:

Metodo	Utilizzo
OrderByChild()	Ordina i risultati in base al valore di una chiave secondaria specificata.
OrderByKey()	Ordina i risultati in base alle 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 order-by più volte nella stessa query genera un errore.

Il seguente esempio mostra come abbonarsi a una classifica dei punteggi 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.

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. Per saperne di più su come strutturare i dati in modo efficiente, consulta la sezione 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 di "score" in ogni elemento secondario. Per saperne di più sull'ordine degli altri tipi di dati, vedi Come vengono ordinati i dati delle query.

Filtrare i dati

Per filtrare i dati, puoi combinare uno qualsiasi 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 di risultati.
LimitToLast()	Imposta il numero massimo di elementi da restituire dalla fine dell'elenco ordinato di 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 quando esiste una sola corrispondenza per la query, lo snapshot è comunque un elenco, ma contiene un solo elemento.

Limitare il numero di risultati

Puoi utilizzare i metodi LimitToFirst() e LimitToLast() per impostare un numero massimo di figli da sincronizzare per un determinato callback. Ad esempio, se utilizzi LimitToFirst() per impostare un limite di 100, inizialmente riceverai solo fino a 100 callback OnChildAdded. Se hai meno di 100 elementi memorizzati nel database Firebase, viene attivata una richiamata OnChildAdded per ogni elemento.

Man mano che gli elementi cambiano, ricevi OnChildAdded callback per gli elementi che entrano nella query e OnChildRemoved callback per gli elementi che escono dalla query, in modo che il numero totale rimanga a 100.

Ad esempio, il codice riportato di seguito 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.

Filtrare per chiave o valore

Puoi utilizzare StartAt(), EndAt() e EqualTo() per scegliere punti di partenza, di arrivo e di equivalenza arbitrari per le query. Questo può essere utile per impaginare i dati o trovare elementi secondari con 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 nella classe Query.

OrderByChild

Quando utilizzi OrderByChild(), i dati che contengono la chiave secondaria specificata vengono ordinati nel seguente modo:

1. I bambini con un valore null per la chiave figlio specificata vengono visualizzati per primi.
2. I figli con un valore di false per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore di false, vengono ordinati lessicograficamente per chiave.
3. I figli con un valore di true per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore di true, vengono ordinati in ordine lessicografico in base alla chiave.
4. Seguono i bambini con un valore numerico, ordinati in ordine crescente. Se più elementi secondari hanno lo stesso valore numerico per il nodo secondario specificato, vengono ordinati per chiave.
5. 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 in ordine lessicografico per chiave.
6. Gli oggetti vengono visualizzati per ultimi e sono ordinati lessicograficamente per chiave in ordine crescente.

OrderByKey

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

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

OrderByValue

Quando si utilizza OrderByValue(), i bambini vengono ordinati in base al loro valore. I criteri di ordinamento sono gli stessi di OrderByChild(), tranne che viene utilizzato il valore del nodo anziché il valore di una chiave secondaria specificata.

Passaggi successivi

• Salvataggio dei dati