Recupero dei dati con Firebase Realtime Database per C++

Questo documento illustra le nozioni di base per il recupero dei dati e 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

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 dati nel database, devi avere un'istanza di DatabaseReference:

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

Leggere i dati una 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 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 .

Ascoltare 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 dati 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.

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 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 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 dati secondari di un nodo, ad esempio l'aggiunta di un nuovo dato secondario tramite il metodo PushChild() o l'aggiornamento di un dato secondario tramite il metodo UpdateChildren(). Ognuno di questi metodi 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 dato secondario esistente e di nuovo ogni volta che viene aggiunto un nuovo dato secondario al percorso specificato. Al listener viene passato uno snapshot contenente i dati del nuovo dato secondario.

Il callback OnChildChanged viene chiamato ogni volta che un nodo secondario viene modificato. Sono incluse tutte le modifiche ai discendenti del nodo secondario. 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 dato secondario.

Il callback OnChildRemoved viene attivato quando viene rimosso un dato secondario immediato. Viene in genere utilizzato insieme ai callback OnChildAdded e OnChildChanged. Lo snapshot passato al callback contiene i dati del dato secondario rimosso.

Il callback OnChildMoved viene attivato ogni volta che la chiamata OnChildChanged viene generata da un aggiornamento che causa il riordino del dato secondario. Viene utilizzato con i 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 dato secondario. Puoi anche filtrare il risultato ordinato in base a un numero specifico di risultati o a un intervallo di chiavi o valori.

Ordinare 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 secondaria in base alla quale ordinare i risultati. In questo caso, i risultati vengono ordinati in base al valore di "score" valore in ogni dato secondario. 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 dati secondari 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, fine ed equivalenza arbitrari per le query. Questa operazione può essere utile per impaginare i dati o trovare elementi con dati secondari 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 secondaria specificata vengono ordinati come segue:

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

OrderByValue

Quando utilizzi OrderByValue(), i dati 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

• Salvare i dati