API REST del database Firebase

Utilizzo dell'API

Puoi utilizzare qualsiasi URL del database Firebase Realtime Database come endpoint REST. Tutto quello che devi fare è aggiungere .json alla fine dell'URL e inviare una richiesta dal tuo client HTTPS preferito.

È richiesto HTTPS. Firebase risponde solo al traffico crittografato in modo che i tuoi dati rimangano al sicuro.

GET - Lettura dei dati

I dati del tuo Realtime Database possono essere letti inviando una richiesta HTTP GET a un endpoint. L'esempio seguente dimostra come recuperare il nome di un utente precedentemente archiviato in Realtime Database.

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Una richiesta riuscita è indicata da un codice di stato HTTP 200 OK . La risposta contiene i dati associati al percorso nella richiesta GET .

{ "first": "Jack", "last": "Sparrow" }

PUT - Scrittura dei dati

È possibile scrivere dati con una richiesta PUT .

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Una richiesta riuscita è indicata da un codice di stato HTTP 200 OK . La risposta contiene i dati specificati nella richiesta PUT .

{ "first": "Jack", "last": "Sparrow" }

POST - Invio dei dati

Per ottenere l'equivalente del metodo JavaScript push() (vedi Elenchi di dati ), puoi inviare una richiesta POST .

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

Una richiesta riuscita è indicata da un codice di stato HTTP 200 OK . La risposta contiene il nome figlio dei nuovi dati specificati nella richiesta POST .

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH - Aggiornamento dei dati

Puoi aggiornare elementi secondari specifici in una posizione senza sovrascrivere i dati esistenti utilizzando una richiesta PATCH . I figli con nome nei dati scritti con PATCH vengono sovrascritti, ma i figli omessi non vengono eliminati. Ciò è equivalente alla funzione JavaScript update() .

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

Una richiesta riuscita è indicata da un codice di stato HTTP 200 OK . La risposta contiene i dati specificati nella richiesta PATCH .

{ "last": "Jones" }

DELETE: rimozione dei dati

Puoi eliminare i dati con una richiesta DELETE :

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Una richiesta DELETE riuscita è indicata da un codice di stato HTTP 200 OK con una risposta contenente JSON null .

Sostituzione del metodo

Se effettui chiamate REST da un browser che non supporta i metodi precedenti, puoi sovrascrivere il metodo di richiesta effettuando una richiesta POST e impostando il metodo utilizzando l'intestazione della richiesta X-HTTP-Method-Override .

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Puoi anche utilizzare il parametro di query x-http-method-override .

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

Richieste Condizionate

Le richieste condizionali, l'equivalente REST delle operazioni di transazione dell'SDK, aggiornano i dati in base a una determinata condizione. Visualizza una panoramica del flusso di lavoro e scopri di più sulle richieste condizionali per REST in Salvataggio dei dati .

ETag di Firebase

L'ETag Firebase è l'identificatore univoco per i dati correnti in una posizione specificata. Se i dati cambiano in quella posizione, cambia anche l'ETag. L'ETag Firebase deve essere specificato nell'intestazione della richiesta REST iniziale (in genere un GET , ma può essere qualsiasi cosa diversa da PATCH ).

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

se-corrispondenza

La condizione if-match specifica il valore ETag per i dati che desideri aggiornare. Se utilizzi la condizione, Realtime Database completa solo le richieste in cui l'ETag specificato nella richiesta di scrittura corrisponde all'ETag dei dati esistenti nel database. Recupera l'ETag in una posizione con una richiesta ETag Firebase. Se desideri sovrascrivere qualsiasi posizione nulla, utilizza null_etag .

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

Risposte attese

La tabella seguente fornisce una panoramica delle risposte previste per ciascun tipo di richiesta, in base alla corrispondenza ETag.

Tipo di richiesta 'X-Firebase-ETag: vero' Corrispondenze ETag
if_match: <matching etag>		 L'ETag non corrisponde
if_match: <no matching etag>
OTTENERE Stato/contenuto della risposta 200: "<data_at_path>" 400: "...non supportato.." 400: "...non supportato.."
Intestazioni aggiunte ETag: <ETag_di_dati> N / A N / A
METTERE Stato/contenuto della risposta 200: "<inserisci_dati>" 200: "<inserisci_dati>" 412: "...ETag non corrispondente.."
Intestazioni aggiunte ETag: <ETag_of_put_data> N / A ETag: <database_ETag>
INVIARE Stato/contenuto della risposta 200: "<dati_articolo>" 400: "...non supportato.." 400: "...non supportato.."
Intestazioni aggiunte ETag: <ETag_of_post_data> N / A N / A
TOPPA Stato/contenuto della risposta 400: "...non supportato.." 400: "...non supportato.." 400: "...non supportato.."
Intestazioni aggiunte N / A N / A N / A
ELIMINARE Stato/contenuto della risposta 200: nullo 200: "<dati_dopo_immissione>" 412: "...ETag non corrispondente.."
Intestazioni aggiunte ETag: <ETag_of_null> N / A ETag: <database_ETag>

