Firebase-Datenbank-REST-API

API-Nutzung

Sie können jede Firebase-Echtzeitdatenbank-URL als REST-Endpunkt verwenden. Sie müssen lediglich .json an das Ende der URL anhängen und eine Anfrage von Ihrem bevorzugten HTTPS-Client senden.

HTTPS ist erforderlich. Firebase reagiert nur auf verschlüsselten Datenverkehr, damit Ihre Daten sicher bleiben.

GET – Daten lesen

Daten aus Ihrer Echtzeitdatenbank können gelesen werden, indem Sie eine HTTP- GET Anfrage an einen Endpunkt senden. Das folgende Beispiel zeigt, wie Sie den Namen eines Benutzers abrufen können, den Sie zuvor in der Echtzeitdatenbank gespeichert haben.

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

Eine erfolgreiche Anfrage wird durch den HTTP-Statuscode 200 OK angezeigt. Die Antwort enthält die Daten, die dem Pfad in der GET Anfrage zugeordnet sind.

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

PUT – Daten schreiben

Sie können Daten mit einer PUT Anfrage schreiben.

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

Eine erfolgreiche Anfrage wird durch den HTTP-Statuscode 200 OK angezeigt. Die Antwort enthält die in der PUT Anfrage angegebenen Daten.

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

POST – Daten übertragen

Um das Äquivalent der JavaScript-Methode push() zu erreichen (siehe Datenlisten ), können Sie eine POST Anfrage ausgeben.

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

Eine erfolgreiche Anfrage wird durch den HTTP-Statuscode 200 OK angezeigt. Die Antwort enthält den untergeordneten Namen der neuen Daten, die in der POST Anfrage angegeben wurden.

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

PATCH – Daten aktualisieren

Mithilfe einer PATCH Anfrage können Sie bestimmte untergeordnete Elemente an einem Standort aktualisieren, ohne vorhandene Daten zu überschreiben. Benannte untergeordnete Elemente in den mit PATCH geschriebenen Daten werden überschrieben, ausgelassene untergeordnete Elemente werden jedoch nicht gelöscht. Dies entspricht der JavaScript-Funktion update() .

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

Eine erfolgreiche Anfrage wird durch den HTTP-Statuscode 200 OK angezeigt. Die Antwort enthält die in der PATCH Anfrage angegebenen Daten.

{ "last": "Jones" }

DELETE – Daten entfernen

Sie können Daten mit einer DELETE Anfrage löschen:

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

Eine erfolgreiche DELETE Anfrage wird durch den HTTP-Statuscode 200 OK mit einer Antwort angezeigt, die JSON null enthält.

Methodenüberschreibung

Wenn Sie REST-Aufrufe von einem Browser aus durchführen, der die oben genannten Methoden nicht unterstützt, können Sie die Anforderungsmethode überschreiben, indem Sie eine POST Anfrage stellen und Ihre Methode mithilfe des Anforderungsheaders X-HTTP-Method-Override festlegen.

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

Sie können auch den Abfrageparameter x-http-method-override verwenden.

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

Bedingte Anfragen

Bedingte Anforderungen, das REST-Äquivalent von SDK-Transaktionsvorgängen, aktualisieren Daten gemäß einer bestimmten Bedingung. Sehen Sie sich einen Überblick über den Workflow an und erfahren Sie mehr über bedingte Anforderungen für REST unter „Daten speichern“ .

Firebase ETag

Der Firebase ETag ist die eindeutige Kennung für die aktuellen Daten an einem bestimmten Ort. Wenn sich die Daten an diesem Ort ändern, ändert sich auch das ETag. Der Firebase-ETag muss im Header für die erste REST-Anfrage angegeben werden (normalerweise ein GET , kann aber auch ein anderer Wert als PATCH sein).

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

if-match

