Recupero dati

Lettura dei dati con GET

Possiamo leggere i dati dal nostro database Firebase inviando una richiesta GET al suo endpoint URL. Continuiamo con il nostro esempio di blog della sezione precedente e leggiamo tutti i dati dei nostri post sul blog:

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

Una richiesta riuscita sarà indicata da un codice di stato HTTP 200 OK e la risposta conterrà i dati che stiamo recuperando.

Aggiunta di parametri URI

L'API REST accetta diversi parametri di query durante la lettura dei dati dal nostro database Firebase. Di seguito sono elencati i parametri più comunemente utilizzati. Per un elenco completo, fare riferimento a Riferimento API REST .

aut

Il parametro auth request consente l'accesso ai dati protetti dalle regole del database in tempo reale di Firebase ed è supportato da tutti i tipi di richiesta. L'argomento può essere il segreto dell'app Firebase o un token di autenticazione, come descritto in Utenti nei progetti Firebase . Nell'esempio seguente inviamo una richiesta GET con un parametro auth , dove CREDENTIAL è il segreto dell'app Firebase o un token di autenticazione:

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

Stampa

Specificando print=pretty i dati vengono restituiti in un formato leggibile.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

Specificando print=silent restituisce 204 No Content in caso di successo.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'

richiama

Per effettuare chiamate REST da un browser Web tra domini, puoi utilizzare JSONP per racchiudere la risposta in una funzione di callback JavaScript. Aggiungi callback= per fare in modo che l'API REST includa i dati restituiti nella funzione di callback specificata. Per esempio:

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

poco profondo

Questa è una funzionalità avanzata, progettata per aiutarti a lavorare con set di dati di grandi dimensioni senza dover scaricare tutto. Per usarlo, aggiungi shallow=true come parametro. Ciò limiterà la profondità dei dati restituiti. Se i dati nella posizione sono una primitiva JSON (stringa, numero o booleano), il suo valore verrà semplicemente restituito. Se lo snapshot dei dati nella posizione è un oggetto JSON, i valori per ciascuna chiave verranno troncati su true . Ad esempio, utilizzando i dati seguenti:

{
  "message": {
    "user": {
      "name": "Chris"
    },
    "body": "Hello!"
  }
}

// A request to /message.json?shallow=true
// would return the following:
{
  "user": true,
  "body": true
}

// A request to /message/body.json?shallow=true
// would simply return:
"Hello!"

Provalo con questa richiesta di curl :

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

tempo scaduto

Utilizzare questo per limitare la durata della lettura sul lato server. Se una richiesta di lettura non termina entro il tempo assegnato, termina con un errore HTTP 400. Ciò è particolarmente utile quando ti aspetti un piccolo trasferimento di dati e non vuoi aspettare troppo a lungo per recuperare un sottoalbero potenzialmente enorme. Il tempo di lettura effettivo potrebbe variare in base alla dimensione dei dati e alla memorizzazione nella cache.

Specificare i timeouts utilizzando il seguente formato: 3ms , 3s o 3min , con un numero e un'unità. Se non specificato verrà applicato il timeout massimo di 15min . Se il timeout non è positivo o supera il massimo, la richiesta verrà rifiutata con un errore HTTP 400. Nell'esempio seguente, la richiesta GET include un timeout di 10 secondi.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

Filtraggio dei dati

Possiamo costruire query per filtrare i dati in base a vari fattori. Per iniziare, specifichi come vuoi che i tuoi dati vengano filtrati usando il parametro orderBy . Quindi, combini orderBy con uno qualsiasi degli altri cinque parametri: limitToFirst , limitToLast , startAt , endAt e equalTo .

Dal momento che tutti noi di Firebase pensiamo che i dinosauri siano piuttosto interessanti, useremo uno snippet da un database campione di fatti sui dinosauri per dimostrare come puoi filtrare i dati:

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

Possiamo filtrare i dati in uno dei tre modi seguenti: per chiave figlio , per chiave o per valore . Una query inizia con uno di questi parametri, quindi deve essere combinata con uno o più dei seguenti parametri: startAt , endAt , limitToFirst , limitToLast o equalTo .

Filtraggio in base a una chiave figlio specificata

