Daten werden abgerufen

Daten mit GET lesen

Wir können Daten aus unserer Firebase-Datenbank lesen, indem wir eine GET-Anfrage an den URL-Endpunkt senden. Fahren wir mit dem Blogbeispiel aus dem vorherigen Abschnitt fort und lesen alle Daten zu unseren Blogposts:

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

Eine erfolgreiche Anfrage wird durch einen 200 OK-HTTP-Statuscode angezeigt. Die Antwort enthält die abgerufenen Daten.

URI-Parameter hinzufügen

Die REST API akzeptiert mehrere Abfrageparameter beim Lesen von Daten aus unserer Firebase-Datenbank. Im Folgenden finden Sie die am häufigsten verwendeten Parameter. Eine vollständige Liste finden Sie in der REST API-Referenz.

auth

Der Anfrageparameter auth ermöglicht den Zugriff auf Daten, die durch Firebase Realtime Database Security Rules geschützt sind. Er wird von allen Anfragetypen unterstützt. Das Argument kann entweder das Secret Ihrer Firebase-App oder ein Authentifizierungstoken sein, wie unter Nutzer in Firebase-Projekten beschrieben. Im folgenden Beispiel senden wir eine GET-Anfrage mit einem auth-Parameter, wobei CREDENTIAL entweder das Secret Ihrer Firebase-App oder ein Authentifizierungstoken ist:

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

Wenn das debug-Flag des Tokens gesetzt ist, finden Sie Debug-Informationen im X-Firebase-Auth-Debug-Header der Antwort.

ausgeben

Wenn Sie print=pretty angeben, werden die Daten in einem für Menschen lesbaren Format zurückgegeben.

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

Wenn Sie print=silent angeben, wird bei Erfolg eine 204 No Content zurückgegeben.

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

callback

Wenn Sie REST-Aufrufe von einem Webbrowser aus über Domains hinweg ausführen möchten, können Sie JSONP verwenden, um die Antwort in eine JavaScript-Callback-Funktion einzubetten. Fügen Sie callback= hinzu, damit die REST API die zurückgegebenen Daten in die von Ihnen angegebene Callback-Funktion einbettet. Beispiel:

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

flach

Diese erweiterte Funktion soll Ihnen die Arbeit mit großen Datenmengen erleichtern, ohne dass Sie alles herunterladen müssen. Fügen Sie dazu shallow=true als Parameter hinzu. Dadurch wird die Tiefe der zurückgegebenen Daten begrenzt. Wenn die Daten an der Position ein JSON-Primitiv (String, Zahl oder boolescher Wert) sind, wird einfach der Wert zurückgegeben. Wenn der Daten-Snapshot an diesem Speicherort ein JSON-Objekt ist, werden die Werte für jeden Schlüssel auf true gekürzt. Verwenden Sie beispielsweise 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'

shallow kann nicht mit den Abfrageparametern für „Daten filtern“ verwendet werden.

Zeitüberschreitung

Hiermit lässt sich die Dauer des Lesens auf der Serverseite begrenzen. Wenn eine Leseanfrage nicht innerhalb des zugewiesenen Zeitraums abgeschlossen wird, wird sie mit dem HTTP-Fehler 400 beendet. Das ist besonders nützlich, wenn Sie mit einer kleinen Datenübertragung rechnen und nicht zu lange warten möchten, um einen potenziell riesigen untergeordneten Knoten abzurufen. Die tatsächliche Lesezeit kann je nach Datenmenge und Caching variieren.

Geben Sie timeouts im folgenden Format an: 3ms, 3s oder 3min mit einer Zahl und einer Einheit. Wenn keine Angabe erfolgt, wird das Maximum von timeout = 15min angewendet. Wenn timeout nicht positiv ist oder den Maximalwert überschreitet, wird die Anfrage mit dem HTTP-Fehler 400 abgelehnt. Im folgenden Beispiel enthält die GET-Anfrage eine timeout von 10 Sekunden.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

Daten filtern

Wir können Abfragen erstellen, um Daten nach verschiedenen Faktoren zu filtern. Geben Sie zuerst mit dem Parameter orderBy an, wie Ihre Daten gefiltert werden sollen. Kombinieren Sie dann orderBy mit einem der anderen fünf Parameter: limitToFirst, limitToLast, startAt, endAt und equalTo.