Die if-match Bedingung gibt den ETag-Wert für die Daten an, die Sie aktualisieren möchten. Wenn Sie die Bedingung verwenden, schließt Realtime Database nur Anfragen ab, bei denen das in der Schreibanforderung angegebene ETag mit dem ETag der vorhandenen Daten in der Datenbank übereinstimmt. Rufen Sie das ETag mit einer Firebase-ETag-Anfrage an einem Ort ab. Wenn Sie einen Standort überschreiben möchten, der null ist, verwenden Sie null_etag .

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

Erwartete Antworten

Die folgende Tabelle bietet einen Überblick über die erwarteten Antworten für jeden Anfragetyp, basierend auf der ETag-Übereinstimmung.

Anfragetyp 'X-Firebase-ETag: true' ETag-Übereinstimmungen
if_match: <matching etag>		 ETag stimmt nicht überein
if_match: <no matching etag>
ERHALTEN Antwortstatus/Inhalt 200: „<data_at_path>“ 400: „...nicht unterstützt..“ 400: „...nicht unterstützt..“
Überschriften hinzugefügt ETag: <ETag_of_data> N / A N / A
SETZEN Antwortstatus/Inhalt 200: „<put_data>“ 200: „<put_data>“ 412: „...ETag stimmt nicht überein.“
Überschriften hinzugefügt ETag: <ETag_of_put_data> N / A ETag: <database_ETag>
POST Antwortstatus/Inhalt 200: „<post_data>“ 400: „...nicht unterstützt..“ 400: „...nicht unterstützt..“
Überschriften hinzugefügt ETag: <ETag_of_post_data> N / A N / A
PATCH Antwortstatus/Inhalt 400: „...nicht unterstützt..“ 400: „...nicht unterstützt..“ 400: „...nicht unterstützt..“
Überschriften hinzugefügt N / A N / A N / A
LÖSCHEN Antwortstatus/Inhalt 200: null 200: „<data_after_put>“ 412: „...ETag stimmt nicht überein.“
Überschriften hinzugefügt ETag: <ETag_of_null> N / A ETag: <database_ETag>

Abfrageparameter

Die Firebase-Datenbank-REST-API akzeptiert die folgenden Abfrageparameter und -werte:

Zugangstoken

Unterstützt von allen Anfragetypen. Authentifiziert diese Anfrage, um den Zugriff auf Daten zu ermöglichen, die durch Firebase Realtime Database Security Rules geschützt sind. Weitere Informationen finden Sie in der Dokumentation zur REST-Authentifizierung .

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

seicht

Hierbei handelt es sich um eine erweiterte Funktion, die Ihnen bei der Arbeit mit großen Datensätzen helfen soll, ohne alles herunterladen zu müssen. Setzen Sie dies auf true , um die Tiefe der an einem Standort zurückgegebenen Daten zu begrenzen. Wenn es sich bei den Daten am Speicherort um ein JSON-Grundelement (Zeichenfolge, Zahl oder boolescher Wert) handelt, wird der Wert einfach zurückgegeben. Wenn der Daten-Snapshot am Standort ein JSON-Objekt ist, werden die Werte für jeden Schlüssel auf true gekürzt.

Argumente REST-Methoden Beschreibung
seicht ERHALTEN Begrenzen Sie die Tiefe der Antwort.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Beachten Sie, dass shallow nicht mit anderen Abfrageparametern gemischt werden kann.

drucken

Formatiert die in der Antwort vom Server zurückgegebenen Daten.

Argumente REST-Methoden Beschreibung
hübsch GET, PUT, POST, PATCH, DELETE Zeigen Sie die Daten in einem für Menschen lesbaren Format an.
still GET, PUT, POST, PATCH Wird verwendet, um die Ausgabe vom Server beim Schreiben von Daten zu unterdrücken. Die resultierende Antwort ist leer und wird durch den HTTP-Statuscode 204 No Content angezeigt.
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'

Ruf zurück

