Recupero dei dati in corso...

Lettura dei dati con GET

Possiamo leggere i dati dal nostro database Firebase inviando una richiesta GET al relativo endpoint URL. Continuiamo con l'esempio del blog della sezione precedente e leggiamo tutti i dati del post del blog:

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

Una richiesta andata a buon fine 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ù utilizzati. Per un elenco completo, consulta il riferimento all'API REST.

auth

Il parametro di richiesta auth consente di accedere ai dati protetti da Firebase Realtime Database Security Rules ed è supportato da tutti i tipi di richiesta. L'argomento può essere il segreto della tua app Firebase o un token di autenticazione, come descritto nella sezione Utenti nei progetti Firebase. Nell'esempio seguente inviamo una richiesta GET con un parametro auth, dove CREDENTIAL è il secret della tua app Firebase o un token di autenticazione:

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

stampa

La specifica di print=pretty restituisce i dati in un formato leggibile.

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

Se specifichi print=silent, in caso di esito positivo viene restituito un 204 No Content.

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

callback

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 inserisca i dati restituiti nella funzione di callback specificata. Ad esempio:

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

poco profondo

Si tratta di una funzionalità avanzata, progettata per aiutarti a lavorare con set di dati di grandi dimensioni senza dover scaricare tutto. Per utilizzarlo, aggiungi shallow=true come parametro. In questo modo, verrà limitata la profondità dei dati restituiti. Se i dati nella posizione sono un valore JSON primitivo (stringa, numero o booleano), verrà restituito semplicemente il relativo valore. Se lo snapshot dei dati nella posizione è un oggetto JSON, i valori di ogni chiave verranno troncati a true. Ad esempio, utilizzando i dati riportati di seguito:

{
  "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!"

Prova con questa richiesta curl:

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

timeout

Utilizzalo per limitare il tempo necessario per la lettura lato server. Se una richiesta di lettura non viene completata entro il tempo a disposizione, termina con un errore HTTP 400. Questo è particolarmente utile quando prevedi un trasferimento di dati ridotto e non vuoi attendere troppo per recuperare un sottoalbero potenzialmente enorme. Il tempo di lettura effettivo può variare in base alle dimensioni dei dati e alla memorizzazione nella cache.

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

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

Filtrare i dati

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

Dato che tutti noi di Firebase pensiamo che i dinosauri siano fantastici, utilizzeremo uno snippet di un database di esempio di curiosità 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 tre modi: per chiave secondaria, per chiave o per valore. Una query inizia con uno di questi parametri e deve essere combinata con uno o più dei seguenti parametri: startAt, endAt, limitToFirst, limitToLast o equalTo.

Filtro in base a una chiave secondaria specificata

Possiamo filtrare i nodi in base a una chiave secondaria comune passandola al parametro orderBy. Ad esempio, per recuperare tutti i dinosauri con un'altezza superiore a 3, possiamo procedere nel seguente modo:

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

Qualsiasi nodo che non abbia la chiave secondaria in base alla quale viene applicato il filtro verrà ordinato con un valore di null. Per informazioni dettagliate sull'ordinamento dei dati, consulta Come vengono ordinati i dati.

Firebase supporta anche le query ordinate per elementi secondari nidificati in modo approfondito, anziché solo per elementi secondari a un livello inferiore. Questo è utile se hai dati nidificati in modo complesso come questo:

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

Per eseguire una query sull'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 in base a una chiave alla volta. L'utilizzo del parametro orderBy più volte nella stessa richiesta genera un errore.

Filtro per chiave

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

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

Filtri per valore

Possiamo filtrare i nodi in base al valore delle relative chiavi secondarie utilizzando il parametro orderBy="$value". Supponiamo che i dinosauri stiano partecipando a una competizione sportiva e stiamo monitorando i 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 effettuare la seguente richiesta:

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

Consulta Come vengono ordinati i dati per una spiegazione su come vengono ordinati i valori null, booleani, di stringa e di oggetti quando utilizzi orderBy="$value".

Filtri complessi

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

Limita query

I parametri limitToFirst e limitToLast vengono utilizzati per impostare un numero massimo di bambini 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 tutti i bambini. Tuttavia, se abbiamo più di 100 messaggi, riceveremo i dati solo per 100 di questi messaggi. Si tratta dei primi 100 messaggi ordinati se utilizziamo limitToFirst o degli ultimi 100 messaggi ordinati se utilizziamo limitToLast.

Utilizzando il nostro database di informazioni 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ù brevi utilizzando limitToFirst:

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

Possiamo anche eseguire query con limiti con orderBy="$value". Se vogliamo creare una classifica con i tre concorrenti di Dino Sports con il punteggio più alto, possiamo procedere nel seguente modo:

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

Query sull'intervallo

L'utilizzo di startAt, endAt e equalTo ci consente di scegliere punti di inizio e di 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 utilizzare endAt per trovare tutti i dinosauri i cui nomi precedono Pterodattilo alfabeticamente:

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 query. Il seguente esempio 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 sull'intervallo sono utili anche quando devi paginare i dati.

In sintesi

Possiamo combinare tutte queste tecniche per creare query complesse. Ad esempio, potresti voler trovare il nome di tutti i dinosauri più corti o uguali in altezza al nostro preferito, lo Stegosaurus:

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 utilizzi ciascuno dei tre parametri di filtro.

orderBy

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

1. I figli con un valore null per la chiave secondaria specificata vengono visualizzati per primi.
2. Seguono gli elementi secondari con un valore di false per la chiave secondaria specificata. Se più elementi secondari hanno un valore false, vengono ordinati in ordine alfabetico in base alla chiave.
3. Seguono gli elementi secondari con un valore di true per la chiave secondaria specificata. Se più elementi secondari hanno un valore true, vengono ordinati in ordine alfabetico per chiave.
4. Seguono gli elementi secondari con un valore numerico, ordinati in ordine crescente. Se più elementi figli hanno lo stesso valore numerico per il nodo figlio specificato, vengono ordinati in base alla chiave.
5. Le stringhe vengono visualizzate dopo i numeri e sono ordinate in ordine crescente in base al codice. Se più elementi figli hanno lo stesso valore per il nodo figlio specificato, vengono ordinati in ordine alfabetico per chiave.
6. Gli oggetti vengono visualizzati per ultimi e ordinati in ordine lessicografico per chiave in ordine crescente.

orderBy="$key"

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

1. Gli elementi secondari con una chiave che può essere analizzata come numero intero a 32 bit vengono visualizzati per primi, in ordine crescente.
2. Seguono gli elementi secondari con un valore di stringa come chiave, ordinati in ordine lessicografico crescente.

orderBy="$value"

Quando utilizzi il parametro orderBy="$value" per ordinare i dati, gli elementi secondari verranno ordinati in base al loro valore. I criteri di ordinamento sono gli stessi dei dati ordinati in base a una chiave secondaria, tranne per il fatto che viene utilizzato il valore del nodo anziché il valore di una chiave secondaria specificata.

orderBy="$priority"

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

1. I bambini senza priorità (valore predefinito) vengono visualizzati per primi.
2. Seguono i bambini con una priorità numerica. Sono ordinate numericamente in base alla priorità, da piccola a grande.
3. I bambini con una stringa come priorità vengono visualizzati per ultimi. Sono ordinate in ordine lessicografico in base alla priorità.
4. Quando due elementi secondari hanno la stessa priorità (inclusa nessuna priorità), vengono ordinati in base alla chiave. Le chiavi numeriche vengono visualizzate per prime (ordinate in ordine numerico), seguite dalle chiavi rimanenti (ordinate alfabeticamente).

Per ulteriori informazioni sulle priorità, consulta il riferimento all'API.

Streaming dall'API REST

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

Per iniziare a trasmettere in streaming, dobbiamo:

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. Includi il parametro di query auth se la posizione del database Firebase richiede l'autorizzazione di lettura

In cambio, il server invierà eventi denominati man mano che cambia lo stato dei dati nell'URL richiesto. La struttura di questi messaggi è conforme al protocollo EventSource:

event: event name
data: JSON encoded data payload

Il server potrebbe inviare i seguenti eventi:

Di seguito è riportato un esempio di un insieme di eventi che il server potrebbe 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 utilizzi Go, dai un'occhiata a Firego, un wrapper di terze parti per le API Firebase REST e Streaming.