Gefilterte Daten werden unsortiert zurückgegeben: Bei Verwendung der REST API werden die gefilterten Ergebnisse in einer nicht definierten Reihenfolge zurückgegeben, da JSON-Interpreter keine Reihenfolge erzwingen. Wenn die Reihenfolge Ihrer Daten wichtig ist, sollten Sie die Ergebnisse in Ihrer Anwendung sortieren, nachdem sie von Firebase zurückgegeben wurden.

Da wir bei Firebase Dinosaurier ziemlich cool finden, verwenden wir ein Snippet aus einer Beispieldatenbank mit Dinosaurierinformationen, um zu zeigen, wie Sie Daten filtern können:

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

Es gibt drei Möglichkeiten, Daten zu filtern: nach untergeordnetem Schlüssel, nach Schlüssel oder nach Wert. Eine Suchanfrage beginnt mit einem dieser Parameter und muss dann mit einem oder mehreren der folgenden Parameter kombiniert werden: startAt, endAt, limitToFirst, limitToLast oder equalTo.

Nach einem bestimmten untergeordneten Schlüssel filtern

Wir können Knoten nach einem gemeinsamen untergeordneten Schlüssel filtern, indem wir diesen Schlüssel an den Parameter orderBy übergeben. Wenn wir beispielsweise alle Dinosaurier mit einer Höhe von mehr als 3 abrufen möchten, gehen wir so vor:

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

Alle Knoten, die nicht den untergeordneten Schlüssel haben, nach dem wir filtern, werden mit dem Wert null sortiert. Weitere Informationen zur Sortierung von Daten finden Sie unter Sortierung von Daten.

Firebase unterstützt auch Abfragen, die nach tief verschachtelten untergeordneten Elementen sortiert sind, nicht nur nach untergeordneten Elementen auf einer Ebene. Das ist nützlich, wenn Sie 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 abzufragen, verwenden wir jetzt den vollständigen Pfad zum Objekt anstelle eines einzelnen Schlüssels:

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

Bei Abfragen kann jeweils nur nach einem Schlüssel gefiltert werden. Wenn der Parameter orderBy mehrmals in derselben Anfrage verwendet wird, wird ein Fehler ausgegeben.

Indexierung zu Ihrer Firebase Realtime Database Security Rules hinzufügen: Wenn Sie orderBy in Ihrer App verwenden, müssen Sie die Schlüssel, die Sie indexieren möchten, über die .indexOn-Regel in Ihrer Firebase Realtime Database Security Rules definieren. Weitere Informationen finden Sie in der Dokumentation zur Regel .indexOn.

Nach Schlüssel filtern

Mit dem Parameter orderBy="$key" können wir Knoten auch nach ihren Schlüsseln filtern. Im folgenden Beispiel werden alle Dinosaurier mit einem Namen abgerufen, der mit dem Buchstaben a bis m beginnt:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

Nach Wert filtern

Mit dem Parameter orderBy="$value" lassen sich Knoten nach dem Wert ihrer untergeordneten Schlüssel filtern. Angenommen, die Dinosaurier veranstalten einen Dino-Sportwettbewerb und wir führen die Punkte im folgenden Format auf:

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

Um alle Dinosaurier mit einer Bewertung von über 50 abzurufen, könnten wir die folgende Anfrage stellen:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

Eine Erklärung dazu, wie null-, boolesche, String- und Objektwerte bei Verwendung von orderBy="$value" sortiert werden, finden Sie unter Sortierung von Daten.

Firebase Realtime Database Security Rules Indexierung hinzufügen: Wenn Sie orderBy="$value" in Ihrer App verwenden, müssen Sie Ihren Regeln am entsprechenden Index .value hinzufügen. Weitere Informationen finden Sie in der Dokumentation zur Regel .indexOn.

Komplexe Filterung

Wir können mehrere Parameter kombinieren, um komplexere Abfragen zu erstellen.

Abfragen begrenzen

Mit den Parametern limitToFirst und limitToLast wird die maximale Anzahl von untergeordneten Elementen festgelegt, für die Daten empfangen werden sollen. Wenn wir ein Limit von 100 festlegen, erhalten wir nur bis zu 100 übereinstimmende untergeordnete Elemente. Wenn in unserer Datenbank weniger als 100 Nachrichten gespeichert sind, erhalten wir alle Kinder. Wenn wir jedoch mehr als 100 Nachrichten erhalten, erhalten wir nur Daten für 100 dieser Nachrichten. Bei limitToFirst sind dies die ersten 100 sortierten Nachrichten, bei limitToLast die letzten 100 sortierten Nachrichten.