Wird nur von GET unterstützt. Um REST-Aufrufe von einem Webbrowser aus über Domänen hinweg durchzuführen, können Sie JSONP verwenden, um die Antwort in eine JavaScript-Rückruffunktion zu verpacken. Fügen Sie callback= hinzu, damit die REST-API die zurückgegebenen Daten in die von Ihnen angegebene Callback-Funktion einschließt.

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

Format

Wenn export eingestellt ist, kodiert der Server Prioritäten in der Antwort.

Argumente REST-Methoden Beschreibung
Export ERHALTEN Fügen Sie der Antwort wichtige Informationen hinzu.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

herunterladen

Wird nur von GET unterstützt. Wenn Sie einen Dateidownload Ihrer Daten über einen Webbrowser auslösen möchten, fügen Sie download= hinzu. Dadurch fügt der REST-Dienst die entsprechenden Header hinzu, damit Browser wissen, dass sie die Daten in einer Datei speichern müssen.

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

Auszeit

Verwenden Sie diese Option, um die Dauer des Lesevorgangs auf der Serverseite zu begrenzen. Wenn eine Leseanforderung nicht innerhalb der vorgegebenen Zeit abgeschlossen wird, wird sie mit einem HTTP-400-Fehler beendet. Dies ist besonders nützlich, wenn Sie eine kleine Datenübertragung erwarten und nicht zu lange warten möchten, um einen möglicherweise großen Teilbaum abzurufen. Die tatsächliche Lesezeit kann je nach Datengröße und Caching variieren.

Geben Sie timeouts im folgenden Format an: 3ms , 3s oder 3min , mit einer Zahl und einer Einheit. Wenn nicht angegeben, wird das maximale timeout von 15min angewendet. Wenn das timeout nicht positiv ist oder das Maximum überschreitet, wird die Anfrage mit einem HTTP-400-Fehler abgelehnt.

writeSizeLimit

Um die Größe eines Schreibvorgangs zu begrenzen, können Sie den Abfrageparameter writeSizeLimit als tiny (Ziel=1s), small (Ziel=10s), medium (Ziel=30s), large (Ziel=60s) angeben. Die Echtzeitdatenbank schätzt die Größe jeder Schreibanforderung und bricht Anforderungen ab, die länger als die Zielzeit dauern.

Wenn Sie unlimited angeben, sind außergewöhnlich große Schreibvorgänge (mit bis zu 256 MB Nutzlast) zulässig, die möglicherweise nachfolgende Anforderungen blockieren, während die Datenbank den aktuellen Vorgang verarbeitet. Schreibvorgänge können nicht abgebrochen werden, sobald sie den Server erreichen.

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

Wenn der Schreibvorgang zu groß ist, wird die folgende Fehlermeldung angezeigt:

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

Darüber hinaus können Sie mit der Firebase-CLI das defaultWriteSizeLimit für die gesamte Datenbankinstanz festlegen. Dieses Limit gilt für alle Anfragen, auch solche von SDKs. Neue Datenbanken werden mit der Einstellung defaultWriteSizeLimit auf large erstellt. Sie können defaultWriteSizeLimit mit der Firebase-CLI nicht auf tiny setzen.

firebase database:settings:set defaultWriteSizeLimit large

Sortieren nach

Weitere Informationen finden Sie im Abschnitt im Leitfaden zu geordneten Daten .

limitToFirst, limitToLast, startAt, endAt, equalTo

Weitere Informationen finden Sie im Abschnitt zum Filtern von Daten im Leitfaden.

Streaming von der REST-API

Firebase-REST-Endpunkte unterstützen das EventSource-/Server-Sent Events- Protokoll. Um Änderungen an einem einzelnen Ort in Ihrer Echtzeitdatenbank zu streamen, müssen Sie einige Dinge tun:

  • Setzen Sie den Accept-Header des Clients auf "text/event-stream"
  • Respektieren Sie HTTP-Weiterleitungen, insbesondere den HTTP-Statuscode 307
  • Wenn für den Standort eine Leseberechtigung erforderlich ist, müssen Sie den auth Parameter angeben