Parametri della query

L'API REST del database Firebase accetta i seguenti parametri e valori di query:

token di accesso

Supportato da tutti i tipi di richiesta. Autentica questa richiesta per consentire l'accesso ai dati protetti dalle regole di sicurezza del database Firebase Realtime. Consulta la documentazione sull'autenticazione REST per i dettagli.

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

poco profondo

Si tratta di una funzionalità avanzata, progettata per aiutarti a lavorare con set di dati di grandi dimensioni senza dover scaricare tutto. Impostalo su true per limitare la profondità dei dati restituiti in una posizione. 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 .

argomenti Metodi REST Descrizione
poco profondo OTTENERE Limita la profondità della risposta.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Tieni presente che shallow non può essere combinato con altri parametri di query.

stampa

Formatta i dati restituiti nella risposta dal server.

argomenti Metodi REST Descrizione
bello OTTIENI, INSERisci, PUBBLICA, PATCH, ELIMINA Visualizza i dati in un formato leggibile dall'uomo.
silenzioso OTTIENI, metti, pubblica, patch Utilizzato per sopprimere l'output dal server durante la scrittura dei dati. La risposta risultante sarà vuota e indicata da un codice di stato HTTP 204 No Content .
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

richiamare

Supportato solo da GET . 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 specificata.

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

formato

Se impostato su export , il server codificherà le priorità nella risposta.

argomenti Metodi REST Descrizione
esportare OTTENERE Includere informazioni prioritarie nella risposta.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

scaricamento

Supportato solo da GET . Se desideri attivare il download di un file dei tuoi dati da un browser web, aggiungi download= . Ciò fa sì che il servizio REST aggiunga le intestazioni appropriate in modo che i browser sappiano che è necessario salvare i dati in un file.

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

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.

writeSizeLimit

Per limitare la dimensione di una scrittura, è possibile specificare il parametro di query writeSizeLimit come tiny (target=1s), small (target=10s), medium (target=30s), large (target=60s). Realtime Database stima la dimensione di ciascuna richiesta di scrittura e interrompe le richieste che richiederanno più tempo rispetto al tempo previsto.

Se specifichi unlimited , sono consentite scritture eccezionalmente grandi (con un carico utile fino a 256 MB), bloccando potenzialmente le richieste successive mentre il database elabora l'operazione corrente. Le scritture non possono essere annullate una volta raggiunto il server.

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

Verrà visualizzato il seguente messaggio di errore se la scrittura è troppo grande:

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

Inoltre, puoi impostare il defaultWriteSizeLimit per l'intera istanza del database utilizzando la CLI di Firebase. Questo limite si applica a tutte le richieste, comprese quelle provenienti dagli SDK. I nuovi database vengono creati con defaultWriteSizeLimit impostato su large . Non puoi impostare defaultWriteSizeLimit su tiny utilizzando la CLI di Firebase.

firebase database:settings:set defaultWriteSizeLimit large

ordinato da

Consulta la sezione della guida sui dati ordinati per maggiori informazioni.

limite al primo, limite all'ultimo, inizio, fine, uguale a

Per ulteriori informazioni consultare la sezione della guida sul filtraggio dei dati .

Streaming dall'API REST

Gli endpoint REST Firebase supportano il protocollo EventSource/Eventi inviati dal server . Per trasmettere le modifiche a una singola posizione nel tuo Realtime Database, devi eseguire alcune operazioni:

  • Imposta l'intestazione Accetta del client su "text/event-stream"
  • Rispettare i reindirizzamenti HTTP, in particolare il codice di stato HTTP 307
  • Se la posizione richiede l'autorizzazione per la lettura, è necessario includere il parametro auth

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 sono un oggetto con due chiavi: path e data . La chiave del percorso punta a una posizione relativa all'URL della richiesta. Il client dovrebbe sostituire tutti i dati in quella posizione nella sua cache con data .

toppa

I dati con codifica JSON sono un oggetto con due chiavi: path e data . La chiave del percorso punta a una posizione relativa all'URL della richiesta. Per ogni chiave in data , 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 null . Non è richiesta alcuna azione.

Annulla