Mithilfe unserer Datenbank mit Dinosaurierinformationen und orderBy können wir die beiden schwersten Dinosaurier finden:

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

Ebenso können wir mit limitToFirst die beiden kürzesten Dinosaurier finden:

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

Mit orderBy="$value" können wir auch Abfragen mit Begrenzungen durchführen. Wenn wir eine Bestenliste mit den drei besten Spielern erstellen möchten, die die meisten Punkte im Dino-Sport erzielt haben, gehen wir so vor:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

Bereichsabfragen

Mit 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 hoch sind, können wir orderBy und startAt kombinieren:

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

Mit endAt können wir alle Dinosaurier finden, deren Namen lexikalisch vor „Pterodactyl“ stehen:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

startAt und endAt sind inklusive, d. h. „Pterodactyl“ stimmt mit der obigen Abfrage überein.

Wir können startAt und endAt kombinieren, um beide Enden unserer Abfrage einzugrenzen. Im folgenden Beispiel werden alle Dinosaurier gefunden, deren Name mit dem Buchstaben „b“ beginnt:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

Das Zeichen \uf8ff in der obigen Abfrage hat einen sehr hohen Codepunkt im Unicode-Bereich. Da es sich nach den meisten regulären Zeichen in Unicode befindet, werden mit der Abfrage alle Werte gefunden, die mit einem „b“ beginnen.

Bereichsabfragen sind auch nützlich, wenn Sie Ihre Daten auf Seiten aufteilen möchten.

Zusammenfassung

Wir können all diese Techniken kombinieren, um komplexe Abfragen zu erstellen. Angenommen, Sie möchten den Namen aller Dinosaurier ermitteln, die kleiner oder gleich groß wie unser Lieblingsdinosaurier, der 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"

Sortierung von Daten

In diesem Abschnitt wird beschrieben, wie Ihre Daten bei Verwendung der drei Filterparameter sortiert werden.

Die REST API gibt unsortierte Ergebnisse zurück: JSON-Interpreter erzwingen keine Sortierung der Ergebnismenge. orderBy kann in Kombination mit startAt, endAt, limitToFirst oder limitToLast verwendet werden, um eine Teilmenge der Daten zurückzugeben. Die zurückgegebenen Ergebnisse werden jedoch nicht sortiert. Daher kann es erforderlich sein, die Ergebnisse manuell zu sortieren, wenn die Reihenfolge wichtig ist.

orderBy

Wenn Sie orderBy mit dem Namen eines untergeordneten Schlüssels verwenden, werden Daten, die den angegebenen untergeordneten Schlüssel enthalten, so sortiert:

1. Untergeordnete Elemente mit einem null-Wert für den angegebenen untergeordneten Schlüssel werden zuerst angezeigt.
2. Als Nächstes folgen untergeordnete Elemente mit dem Wert false für den angegebenen untergeordneten Schlüssel. Wenn mehrere untergeordnete Elemente den Wert false haben, werden sie lexikografisch nach Schlüssel sortiert.
3. Als Nächstes folgen untergeordnete Elemente mit dem Wert true für den angegebenen untergeordneten Schlüssel. Wenn mehrere untergeordnete Elemente den Wert true haben, werden sie nach Schlüssel sortiert.
4. Als Nächstes folgen untergeordnete Elemente mit einem numerischen Wert, sortiert in aufsteigender Reihenfolge. Wenn mehrere untergeordnete Elemente denselben numerischen Wert für den angegebenen untergeordneten Knoten haben, werden sie nach Schlüssel sortiert.
5. Strings folgen nach Zahlen und werden lexikografisch in aufsteigender Reihenfolge sortiert. Wenn mehrere untergeordnete Elemente denselben Wert für den angegebenen untergeordneten Knoten haben, werden sie lexikografisch nach Schlüssel sortiert.
6. Objekte kommen zuletzt und werden in aufsteigender lexikografischer Reihenfolge nach Schlüssel sortiert.

Die gefilterten Ergebnisse werden unsortiert zurückgegeben. Wenn die Reihenfolge Ihrer Daten wichtig ist, sollten Sie die Ergebnisse in Ihrer Anwendung sortieren, nachdem sie von Firebase zurückgegeben wurden.