Im Gegenzug sendet der Server benannte Ereignisse, wenn sich der Status der Daten an der angeforderten URL ändert. Die Struktur dieser Nachrichten entspricht dem EventSource Protokoll.

event: event name
data: JSON encoded data payload

Der Server kann die folgenden Ereignisse senden:

setzen

Die JSON-codierten Daten sind ein Objekt mit zwei Schlüsseln: path und data . Der Pfadschlüssel zeigt auf einen Ort relativ zur Anforderungs-URL. Der Client sollte alle Daten an dieser Stelle in seinem Cache durch data ersetzen.

Patch

Die JSON-codierten Daten sind ein Objekt mit zwei Schlüsseln: path und data . Der Pfadschlüssel zeigt auf einen Ort relativ zur Anforderungs-URL. Für jeden Schlüssel in data sollte der Client den entsprechenden Schlüssel in seinem Cache durch die Daten für diesen Schlüssel in der Nachricht ersetzen.

bleib am Leben

Die Daten für dieses Ereignis sind null . Es sind keine Maßnahmen erforderlich.

stornieren

Einige unerwartete Fehler können ein „Abbruch“-Ereignis senden und die Verbindung beenden. Die Ursache ist in den für dieses Ereignis bereitgestellten Daten beschrieben. Einige mögliche Ursachen sind wie folgt: 1. Die Firebase-Echtzeitdatenbank-Sicherheitsregeln erlauben keinen Lesevorgang am angeforderten Speicherort mehr. Die „Daten“-Beschreibung für diesen Grund lautet „Berechtigung verweigert“. 2. Ein Schreibvorgang hat einen Event-Streamer ausgelöst, der einen großen JSON-Baum gesendet hat, der unser Limit von 512 MB überschreitet. Die „Daten“ für diesen Grund lauten „Die angegebene Nutzlast ist zu groß, bitte fordern Sie einen Standort mit weniger Daten an.“

auth_revoked

Die Daten für dieses Ereignis sind eine Zeichenfolge, die angibt, dass die Anmeldeinformationen abgelaufen sind. Dieses Ereignis wird gesendet, wenn der angegebene auth nicht mehr gültig ist.

Hier ist ein Beispielsatz von Ereignissen, die der Server senden kann:

// 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äten

Prioritätsinformationen für einen Standort können mit einem „virtuellen untergeordneten Element“ namens .priority referenziert werden. Sie können Prioritäten mit GET Anfragen lesen und mit PUT Anfragen schreiben. Die folgende Anfrage ruft beispielsweise die Priorität des Knotens users/tom ab:

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

Um Priorität und Daten gleichzeitig zu schreiben, können Sie der JSON-Nutzlast ein untergeordnetes .priority Element hinzufügen:

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

Um Priorität und einen Grundwert (z. B. eine Zeichenfolge) gleichzeitig zu schreiben, können Sie ein .priority Kind hinzufügen und den Grundwert in ein .value Kind einfügen:

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

Dies schreibt "Tom" mit einer Priorität von 1.0 . Prioritäten können in beliebiger Tiefe in die JSON-Nutzlast eingefügt werden.

Serverwerte

Sie können Serverwerte an einem Ort schreiben, indem Sie einen Platzhalterwert verwenden, der ein Objekt mit einem einzelnen .sv Schlüssel ist. Der Wert für diesen Schlüssel ist der Typ des Serverwerts, den Sie festlegen möchten. Die folgende Anfrage setzt beispielsweise den Wert des Knotens auf den aktuellen Zeitstempel des Firebase-Servers:

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

Sie können Prioritäten auch mithilfe von Serverwerten schreiben, indem Sie den oben genannten „virtuellen untergeordneten“ Pfad verwenden.