Alcuni errori imprevisti possono inviare un evento "cancel" e interrompere la connessione. La causa è descritta nei dati forniti per questo evento. Alcune potenziali cause sono le seguenti: 1. Le regole di sicurezza del database Firebase Realtime non consentono più una lettura nella posizione richiesta. La descrizione dei dati per questa causa è "Autorizzazione negata". 2. Una scrittura ha attivato uno streamer di eventi che ha inviato un albero JSON di grandi dimensioni che supera il nostro limite, 512 MB. I "dati" per questa causa sono "Il carico utile specificato è troppo grande, richiedi una posizione con meno dati".

autenticazione_revocata

I dati per questo evento sono una stringa che indica che la credenziale è scaduta. Questo evento viene inviato quando il parametro auth fornito non è più valido.

Ecco un esempio di 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}}

Priorità

È possibile fare riferimento alle informazioni sulla priorità per una posizione con un "figlio virtuale" denominato .priority . Puoi leggere le priorità con le richieste GET e scriverle con le richieste PUT . Ad esempio, la seguente richiesta recupera la priorità del nodo users/tom :

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

Per scrivere priorità e dati contemporaneamente, puoi aggiungere un figlio .priority al payload JSON:

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

Per scrivere priorità e un valore primitivo (ad esempio una stringa) allo stesso tempo, puoi aggiungere un figlio .priority e inserire il valore primitivo in un figlio .value :

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

Questo scrive "Tom" con una priorità di 1.0 . Le priorità possono essere incluse a qualsiasi profondità nel payload JSON.

Valori del server

È possibile scrivere valori del server in una posizione utilizzando un valore segnaposto che è un oggetto con una singola chiave .sv . Il valore per quella chiave è il tipo di valore del server che desideri impostare. Ad esempio, la richiesta seguente imposta il valore del nodo sul timestamp corrente del server Firebase:

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

Puoi anche scrivere le priorità utilizzando i valori del server, utilizzando il percorso "figlio virtuale" indicato sopra.

I valori del server supportati includono:

Valore del server
timestamp Il tempo trascorso dall'epoca di UNIX, in millisecondi.
incremento Fornire un valore delta intero o in virgola mobile, nel formato { ".sv": {"increment": <delta_value> }} , con cui incrementare atomicamente il valore del database corrente. Se i dati non esistono ancora, l'aggiornamento imposterà i dati sul valore delta. Se il valore delta o i dati esistenti sono numeri a virgola mobile, entrambi i valori verranno interpretati come numeri a virgola mobile e applicati sul back-end come un valore doppio. L'aritmetica doppia e la rappresentazione dei valori doppi seguono la semantica IEEE 754. Se si verifica un overflow di numeri interi positivi/negativi, la somma viene calcolata come doppia.

Recupero e aggiornamento delle regole di sicurezza del database Firebase Realtime

L'API REST può essere utilizzata anche per recuperare e aggiornare le regole di sicurezza del database Firebase Realtime per il tuo progetto Firebase. Avrai bisogno del segreto del tuo progetto Firebase, che puoi trovare nel pannello Account di servizio delle impostazioni del tuo progetto Firebase.

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

Autenticare le richieste

Per impostazione predefinita, le richieste REST vengono eseguite senza autenticazione e avranno esito positivo solo se le regole del database in tempo reale consentono l'accesso pubblico in lettura o scrittura ai dati. Per autenticare la tua richiesta, utilizza i parametri di query access_token= o auth= .

Scopri di più sull'autenticazione tramite l'API REST in Autenticare le richieste REST .

Condizioni di errore

L'API REST del database Firebase può restituire i seguenti codici di errore.

Codici di stato HTTP
400 Richiesta errata

Una delle seguenti condizioni di errore:

  • Impossibile analizzare i dati PUT o POST .
  • Dati PUT o POST mancanti.
  • La richiesta tenta di PUT o POST dati troppo grandi.
  • La chiamata API REST contiene nomi figlio non validi come parte del percorso.
  • Il percorso della chiamata API REST è troppo lungo.
  • La richiesta contiene un valore del server non riconosciuto.
  • L'indice per la query non è definito nelle regole di sicurezza del database Firebase Realtime .
  • La richiesta non supporta uno dei parametri di query specificati.
  • La richiesta combina i parametri di query con una richiesta GET superficiale.
401 Non autorizzato

Una delle seguenti condizioni di errore:

404 non trovato Il Realtime Database specificato non è stato trovato.
500 Errore interno del server Il server ha restituito un errore. Per ulteriori dettagli vedere il messaggio di errore.
503 servizio non disponibile Il Firebase Realtime Database specificato è temporaneamente non disponibile, il che significa che la richiesta non è stata tentata.
412 Precondizione non riuscita Il valore ETag specificato della richiesta nell'intestazione if-match non corrispondeva al valore del server.