Recupero dei dati in corso...

Lettura dei dati con GET

Possiamo leggere i dati dal nostro database Firebase inviando una GET richiesta all'endpoint URL. Continuiamo con l'esempio del blog della sezione precedente e leggiamo tutti i dati dei post del 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 di uso comune. Per un elenco completo, consulta il riferimento dell'API REST.

auth

Il parametro di richiesta auth consente l'accesso ai dati protetti da Firebase Realtime Database Security Rules 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'

print

Se specifichi print=pretty, i dati vengono restituiti in un formato leggibile.

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

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

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 racchiuda i dati restituiti nella funzione di callback che hai specificato. Ad esempio:

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

shallow

Si tratta di una funzionalità avanzata, progettata per aiutarti a lavorare con set di dati di grandi dimensioni senza dover scaricare tutto. Per utilizzarla, aggiungi shallow=true come parametro. In questo modo, la profondità dei dati restituiti sarà limitata. Se i dati nella località sono una primitiva JSON (stringa, numero, o valore booleano), il relativo valore verrà semplicemente restituito. Se lo snapshot dei dati nella località è 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

Utilizza questo parametro per limitare il tempo di lettura sul lato server. Se una richiesta di lettura non viene completata entro il tempo assegnato, viene terminata con un errore HTTP 400. Questo è particolarmente utile quando prevedi un piccolo trasferimento di dati e non vuoi aspettare troppo a lungo 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à. Se non viene specificato, verrà applicato il timeout massimo di 15min. Se il timeout non è positivo o supera il valore 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 creare query per filtrare i dati in base a vari fattori. Per iniziare, specifica come vuoi filtrare i dati utilizzando il orderBy parametro. Poi, combina orderBy con uno degli altri cinque parametri: limitToFirst, limitToLast, startAt, endAt, e equalTo.

Poiché tutti noi di Firebase pensiamo che i dinosauri siano piuttosto interessanti, utilizzeremo uno snippet di un database di esempio di fatti sui dinosauri per mostrare 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.

Filtraggio in base a una chiave secondaria specificata

Possiamo filtrare i nodi in base a una chiave secondaria comune passando la chiave al orderBy parametro. 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 ha la chiave secondaria su cui stiamo filtrando verrà ordinato con un valore di null. Per informazioni dettagliate su come vengono ordinati i dati, consulta Come vengono ordinati i dati.

Firebase supporta anche le query ordinate in base a elementi secondari nidificati in profondità, anziché solo a elementi secondari di un livello inferiore. Questo è utile se hai dati nidificati in profondità come questi:

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

Per eseguire una query sull'altezza, 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.

Filtraggio 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'

Filtraggio per valore

Possiamo filtrare i nodi in base al valore delle relative chiavi secondarie utilizzando il orderBy="$value" parametro. Supponiamo che i dinosauri stiano partecipando a una competizione sportiva e che 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, possiamo 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 null, booleani, stringa e oggetto vengono ordinati quando utilizzi orderBy="$value".

Filtraggio complesso

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

Query di limite

I parametri limitToFirst e limitToLast vengono utilizzati per impostare un numero massimo di elementi secondari per i quali ricevere i dati. Se impostiamo un limite di 100, riceveremo solo fino a 100 elementi secondari corrispondenti. Se nel database sono memorizzati meno di 100 messaggi, riceveremo tutti gli elementi secondari. Tuttavia, se abbiamo più di 100 messaggi, riceveremo i dati solo per 100 di questi messaggi. Questi saranno i primi 100 messaggi ordinati se utilizziamo limitToFirst o gli ultimi 100 messaggi ordinati se utilizziamo limitToLast.

Utilizzando 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 utilizzando limitToFirst:

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

Possiamo anche eseguire query di limite con orderBy="$value". Se vogliamo creare una classifica con i primi tre concorrenti sportivi di dinosauri 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 di intervallo

L'utilizzo di 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 utilizzare endAt per trovare tutti i dinosauri i cui nomi precedono Pterodactyl in ordine lessicografico:

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. 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 devi impaginare i dati.

Elaborazione della risposta…

Possiamo combinare tutte queste tecniche per creare query complesse. Ad esempio, potresti voler trovare il nome di tutti i dinosauri di altezza inferiore o uguale al nostro tipo 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 vengono ordinati nel seguente modo:

1. Gli elementi secondari con un valore null per la chiave secondaria specificata vengono visualizzati per primi.
2. Gli elementi secondari con un valore false per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore false, vengono ordinati lessicograficamente per chiave.
3. Gli elementi secondari con un valore true per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore true, vengono ordinati lessicograficamente per chiave.
4. Gli elementi secondari con un valore numerico vengono visualizzati successivamente, 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 vengono ordinate lessicograficamente in ordine crescente. Se più elementi 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.

orderBy="$key"

Quando utilizzi il parametro orderBy="$key" per ordinare i dati, i dati vengono 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 un intero a 32 bit vengono visualizzati per primi, ordinati in ordine crescente.
2. Gli elementi secondari con un valore stringa come chiave vengono visualizzati successivamente, ordinati lessicograficamente in ordine crescente ordine.

orderBy="$value"

Quando utilizzi il parametro orderBy="$value" per ordinare i dati, gli elementi secondari vengono ordinati in base al relativo 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'ordinamento degli elementi secondari è determinato dalla relativa priorità e chiave come segue. Tieni presente che i valori di priorità possono essere solo numeri o stringhe.

1. Gli elementi secondari senza priorità (valore predefinito) vengono visualizzati per primi.
2. Gli elementi secondari con un numero come priorità vengono visualizzati successivamente. Vengono ordinati numericamente per priorità, dal più piccolo al più grande.
3. Gli elementi secondari con una stringa come priorità vengono visualizzati per ultimi. Vengono ordinati lessicograficamente per priorità.
4. Ogni volta che due elementi secondari hanno la stessa priorità (inclusa nessuna priorità), vengono ordinati per chiave. Le chiavi numeriche vengono visualizzate per prime (ordinate numericamente), seguite dalle chiavi rimanenti (ordinate lessicograficamente).

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

Streaming dall'API REST

Gli endpoint REST di Firebase supportano il protocollo EventSource / Server-Sent Events, semplificando lo streaming delle modifiche a una singola località nel nostro database Firebase.

Per iniziare a utilizzare lo streaming, dobbiamo:

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

In cambio, il server invierà eventi denominati man mano che 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:

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 utilizzi Go, consulta Firego, un wrapper di terze parti per le API REST e di streaming di Firebase.