Possiamo filtrare i nodi in base a una chiave figlio comune passando quella chiave al parametro orderBy . Ad esempio, per recuperare tutti i dinosauri con un'altezza maggiore di 3, possiamo fare quanto segue:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Qualsiasi nodo che non ha la chiave figlio su cui stiamo filtrando verrà ordinato con un valore null . Per i dettagli su come vengono ordinati i dati, vedere Come vengono ordinati i dati .

Firebase supporta anche le query ordinate da bambini profondamente nidificati, piuttosto che solo da bambini di un livello inferiore. Questo è utile se hai dati profondamente nidificati come questo:

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

Per interrogare l'altezza ora, utilizziamo il percorso completo dell'oggetto anziché una singola chiave:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'

Le query possono filtrare solo per una chiave alla volta. L'utilizzo del parametro orderBy più volte sulla stessa richiesta genera un errore.

Filtraggio per chiave

Possiamo anche filtrare i nodi in base alle loro chiavi usando il orderBy="$key" . L'esempio seguente recupera tutti i dinosauri con un nome che inizia con la lettera a a m :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

Filtraggio per valore

Possiamo filtrare i nodi in base al valore delle loro chiavi figlio usando il orderBy="$value" . Diciamo che i dinosauri stanno partecipando a una competizione sportiva di dinosauri e stiamo tenendo traccia dei loro punteggi nel seguente formato:

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

Per recuperare tutti i dinosauri con un punteggio superiore a 50, potremmo fare la seguente richiesta:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

Vedere Come vengono ordinati i dati per una spiegazione su come vengono ordinati i valori null , boolean, string e oggetto quando si utilizza orderBy="$value" .

Filtraggio complesso

Possiamo combinare più parametri per costruire query più complesse.

Limita le query

I parametri limitToFirst e limitToLast vengono utilizzati per impostare un numero massimo di figli per i quali ricevere i dati. Se impostiamo un limite di 100, riceveremo solo fino a 100 bambini corrispondenti. Se abbiamo meno di 100 messaggi memorizzati nel nostro database, riceveremo ogni bambino. Tuttavia, se abbiamo più di 100 messaggi, riceveremo solo i dati per 100 di quei messaggi. Questi saranno i primi 100 messaggi ordinati se stiamo usando limitToFirst o gli ultimi 100 messaggi ordinati se stiamo usando limitToLast .

Usando il nostro database di fatti sui dinosauri e orderBy , possiamo trovare i due dinosauri più pesanti:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'

Allo stesso modo, possiamo trovare i due dinosauri più corti usando limitToFirst :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'

Possiamo anche condurre query sui limiti con orderBy="$value" . Se vogliamo creare una classifica con i primi tre concorrenti dino sport con il punteggio più alto, potremmo fare quanto segue:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

Intervallo di query

L'uso startAt , endAt e equalTo ci consente di scegliere punti di inizio e fine arbitrari per le nostre query. Ad esempio, se volessimo trovare tutti i dinosauri alti almeno tre metri, possiamo combinare orderBy e startAt :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Possiamo usare endAt per trovare tutti i dinosauri i cui nomi vengono prima di Pterodattilo lessicograficamente:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

Possiamo combinare startAt e endAt per limitare entrambe le estremità della nostra query. L'esempio seguente trova tutti i dinosauri il cui nome inizia con la lettera "b":

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

Le query di intervallo sono utili anche quando è necessario impaginare i dati.

Mettere tutto insieme

Possiamo combinare tutte queste tecniche per creare query complesse. Ad esempio, forse vuoi trovare il nome di tutti i dinosauri che sono più bassi o uguali in altezza al nostro tipo preferito, lo Stegosauro:

MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"`
curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"

Come vengono ordinati i dati

Questa sezione spiega come vengono ordinati i dati quando si utilizza ciascuno dei tre parametri di filtro.

ordinato da

Quando si utilizza orderBy con il nome di una chiave figlio, i dati che contengono la chiave figlio specificata verranno ordinati come segue:

  1. I bambini con un valore null per la chiave figlio specificata vengono prima.
  2. Seguono i figli con un valore false per la chiave figlio specificata. Se più figli hanno un valore di false , vengono ordinati lessicograficamente per chiave.
  3. I figli con un valore true per la chiave figlio specificata vengono dopo. Se più figli hanno un valore true , vengono ordinati lessicograficamente per chiave.
  4. I bambini con un valore numerico vengono dopo, 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 sono ordinate lessicograficamente in ordine crescente. Se più figli hanno lo stesso valore per il nodo figlio specificato, vengono ordinati lessicograficamente per chiave.
  6. Gli oggetti vengono per ultimi e ordinati lessicograficamente per chiave in ordine crescente.
