Lesen von Daten mit GET
Wir können Daten aus unserer Firebase-Datenbank lesen, indem wir eine GET
-Anforderung an ihren URL-Endpunkt senden. Lassen Sie uns mit unserem Blog-Beispiel aus dem vorherigen Abschnitt fortfahren und alle unsere Blog-Post-Daten lesen:
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
Eine erfolgreiche Anfrage wird durch den HTTP-Statuscode 200 OK
angezeigt und die Antwort enthält die Daten, die wir abrufen.
Hinzufügen von URI-Parametern
Die REST-API akzeptiert mehrere Abfrageparameter beim Lesen von Daten aus unserer Firebase-Datenbank. Nachfolgend sind die am häufigsten verwendeten Parameter aufgeführt. Eine vollständige Liste finden Sie in der REST-API-Referenz .
Authentifizierung
Der Anforderungsparameter auth
ermöglicht den Zugriff auf Daten, die durch Firebase Realtime Database Rules geschützt sind, und wird von allen Anforderungstypen unterstützt. Das Argument kann entweder das Geheimnis Ihrer Firebase-App oder ein Authentifizierungstoken sein, wie in den Benutzern in Firebase-Projekten beschrieben. Im folgenden Beispiel senden wir eine GET
-Anforderung mit einem CREDENTIAL
auth
das Geheimnis Ihrer Firebase-App oder ein Authentifizierungstoken ist:
curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'
Die Angabe von print=pretty
gibt die Daten in einem für Menschen lesbaren Format zurück.
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
Die Angabe von print=silent
gibt bei Erfolg 204 No Content
zurück.
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'
zurückrufen
Um REST-Aufrufe von einem Webbrowser über Domänen hinweg durchzuführen, können Sie JSONP verwenden, um die Antwort in eine JavaScript-Callback-Funktion zu verpacken. Fügen Sie callback=
, damit die REST-API die zurückgegebenen Daten in die von Ihnen angegebene Rückruffunktion einschließt. Zum Beispiel:
<script> function gotData(data) { console.log(data); } </script> <script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">
seicht
Dies ist eine erweiterte Funktion, die Ihnen bei der Arbeit mit großen Datensätzen helfen soll, ohne alles herunterladen zu müssen. Um es zu verwenden, fügen Sie shallow=true
als Parameter hinzu. Dadurch wird die Tiefe der zurückgegebenen Daten begrenzt. Wenn die Daten an der Position ein JSON-Primitive (Zeichenfolge, Zahl oder boolescher Wert) sind, wird ihr 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 . Verwenden Sie zum Beispiel die folgenden Daten:
{ "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!"
Probieren Sie es mit dieser curl
Anfrage aus:
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'
Auszeit
Verwenden Sie dies, um zu begrenzen, wie lange das Lesen auf der Serverseite dauert. Wenn eine Leseanforderung nicht innerhalb der zugewiesenen 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 potenziell 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. Im folgenden Beispiel enthält die GET
Anforderung ein timeout
von 10 Sekunden.
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'
Filtern von Daten
Wir können Abfragen erstellen, um Daten basierend auf verschiedenen Faktoren zu filtern. Zunächst geben Sie mit dem Parameter orderBy
an, wie Ihre Daten gefiltert werden sollen. Dann kombinieren Sie orderBy
mit einem der anderen fünf Parameter: limitToFirst
, limitToLast
, startAt
, endAt
und equalTo
.
Da wir alle bei Firebase Dinosaurier ziemlich cool finden, verwenden wir einen Ausschnitt aus einer Beispieldatenbank mit Dinosaurier-Fakten, um zu demonstrieren, wie Sie Daten filtern können:
{ "lambeosaurus": { "height": 2.1, "length": 12.5, "weight": 5000 }, "stegosaurus": { "height": 4, "length": 9, "weight": 2500 } }
Wir können Daten auf drei Arten filtern: nach untergeordnetem Schlüssel , nach Schlüssel oder nach Wert . Eine Abfrage beginnt mit einem dieser Parameter und muss dann mit einem oder mehreren der folgenden Parameter kombiniert werden: startAt
, endAt
, limitToFirst
, limitToLast
oder equalTo
.
Filtern nach einem angegebenen untergeordneten Schlüssel
Wir können Knoten nach einem gemeinsamen untergeordneten Schlüssel filtern, indem wir diesen Schlüssel an den Parameter orderBy
. Um beispielsweise alle Dinosaurier mit einer Größe von mehr als 3 abzurufen, können wir Folgendes tun:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'
Jeder Knoten, der nicht den untergeordneten Schlüssel hat, nach dem wir filtern, wird mit dem Wert null
sortiert. Einzelheiten zum Sortieren von Daten finden Sie unter Sortieren von Daten .
Firebase unterstützt auch Abfragen, die nach tief verschachtelten untergeordneten Elementen geordnet sind, und nicht nur nach untergeordneten Elementen eine Ebene tiefer. Dies ist nützlich, wenn Sie tief verschachtelte Daten wie diese haben:
{ "lambeosaurus": { "dimensions": { "height" : 2.1, "length" : 12.5, "weight": 5000 } }, "stegosaurus": { "dimensions": { "height" : 4, "length" : 9, "weight" : 2500 } } }
Um die Höhe jetzt abzufragen, verwenden wir statt eines einzelnen Schlüssels den vollständigen Pfad zum Objekt:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'
Abfragen können jeweils nur nach einem Schlüssel filtern. Die mehrmalige Verwendung des Parameters orderBy
für dieselbe Anforderung löst einen Fehler aus.
Filtern nach Schlüssel
Wir können Nodes auch nach ihren Schlüsseln filtern, indem wir den Parameter orderBy="$key"
verwenden. Das folgende Beispiel ruft alle Dinosaurier ab, deren Namen mit den Buchstaben a
bis m
beginnen:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'
Filtern nach Wert
Wir können Knoten nach dem Wert ihrer untergeordneten Schlüssel filtern, indem wir den Parameter orderBy="$value"
. Nehmen wir an, die Dinosaurier veranstalten einen Dino-Sportwettbewerb und wir verfolgen ihre Punktzahlen im folgenden Format:
{ "scores": { "bruhathkayosaurus": 55, "lambeosaurus": 21, "linhenykus": 80, "pterodactyl": 93, "stegosaurus": 5, "triceratops": 22 } }
Um alle Dinosaurier mit einer Punktzahl von mehr als 50 abzurufen, könnten wir die folgende Anfrage stellen:
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'
Siehe Sortieren von Daten für eine Erläuterung, wie null
, boolesche Werte, Zeichenfolgen und Objektwerte sortiert werden, wenn orderBy="$value"
.
Komplexe Filterung
Wir können mehrere Parameter kombinieren, um komplexere Abfragen zu erstellen.
Abfragen einschränken
Die Parameter limitToFirst
und limitToLast
werden verwendet, um eine maximale Anzahl von untergeordneten Elementen festzulegen, für die Daten empfangen werden sollen. Wenn wir ein Limit von 100 festlegen, erhalten wir nur bis zu 100 passende Kinder. Wenn wir weniger als 100 Nachrichten in unserer Datenbank gespeichert haben, erhalten wir jedes Kind. Wenn wir jedoch über 100 Nachrichten haben, erhalten wir nur Daten für 100 dieser Nachrichten. Dies sind die ersten 100 geordneten Nachrichten, wenn wir limitToFirst
verwenden, oder die letzten 100 geordneten Nachrichten, wenn wir limitToLast
verwenden.
Mithilfe unserer Dinosaurier-Faktendatenbank und orderBy
können wir die beiden schwersten Dinosaurier finden:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'
In ähnlicher Weise können wir die beiden kürzesten Dinosaurier finden, indem wir limitToFirst
verwenden:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'
Wir können auch Limitabfragen mit orderBy="$value"
. Wenn wir eine Rangliste mit den drei besten Dino-Sportwettkämpfern mit der höchsten Punktzahl erstellen möchten, könnten wir Folgendes tun:
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'
Bereichsabfragen
Durch die Verwendung startAt
, endAt
und equalTo
können wir beliebige Start- und Endpunkte für unsere Abfragen auswählen. Wenn wir beispielsweise alle Dinosaurier finden möchten, die mindestens drei Meter groß sind, können wir orderBy
und startAt
kombinieren:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'
Wir können endAt
verwenden, um alle Dinosaurier zu finden, deren Namen lexikografisch vor Pterodaktylus stehen:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'
Wir können startAt
und endAt
kombinieren, um beide Enden unserer Abfrage einzuschränken. Das folgende Beispiel findet alle Dinosaurier, deren Name mit dem Buchstaben „b“ beginnt:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'
Bereichsabfragen sind auch nützlich, wenn Sie Ihre Daten paginieren müssen.
Alles zusammenfügen
Wir können all diese Techniken kombinieren, um komplexe Abfragen zu erstellen. Vielleicht möchten Sie zum Beispiel die Namen aller Dinosaurier finden, die kleiner oder gleich groß wie unsere Lieblingsart Stegosaurus sind:
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"
Wie Daten bestellt werden
In diesem Abschnitt wird erläutert, wie Ihre Daten sortiert werden, wenn Sie jeden der drei Filterparameter verwenden.
Sortieren nach
Bei der Verwendung von orderBy
mit dem Namen eines untergeordneten Schlüssels werden Daten, die den angegebenen untergeordneten Schlüssel enthalten, wie folgt geordnet:
- Kinder mit einem
null
für den angegebenen untergeordneten Schlüssel kommen zuerst. - Als nächstes kommen Kinder mit dem Wert
false
für den angegebenen untergeordneten Schlüssel. Wenn mehrere Kinder den Wertfalse
haben, werden sie lexikografisch nach Schlüssel sortiert. - Als nächstes kommen Kinder mit dem Wert
true
für den angegebenen untergeordneten Schlüssel. Wenn mehrere Kinder den Werttrue
haben, werden sie lexikografisch nach Schlüssel sortiert. - Kinder mit einem numerischen Wert kommen als nächstes, in aufsteigender Reihenfolge sortiert. Wenn mehrere untergeordnete Knoten denselben numerischen Wert für den angegebenen untergeordneten Knoten haben, werden sie nach Schlüssel sortiert.
- Zeichenfolgen kommen nach Zahlen und werden lexikografisch in aufsteigender Reihenfolge sortiert. Wenn mehrere untergeordnete Knoten denselben Wert für den angegebenen untergeordneten Knoten haben, werden sie lexikografisch nach Schlüssel geordnet.
- Die Objekte kommen zuletzt und werden lexikografisch nach Schlüssel in aufsteigender Reihenfolge sortiert.
orderBy="$key"
Wenn Sie den Parameter orderBy="$key"
zum Sortieren Ihrer Daten verwenden, werden die Daten wie folgt in aufsteigender Reihenfolge nach Schlüssel zurückgegeben. Denken Sie daran, dass Schlüssel nur Zeichenfolgen sein können.
- Kinder mit einem Schlüssel, der als 32-Bit-Ganzzahl geparst werden kann, kommen zuerst, sortiert in aufsteigender Reihenfolge.
- Kinder mit einem Zeichenfolgenwert als Schlüssel kommen als nächstes, lexikografisch in aufsteigender Reihenfolge sortiert.
orderBy="$value"
Wenn Sie den Parameter orderBy="$value"
verwenden, um Ihre Daten zu sortieren, werden Kinder nach ihrem Wert geordnet. Die Sortierkriterien sind die gleichen wie die nach einem untergeordneten Schlüssel geordneten Daten, außer dass der Wert des Knotens anstelle des Werts eines angegebenen untergeordneten Schlüssels verwendet wird.
orderBy="$priorität"
Wenn Sie den Parameter orderBy="$priority"
zum Sortieren Ihrer Daten verwenden, wird die Reihenfolge der untergeordneten Elemente anhand ihrer Priorität und ihres Schlüssels wie folgt bestimmt. Beachten Sie, dass Prioritätswerte nur Zahlen oder Zeichenfolgen sein können.
- Kinder ohne Priorität (Standardeinstellung) kommen zuerst.
- Kinder mit einer Nummer als Priorität kommen als nächstes. Sie sind numerisch nach Priorität sortiert, klein bis groß.
- Kinder mit einer Schnur als Priorität kommen zuletzt. Sie sind lexikografisch nach Priorität sortiert.
- Immer wenn zwei untergeordnete Elemente dieselbe Priorität haben (einschließlich keiner Priorität), werden sie nach Schlüssel sortiert. Numerische Schlüssel kommen zuerst (numerisch sortiert), gefolgt von den restlichen Schlüsseln (lexikografisch sortiert).
Weitere Informationen zu Prioritäten finden Sie in der API-Referenz .
Streaming von der REST-API
Firebase-REST-Endpunkte unterstützen das EventSource/Server-Sent Events- Protokoll, sodass Änderungen einfach an einen einzigen Ort in unserer Firebase-Datenbank gestreamt werden können.
Um mit dem Streaming zu beginnen, müssen wir Folgendes tun:
- Legen Sie den Accept-Header des Clients auf
text/event-stream
- Respektieren Sie HTTP-Weiterleitungen, insbesondere den HTTP-Statuscode 307
- Schließen Sie den Abfrageparameter
auth
ein, wenn für den Speicherort der Firebase-Datenbank eine Leseberechtigung erforderlich ist
Im Gegenzug sendet der Server benannte Ereignisse, wenn sich der Status der Daten an der angeforderten URL ändert. Der Aufbau dieser Nachrichten entspricht dem EventSource-Protokoll:
event: event name data: JSON encoded data payload
Der Server kann die folgenden Ereignisse senden:
stellen | Die JSON-codierten Daten sind ein Objekt mit zwei Schlüsseln: Pfad und Daten Der Pfad zeigt auf einen Ort relativ zur Anforderungs-URL Der Client sollte alle Daten an dieser Stelle in seinem Cache durch die in der Nachricht angegebenen Daten ersetzen |
Patch | Die JSON-codierten Daten sind ein Objekt mit zwei Schlüsseln: Pfad und Daten Der Pfad zeigt auf einen Ort relativ zur Anforderungs-URL Für jeden Schlüssel in den Daten 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 ist keine Aktion erforderlich |
Abbrechen | Die Daten für dieses Ereignis sind null Dieses Ereignis wird gesendet, wenn die Firebase-Echtzeitdatenbankregeln dazu führen, dass ein Lesevorgang am angeforderten Speicherort nicht mehr zulässig ist |
auth_widerrufen | Die Daten für dieses Ereignis sind eine Zeichenfolge, die angibt, dass der Berechtigungsnachweis abgelaufen ist Dieses Ereignis wird gesendet, wenn der angegebene Authentifizierungsparameter nicht mehr gültig ist |
Unten ist ein Beispiel für eine Reihe 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}}
Wenn Sie Go verwenden, sehen Sie sich Firego an, einen Drittanbieter-Wrapper für die Firebase-REST- und Streaming-APIs.