Recupero dei dati con Firebase Realtime Database per C++

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

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 del valore viene chiamato una volta per lo stato iniziale dei dati e di nuovo ogni volta che i dati cambiano.

Ottieni 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 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();

A questo punto, la richiesta è stata effettuata, ma dobbiamo attendere il completamento del Future prima di poter leggere il valore. Poiché i giochi vengono in genere eseguiti in un loop e sono meno basati su callback rispetto ad altre applicazioni, di solito 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 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 iscriverti alle modifiche ai dati:

Classe base ValueListener

Classe base OnChildListener

Classe ValueListener

Puoi utilizzare i callback OnValueChanged per iscriverti alle modifiche ai contenuti in un determinato percorso. Questo callback viene attivato una volta quando il listener viene collegato e di nuovo ogni volta che i dati, inclusi i nodi secondari, cambiano. Al callback viene passato uno snapshot contenente tutti i dati in quella posizione, inclusi i dati secondari. Se non sono presenti dati, l'istantanea restituita è 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&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 viene annullata. Ad esempio, una lettura può essere annullata se il client non dispone dell'autorizzazione per leggere da una posizione del database Firebase. database::Error indicherà il motivo dell'errore.

Classe ChildListener

Gli eventi figlio vengono attivati in risposta a operazioni specifiche che si verificano sui figli di un nodo, ad esempio l'aggiunta di un nuovo figlio tramite il metodo PushChild() o l'aggiornamento di un figlio tramite il metodo UpdateChildren(). Ognuno 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 elemento secondario esistente e poi di nuovo ogni volta che viene aggiunto un nuovo elemento secondario al percorso specificato. Al listener viene passato uno snapshot contenente i dati del nuovo elemento secondario.

Il callback OnChildChanged viene chiamato ogni volta che un nodo secondario viene modificato. Sono incluse eventuali modifiche ai discendenti del nodo secondario. In genere viene 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 l'elemento secondario.

Il callback OnChildRemoved viene attivato quando viene rimosso un elemento secondario immediato. In genere viene utilizzato insieme ai 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 generata da un aggiornamento che causa il riordinamento del nodo secondario. Viene utilizzata 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 elemento secondario. 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 di un metodo di ordinamento 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.

In questo modo viene definito 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 Struttura il tuo 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ù 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, 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 solo fino a 100 callback OnChildAdded. Se nel tuo database Firebase sono archiviati 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 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, fine ed equivalenza arbitrari per le query. Questo può essere utile per impaginare i dati o trovare elementi con elementi secondari 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 di ordinamento nella classe Query.

OrderByChild

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

1. I nodi secondari con un valore null per la chiave secondaria specificata vengono visualizzati per primi.
2. Seguono i nodi secondari con un valore di false per la chiave secondaria specificata. Se più elementi secondari hanno un valore false, vengono ordinati lessicograficamente in base alla chiave.
3. Seguono i nodi secondari con un valore di true per la chiave secondaria specificata. Se più elementi secondari hanno un valore true, vengono ordinati in ordine lessicografico per 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 per chiave.
5. Le stringhe vengono dopo i numeri e sono ordinate lessicograficamente in ordine crescente. Se più elementi secondari hanno lo stesso valore per il nodo secondario 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 nodi secondari con una chiave che può essere analizzata come un numero intero a 32 bit vengono visualizzati per primi, ordinati in ordine crescente.
2. Seguono gli elementi secondari con un valore di stringa come chiave, ordinati lessicograficamente in ordine crescente.

OrderByValue

Quando utilizzi OrderByValue(), gli elementi secondari vengono ordinati in base al loro valore. I criteri di ordinamento sono gli stessi di OrderByChild(), ad eccezione del fatto che viene utilizzato il valore del nodo anziché il valore di una chiave secondaria specificata.

Passaggi successivi

• Salvataggio dei dati