orderBy="$key"

Wenn Sie den Parameter orderBy="$key" zum Sortieren Ihrer Daten verwenden, werden sie in aufsteigender Reihenfolge nach Schlüssel zurückgegeben. Schlüssel können nur Strings sein.

1. Untergeordnete Elemente mit einem Schlüssel, der als 32‑Bit-Ganzzahl geparst werden kann, werden zuerst in aufsteigender Reihenfolge sortiert.
2. Als Nächstes folgen untergeordnete Elemente mit einem Stringwert als Schlüssel, sortiert in aufsteigender lexikografischer Reihenfolge.

orderBy="$value"

Wenn Sie Ihre Daten mit dem Parameter orderBy="$value" sortieren, werden untergeordnete Elemente nach ihrem Wert angeordnet. Die Sortierkriterien sind dieselben wie bei Daten, die nach einem untergeordneten Schlüssel sortiert werden, mit der Ausnahme, dass der Wert des Knotens anstelle des Werts eines bestimmten untergeordneten Schlüssels verwendet wird.

orderBy="$priority"

Wenn Sie Ihre Daten mit dem Parameter orderBy="$priority" sortieren, wird die Reihenfolge der untergeordneten Elemente wie unten beschrieben anhand ihrer Priorität und ihres Schlüssels festgelegt. Prioritätswerte können nur Zahlen oder Strings sein.

Numerische Prioritäten werden als IEEE 754-Gleitkommazahlen mit doppelter Genauigkeit gespeichert und sortiert. Schlüssel werden immer als Strings gespeichert und nur dann als numerische Werte behandelt, wenn sie als 32‑Bit-Ganzzahl geparst werden können.

1. Kinder ohne Priorität (Standardeinstellung) werden zuerst berücksichtigt.
2. Kinder mit einer Zahl als Priorität kommen als Nächstes. Sie werden nach Priorität numerisch sortiert, von klein nach groß.
3. Elemente mit einem String als Priorität werden zuletzt berücksichtigt. Sie werden nach Priorität sortiert.
4. Wenn zwei untergeordnete Elemente dieselbe Priorität haben (einschließlich keiner Priorität), werden sie nach Schlüssel sortiert. Numerische Schlüssel werden zuerst (numerisch) sortiert, gefolgt von den übrigen Schlüsseln (lexikografisch sortiert).

Weitere Informationen zu Prioritäten finden Sie in der API-Referenz.

Streaming über die REST API

Firebase REST-Endpunkte unterstützen das EventSource-/Server-Sent-Events-Protokoll. So lassen sich Änderungen ganz einfach an einen einzigen Ort in der Firebase-Datenbank streamen.

Damit Sie mit dem Streaming beginnen können, müssen wir Folgendes tun:

1. Setzen Sie den Accept-Header des Clients auf text/event-stream.
2. HTTP-Weiterleitungen berücksichtigen, insbesondere den HTTP-Statuscode 307
3. Fügen Sie den Abfrageparameter auth hinzu, wenn für den Speicherort der Firebase-Datenbank eine Leseberechtigung erforderlich ist.

Als Antwort 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:

put	Die JSON-codierten Daten sind ein Objekt mit zwei Schlüsseln: „path“ und „data“. Der Pfad verweist auf einen Speicherort relativ zur Anfrage-URL. Der Client sollte alle Daten an diesem Speicherort in seinem Cache durch die in der Nachricht angegebenen Daten ersetzen.
patch	Die JSON-codierten Daten sind ein Objekt mit zwei Schlüsseln: „path“ und „data“. Der Pfad verweist auf einen Speicherort relativ zur Anfrage-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.
Keep-Alive	Die Daten für dieses Ereignis sind null. Es sind keine Maßnahmen erforderlich.
Abbrechen	Die Daten für dieses Ereignis sind null. Dieses Ereignis wird gesendet, wenn die Firebase Realtime Database Security Rules dazu führt, dass eine Leseoperation am angeforderten Speicherort nicht mehr zulässig ist.
auth_revoked	Die Daten für dieses Ereignis sind ein String, der angibt, dass die Anmeldedaten abgelaufen sind. Dieses Ereignis wird gesendet, wenn der angegebene Authentifizierungsparameter nicht mehr gültig ist.

Unten finden Sie 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.