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 in the Get Started guida.

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.

Recupero di 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();

Lettura dei dati una sola volta

Puoi utilizzare il metodo GetValue() per leggere una sola volta uno snapshot statico dei contenuti in un determinato percorso. 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&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

A questo punto la richiesta è stata effettuata, ma dobbiamo attendere il completamento di Future prima di 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 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 base degli errori. Per ulteriori informazioni sul controllo degli errori e sui modi per determinare quando il risultato è pronto, consulta il riferimento firebase::Future .

Ascolta gli eventi

Puoi aggiungere listener per abbonarti alle modifiche dei dati:

Classe base ValueListener

Classe base OnChildListener

Classe ValueListener

Puoi utilizzare i callback OnValueChanged per abbonarti alle modifiche dei 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. 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.

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 a value() su uno snapshot restituisce una Variant che rappresenta i dati.

In questo esempio, viene eseguito l'override anche del 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 indicherà il motivo dell'errore.

Classe ChildListener

Gli eventi secondari vengono attivati in risposta a operazioni specifiche eseguite sui 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(). Ognuno di questi 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&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 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 un nodo figlio viene modificato. Sono incluse tutte le modifiche ai discendenti del nodo figlio. Viene in genere utilizzato insieme alle chiamate OnChildAdded e OnChildRemoved per rispondere alle modifiche a un elenco di elementi. Lo snapshot passato al listener contiene i dati aggiornati del 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 del figlio rimosso.

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

Ordinamento e filtro dei dati

Puoi 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, inizia specificando uno dei metodi di ordinamento per determinare l'ordine dei risultati:

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

Il seguente esempio mostra come puoi abbonarti 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 ogni voce. Puoi scoprire di più sulla strutturazione efficiente dei dati in Strutturare il 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 di "score" valore in ogni figlio. Per ulteriori informazioni su come vengono ordinati gli altri tipi di dati, consulta 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.

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; contiene solo un 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 ricevi solo fino a 100 callback OnChildAdded. Se nel database Firebase sono memorizzati meno di 100 elementi, viene attivato un callback OnChildAdded per ogni 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 pari 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 fine e di equivalenza arbitrari per le query. Questa operazione 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 da ciascuno dei metodi di ordinamento nella classe Query.

OrderByChild

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

1. I figli con un valore null per la chiave figlio specificata vengono visualizzati per primi.
2. I figli con un valore false per la chiave figlio specificata vengono visualizzati successivamente. Se più figli hanno un valore false, vengono ordinati lessicograficamente per chiave.
3. I figli con un valore true per la chiave figlio specificata vengono visualizzati successivamente. Se più figli hanno un valore true, vengono ordinati lessicograficamente per chiave.
4. I figli con un valore numerico vengono visualizzati successivamente, ordinati in ordine crescente. Se più figli hanno lo stesso valore numerico per il nodo figlio specificato, vengono ordinati per chiave.
5. Le stringhe vengono dopo i numeri e vengono ordinate lessicograficamente in ordine crescente ordine. Se più figli hanno lo stesso valore per il nodo figlio specificato, vengono ordinati lessicograficamente per chiave.
6. Gli oggetti vengono visualizzati per ultimi e vengono ordinati lessicograficamente per chiave in ordine crescente.

OrderByKey

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

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

OrderByValue

Quando utilizzi 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 anziché il valore di una chiave figlio specificata.

Passaggi successivi

• Salvataggio dei dati