I risultati filtrati vengono restituiti non ordinati. Se l'ordine dei tuoi dati è importante, dovresti ordinare i risultati nella tua applicazione dopo che sono stati restituiti da Firebase.

orderBy="$chiave"

Quando si utilizza il orderBy="$key" per ordinare i dati, i dati verranno restituiti in ordine crescente per chiave come segue. Tieni presente che le chiavi possono essere solo stringhe.

  1. I bambini con una chiave che può essere analizzata come un intero a 32 bit vengono prima, ordinati in ordine crescente.
  2. I bambini con un valore stringa come chiave vengono dopo, ordinati lessicograficamente in ordine crescente.

orderBy="$valore"

Quando si utilizza il orderBy="$value" per ordinare i dati, i bambini verranno ordinati in base al loro valore. I criteri di ordinamento sono gli stessi dei dati ordinati da una chiave figlio, tranne per il fatto che viene utilizzato il valore del nodo invece del valore di una chiave figlio specificata.

orderBy="$ priorità"

Quando si utilizza il orderBy="$priority" per ordinare i dati, l'ordinamento dei figli è determinato dalla loro priorità e chiave come segue. Tieni presente che i valori di priorità possono essere solo numeri o stringhe.

  1. I bambini senza priorità (impostazione predefinita) vengono prima.
  2. I bambini con un numero come priorità vengono dopo. Sono ordinati numericamente per priorità, da piccola a grande.
  3. I bambini con una stringa come priorità sono gli ultimi. Sono ordinati lessicograficamente per priorità.
  4. Ogni volta che due figli hanno la stessa priorità (inclusa nessuna priorità), vengono ordinati per chiave. I tasti numerici vengono prima (ordinati numericamente), seguiti dai tasti rimanenti (ordinati lessicograficamente).

Per ulteriori informazioni sulle priorità, vedere il riferimento API .

Streaming dall'API REST

Gli endpoint REST di Firebase supportano il protocollo EventSource/Server-Sent Events , semplificando lo streaming delle modifiche in un'unica posizione nel nostro database Firebase.

Per iniziare con lo streaming, dovremo fare quanto segue:

  1. Imposta l'intestazione Accept del client su text/event-stream
  2. Rispetta i reindirizzamenti HTTP, in particolare il codice di stato HTTP 307
  3. Includere il parametro di query auth se il percorso del database Firebase richiede l'autorizzazione per la lettura

In cambio, il server invierà eventi con nome quando lo stato dei dati all'URL richiesto cambia. La struttura di questi messaggi è conforme al protocollo EventSource:

event: event name
data: JSON encoded data payload

Il server può inviare i seguenti eventi:

mettere I dati con codifica JSON saranno un oggetto con due chiavi: percorso e dati
Il percorso punta a una posizione relativa all'URL della richiesta
Il client dovrebbe sostituire tutti i dati in quella posizione nella sua cache con i dati forniti nel messaggio
toppa I dati con codifica JSON saranno un oggetto con due chiavi: percorso e dati
Il percorso punta a una posizione relativa all'URL della richiesta
Per ogni chiave nei dati, il client deve sostituire la chiave corrispondente nella sua cache con i dati per quella chiave nel messaggio
mantieniti in vita I dati per questo evento sono nulli, non è richiesta alcuna azione
Annulla I dati per questo evento sono nulli
Questo evento verrà inviato se le regole del database in tempo reale di Firebase impediscono la lettura nella posizione richiesta
auth_revocato I dati per questo evento sono una stringa che indica che la credenziale è scaduta
Questo evento verrà inviato quando il parametro auth fornito non è più valido

Di seguito è riportato un esempio di un insieme di eventi che il server può inviare:

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}


// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}


// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

Se stai usando Go, dai un'occhiata a Firego , un wrapper di terze parti attorno alle API REST e Streaming di Firebase.