Zu den unterstützten Serverwerten gehören:

Serverwert
Zeitstempel Die Zeit seit der UNIX-Epoche in Millisekunden.
Zuwachs Geben Sie einen Ganzzahl- oder Gleitkomma-Deltawert in der Form { ".sv": {"increment": <delta_value> }} , mit dem der aktuelle Datenbankwert atomar erhöht werden soll. Wenn die Daten noch nicht vorhanden sind, werden die Daten durch das Update auf den Deltawert gesetzt. Wenn entweder der Deltawert oder die vorhandenen Daten Gleitkommazahlen sind, werden beide Werte als Gleitkommazahlen interpretiert und im Backend als Double-Wert angewendet. Doppelte Arithmetik und Darstellung von doppelten Werten folgen der IEEE 754-Semantik. Bei einem positiven/negativen Ganzzahlüberlauf wird die Summe als Double berechnet.

Abrufen und Aktualisieren von Firebase-Echtzeitdatenbank-Sicherheitsregeln

Die REST-API kann auch zum Abrufen und Aktualisieren der Firebase-Echtzeitdatenbank-Sicherheitsregeln für Ihr Firebase-Projekt verwendet werden. Sie benötigen das Geheimnis Ihres Firebase-Projekts, das Sie im Bereich „Dienstkonten“ der Einstellungen Ihres Firebase-Projekts finden.

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'

Authentifizieren Sie Anfragen

Standardmäßig werden REST-Anfragen ohne Authentifizierung ausgeführt und sind nur dann erfolgreich, wenn die Echtzeitdatenbankregeln öffentlichen Lese- oder Schreibzugriff auf die Daten zulassen. Um Ihre Anfrage zu authentifizieren, verwenden Sie die Abfrageparameter access_token= oder auth= .

Weitere Informationen zur Authentifizierung über die REST-API finden Sie unter Authentifizieren von REST-Anfragen .

Fehlerbedingungen

Die Firebase-Datenbank-REST-API kann die folgenden Fehlercodes zurückgeben.

HTTP-Statuscodes
400 Ungültige Anfrage

Eine der folgenden Fehlerbedingungen:

  • PUT oder POST Daten können nicht analysiert werden.
  • Fehlende PUT oder POST Daten.
  • Die Anfrage versucht, zu große Daten PUT oder POST zu senden.
  • Der REST-API-Aufruf enthält ungültige untergeordnete Namen als Teil des Pfads.
  • Der REST-API-Aufrufpfad ist zu lang.
  • Die Anfrage enthält einen unbekannten Serverwert.
  • Der Index für die Abfrage ist nicht in Ihren Firebase Realtime Database Security Rules definiert.
  • Die Anfrage unterstützt einen der angegebenen Abfrageparameter nicht.
  • Die Anfrage mischt Abfrageparameter mit einer flachen GET Anfrage.
401 nicht Autorisiert

Eine der folgenden Fehlerbedingungen:

  • Das Authentifizierungstoken ist abgelaufen.
  • Das in der Anfrage verwendete Authentifizierungstoken ist ungültig.
  • Die Authentifizierung mit einem access_token ist fehlgeschlagen.
  • Die Anfrage verstößt gegen Ihre Firebase-Echtzeitdatenbank-Sicherheitsregeln.
404 Nicht gefunden Die angegebene Echtzeitdatenbank wurde nicht gefunden.
500 Interner Serverfehler Der Server hat einen Fehler zurückgegeben. Weitere Einzelheiten finden Sie in der Fehlermeldung.
503 Dienst nicht verfügbar Die angegebene Firebase-Echtzeitdatenbank ist vorübergehend nicht verfügbar, was bedeutet, dass die Anfrage nicht versucht wurde.
412 Vorbedingung fehlgeschlagen Der angegebene ETag-Wert der Anfrage im if-match-Header stimmte nicht mit dem Wert des Servers überein.