Lettura dei dati con GET
Possiamo leggere i dati dal nostro database Firebase emettendo una richiesta GET
al suo endpoint URL. Continuiamo con l'esempio del blog della sezione precedente e leggiamo tutti i dati dei post del nostro blog:
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
Una richiesta riuscita verrà 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 al riferimento API REST .
aut
Il parametro di richiesta auth
consente l'accesso ai dati protetti dalle regole di sicurezza del database Firebase Realtime 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
restituisce i dati in un formato leggibile dall'uomo.
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
Specificando print=silent
restituisce un 204 No Content
in caso di successo.
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'
richiamare
Per effettuare chiamate REST da un browser Web tra domini è possibile 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 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
Si tratta di 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), verrà semplicemente restituito il relativo valore. Se lo snapshot dei dati nella posizione è un oggetto JSON, i valori per ogni chiave verranno troncati a 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 curl
:
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'
tempo scaduto
Utilizzalo per limitare il tempo impiegato dalla 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 si prevede un piccolo trasferimento di dati e non si vuole aspettare troppo a lungo per recuperare un sottoalbero potenzialmente enorme. Il tempo di lettura effettivo potrebbe variare in base alle dimensioni dei dati e alla memorizzazione nella cache.
Specificare 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 desideri che i tuoi dati vengano filtrati utilizzando il parametro orderBy
. Quindi, combini orderBy
con uno qualsiasi 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 da un database di esempio di fatti sui dinosauri per dimostrare come 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 figlio , per chiave o per valore . Una query inizia con uno di questi parametri e 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 tale chiave al parametro orderBy
. Ad esempio, per recuperare tutti i dinosauri con 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 dettagli su come vengono ordinati i dati, vedere Come vengono ordinati i dati .
Firebase supporta anche le query ordinate in base a elementi secondari profondamente annidati, anziché solo a quelli di un livello inferiore. Questo è utile se disponi di dati profondamente annidati come questi:
{ "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 in base a una chiave alla volta. L'utilizzo più volte del parametro orderBy
sulla stessa richiesta genera un errore.
Filtraggio per chiave
Possiamo anche filtrare i nodi in base alle loro chiavi utilizzando il parametro 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 utilizzando il parametro orderBy="$value"
. Supponiamo che i dinosauri stiano partecipando a una competizione sportiva sui dinosauri e teniamo 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
, booleani, stringa 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 archiviati nel nostro database, riceveremo tutti i bambini. Tuttavia, se abbiamo più di 100 messaggi, riceveremo i dati solo per 100 di essi. Questi saranno i primi 100 messaggi ordinati se utilizziamo limitToFirst
o gli ultimi 100 messaggi ordinati se utilizziamo limitToLast
.
Utilizzando il nostro database dei 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ù bassi utilizzando 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 di sport con dinosauri 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'utilizzo startAt
, endAt
e equalTo
ci consente di scegliere punti iniziali e finali 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 precedono lessicograficamente Pterodactyl:
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 su intervalli sono utili anche quando è necessario impaginare i dati.
Mettere tutto insieme
Possiamo combinare tutte queste tecniche per creare query complesse. Ad esempio, potresti voler trovare il nome di tutti i dinosauri che sono più bassi o uguali in altezza 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 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:
- I bambini con un valore
null
per la chiave figlio specificata vengono prima. - I figli con un valore
false
per la chiave figlio specificata vengono dopo. Se più figli hanno un valorefalse
, vengono ordinati lessicograficamente per chiave. - I figli con un valore
true
per la chiave figlio specificata vengono dopo. Se più figli hanno un valoretrue
, vengono ordinati lessicograficamente per chiave. - Seguono i bambini con un valore numerico, ordinati in ordine crescente. Se più figli hanno lo stesso valore numerico per il nodo figlio specificato, vengono ordinati per chiave.
- 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.
- Gli oggetti vengono per ultimi e ordinati lessicograficamente per chiave in ordine crescente.
orderBy="$chiave"
Quando utilizzi il parametro 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.
- I figli con una chiave che può essere analizzata come intero a 32 bit vengono prima, ordinati in ordine crescente.
- Seguono i bambini con un valore stringa come chiave, ordinati lessicograficamente in ordine crescente.
orderBy="$valore"
Quando utilizzi il parametro 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 in base a una chiave figlio, tranne per il fatto che viene utilizzato il valore del nodo anziché il valore di una chiave figlio specificata.
orderBy="$priorità"
Quando utilizzi il parametro orderBy="$priority"
per ordinare i tuoi dati, l'ordine dei figli è determinato dalla loro priorità e chiave come segue. Tieni presente che i valori di priorità possono essere solo numeri o stringhe.
- I bambini senza priorità (impostazione predefinita) vengono prima.
- I bambini con un numero come priorità vengono dopo. Sono ordinati numericamente in base alla priorità, da piccola a grande.
- I bambini con una corda come priorità arrivano per ultimi. Sono ordinati lessicograficamente per priorità.
- Ogni volta che due figli hanno la stessa priorità (inclusa nessuna priorità), vengono ordinati per chiave. I tasti numerici vengono per primi (ordinati numericamente), seguiti dai restanti tasti (ordinati lessicograficamente).
Per ulteriori informazioni sulle priorità, consulta il riferimento API .
Streaming dall'API REST
Gli endpoint REST 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 effettuare le seguenti operazioni:
- Imposta l'intestazione Accept del client su
text/event-stream
- Rispettare i reindirizzamenti HTTP, in particolare il codice di stato HTTP 307
- Includi il parametro di query
auth
se il percorso del database Firebase richiede l'autorizzazione per la lettura
In cambio, il server invierà eventi denominati man mano che lo stato dei dati nell'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 |
mantenersi 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 di sicurezza del database Firebase Realtime impediscono più di consentire una lettura nella posizione richiesta |
autenticazione_revocata | 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 una serie 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, dai un'occhiata a Firego , un wrapper di terze parti per le API REST e Streaming di Firebase.