Pobieram dane

Odczytywanie danych za pomocą metody GET

Dane z bazy danych Firebase możemy odczytać, wysyłając żądanie GET do jej punktu końcowego URL. Wróćmy do przykładu bloga z poprzedniej sekcji i odczytajmy wszystkie dane z postów:

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

Żądanie zakończone powodzeniem będzie oznaczone kodem stanu HTTP 200 OK, a odpowiedź będzie zawierać odczytywane dane.

Dodawanie parametrów URI

Podczas odczytywania danych z bazy danych Firebase interfejs REST API akceptuje kilka parametrów zapytania. Poniżej znajdziesz listę najczęściej używanych parametrów. Pełną listę znajdziesz w dokumentacji interfejsu REST API.

autoryzacja

Parametr żądania auth umożliwia dostęp do danych chronionych przez Firebase Realtime Database Security Rules i jest obsługiwany przez wszystkie typy żądań. Argumentem może być tajny klucz aplikacji Firebase lub token uwierzytelniania, zgodnie z opisem w sekcji Użytkownicy w projektach Firebase. W tym przykładzie wysyłamy żądanie GET z parametrem auth, gdzie CREDENTIAL to tajny klucz aplikacji Firebase lub token uwierzytelniania:

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

drukuj

Określenie print=pretty powoduje zwrócenie danych w formacie czytelnym dla człowieka.

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

Określenie print=silent powoduje zwrócenie kodu 204 No Content w przypadku powodzenia.

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

callback

Aby wykonywać wywołania REST z przeglądarki internetowej w różnych domenach, możesz użyć JSONP do opakowania odpowiedzi w funkcję wywołania zwrotnego JavaScript. Dodaj callback=, aby interfejs REST API opakował zwrócone dane w określonej przez Ciebie funkcji wywołania zwrotnego. Przykład:

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

płytkie

Jest to funkcja zaawansowana, która pomaga pracować z dużymi zbiorami danych bez konieczności pobierania wszystkich danych. Aby z niej skorzystać, dodaj parametr shallow=true. Ograniczy to głębokość zwracanych danych. Jeśli dane w lokalizacji są typem pierwotnym JSON (ciąg, liczba, lub wartość logiczna), zostanie zwrócona ich wartość. Jeśli migawka danych w lokalizacji jest obiektem JSON, wartości każdego klucza zostaną skrócone do true. Na przykład w przypadku tych danych:

{
  "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!"

Wypróbuj to żądanie curl:

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

czas oczekiwania

Użyj tego parametru, aby ograniczyć czas odczytu po stronie serwera. Jeśli żądanie odczytu nie zostanie zakończone w wyznaczonym czasie, zostanie przerwane z błędem HTTP 400. Jest to szczególnie przydatne, gdy spodziewasz się niewielkiego transferu danych i nie chcesz zbyt długo czekać na pobranie potencjalnie dużego poddrzewa. Rzeczywisty czas odczytu może się różnić w zależności od rozmiaru danych i buforowania.

Określ timeouts w tym formacie: 3ms, 3s, lub 3min, z liczbą i jednostką. Jeśli nie określisz, zostanie zastosowany maksymalny timeout z 15min. Jeśli timeout nie jest dodatni lub przekracza wartość maksymalną, żądanie zostanie odrzucone z błędem HTTP 400. W tym przykładzie żądanie GET zawiera timeout wynoszący 10 sekund.

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

Filtrowanie danych

Możemy tworzyć zapytania, aby filtrować dane na podstawie różnych czynników. Na początek określ, jak chcesz filtrować dane, za pomocą parametru orderBy. Następnie połącz orderBy z dowolnym z 5 pozostałych parametrów: limitToFirst, limitToLast, startAt, endAt, i equalTo.

Wszyscy w Firebase uważamy, że dinozaury są fajne, więc użyjemy fragmentu z przykładowej bazy danych z faktami o dinozaurach, aby pokazać, jak można filtrować dane:

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

Dane możemy filtrować na 3 sposoby: według klucza podrzędnego, klucza lub wartości. Zapytanie zaczyna się od jednego z tych parametrów, a następnie musi być połączone z co najmniej jednym z tych parametrów: startAt, endAt, limitToFirst, limitToLast lub equalTo.

Filtrowanie według określonego klucza podrzędnego

Węzły możemy filtrować według wspólnego klucza podrzędnego, przekazując ten klucz do parametru orderBy. Aby na przykład pobrać wszystkie dinozaury o wysokości większej niż 3, możemy wykonać te czynności:

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

Każdy węzeł, który nie ma klucza podrzędnego, według którego filtrujemy, zostanie posortowany z wartością null. Więcej informacji o tym, jak są uporządkowane dane , znajdziesz w sekcji Jak są uporządkowane dane.

Firebase obsługuje też zapytania uporządkowane według głęboko zagnieżdżonych elementów podrzędnych, a nie tylko elementów podrzędnych na 1 poziomie. Jest to przydatne, jeśli masz głęboko zagnieżdżone dane, takie jak te:

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

Aby teraz wysłać zapytanie o wysokość, używamy pełnej ścieżki do obiektu, a nie pojedynczego klucza:

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

Zapytania mogą filtrować tylko według 1 klucza naraz. Użycie parametru orderBy kilka razy w tym samym żądaniu powoduje błąd.

Filtrowanie według klucza

Węzły możemy też filtrować według ich kluczy za pomocą parametru orderBy="$key". Ten przykład pobiera wszystkie dinozaury, których nazwy zaczynają się od litery a do m:

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

Filtrowanie według wartości

Węzły możemy filtrować według wartości ich kluczy podrzędnych za pomocą parametru orderBy="$value". Załóżmy, że dinozaury biorą udział w zawodach sportowych, a my śledzimy ich wyniki w tym formacie:

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

Aby pobrać wszystkie dinozaury z wynikiem powyżej 50, możemy wysłać to żądanie:

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

Więcej informacji o tym, jak są sortowane wartości null, logiczne, ciągi i obiekty podczas używania parametru orderBy="$value", znajdziesz w sekcji Jak są uporządkowane dane.

Filtrowanie złożone

Możemy łączyć ze sobą kilka parametrów, aby tworzyć bardziej złożone zapytania.

Zapytania z ograniczeniami

Parametry limitToFirst i limitToLast służą do ustawiania maksymalnej liczby elementów podrzędnych, dla których mają być odbierane dane. Jeśli ustawimy limit 100, otrzymamy tylko maksymalnie 100 pasujących elementów podrzędnych. Jeśli w bazie danych mamy mniej niż 100 wiadomości, otrzymamy wszystkie elementy podrzędne. Jeśli jednak mamy ponad 100 wiadomości, otrzymamy dane tylko dla 100 z nich. Będą to pierwsze 100 uporządkowanych wiadomości, jeśli używamy limitToFirst lub ostatnie 100 uporządkowanych wiadomości, jeśli używamy limitToLast.

Korzystając z bazy danych z faktami o dinozaurach i orderBy, możemy znaleźć 2 najcięższe dinozaury:

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

Podobnie możemy znaleźć 2 najkrótsze dinozaury, używając parametru limitToFirst:

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

Możemy też wykonywać zapytania z ograniczeniami za pomocą parametru orderBy="$value". Jeśli chcemy utworzyć ranking 3 najlepszych zawodników w sportach dinozaurów, możemy wykonać te czynności:

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

Zapytania dotyczące zakresu

Użycie parametrów startAt, endAt i equalTo pozwala nam wybrać dowolne punkty początkowe i końcowe dla naszych zapytań. Jeśli na przykład chcemy znaleźć wszystkie dinozaury o wysokości co najmniej 3 metrów, możemy połączyć parametry orderBy i startAt:

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

Za pomocą parametru endAt możemy znaleźć wszystkie dinozaury, których nazwy są leksykograficznie wcześniejsze niż „pterodactyl” :

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

Możemy połączyć parametry startAt i endAt, aby ograniczyć oba końce zapytania. Ten przykład znajduje wszystkie dinozaury, których nazwy zaczynają się od litery „b”:

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

Zapytania dotyczące zakresu są też przydatne, gdy trzeba podzielić dane na strony.

Łączę wszystko w całość

Możemy łączyć wszystkie te techniki, aby tworzyć złożone zapytania. Możesz na przykład chcieć znaleźć nazwy wszystkich dinozaurów, które są krótsze lub równe wysokością naszemu ulubionemu dinozaurowi, czyli stegozaurowi:

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"

Jak są uporządkowane dane

W tej sekcji wyjaśniamy, jak są uporządkowane dane podczas używania każdego z 3 parametrów filtrowania.

orderBy

Gdy używasz parametru orderBy z nazwą klucza podrzędnego, dane zawierające określony klucz podrzędny są uporządkowane w ten sposób:

1. Najpierw są elementy podrzędne z wartością null dla określonego klucza podrzędnego.
2. Następnie są elementy podrzędne z wartością false dla określonego klucza podrzędnego. Jeśli kilka elementów podrzędnych ma wartość false, są one sortowane leksykograficznie według klucza.
3. Następnie są elementy podrzędne z wartością true dla określonego klucza podrzędnego. Jeśli kilka elementów podrzędnych ma wartość true, są one sortowane leksykograficznie według klucza.
4. Następnie są elementy podrzędne z wartością liczbową, posortowane w kolejności rosnącej. Jeśli kilka elementów podrzędnych ma tę samą wartość liczbową dla określonego węzła podrzędnego, są one sortowane według klucza.
5. Po liczbach występują ciągi znaków, które są sortowane leksykograficznie w kolejności rosnącej. Jeśli kilka elementów podrzędnych ma tę samą wartość dla określonego węzła podrzędnego, są one sortowane leksykograficznie według klucza.
6. Obiekty są ostatnie i sortowane leksykograficznie według klucza w kolejności rosnącej.

orderBy="$key"

Gdy używasz parametru orderBy="$key" do sortowania danych, dane są zwracane w kolejności rosnącej według klucza w ten sposób. Pamiętaj, że klucze mogą być tylko ciągami znaków.

1. Najpierw są elementy podrzędne z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, posortowane w kolejności rosnącej.
2. Następnie są elementy podrzędne z wartością ciągu znaków jako kluczem, posortowane leksykograficznie w kolejności rosnącej.

orderBy="$value"

Gdy używasz parametru orderBy="$value" do sortowania danych, elementy podrzędne są uporządkowane według ich wartości. Kryteria sortowania są takie same jak w przypadku danych uporządkowanych według klucza podrzędnego, z tym że zamiast wartości określonego klucza podrzędnego używana jest wartość węzła.

orderBy="$priority"

Gdy używasz parametru orderBy="$priority" do sortowania danych, kolejność elementów podrzędnych jest określana na podstawie ich priorytetu i klucza w ten sposób. Pamiętaj, że wartości priorytetu mogą być tylko liczbami lub ciągami znaków.

1. Najpierw są elementy podrzędne bez priorytetu (domyślne).
2. Następnie są elementy podrzędne z liczbą jako priorytetem. Są one sortowane numerycznie według priorytetu, od najmniejszej do największej wartości.
3. Na końcu są elementy podrzędne z ciągiem znaków jako priorytetem. Są one sortowane leksykograficznie według priorytetu.
4. Gdy 2 elementy podrzędne mają ten sam priorytet (w tym brak priorytetu), są one sortowane według klucza. Najpierw są klucze liczbowe (posortowane numerycznie), a następnie pozostałe klucze (posortowane leksykograficznie).

Więcej informacji o priorytetach znajdziesz w dokumentacji interfejsu API.

Przesyłanie strumieniowe z interfejsu REST API

Punkty końcowe Firebase REST obsługują protokół EventSource / Server-Sent Events, co ułatwia przesyłanie strumieniowe zmian do pojedynczej lokalizacji w bazie danych Firebase.

Aby rozpocząć przesyłanie strumieniowe, musimy wykonać te czynności:

1. Ustaw nagłówek Accept klienta na text/event-stream.
2. Przestrzegaj przekierowań HTTP, w szczególności kodu stanu HTTP 307.
3. Jeśli lokalizacja bazy danych Firebase wymaga uprawnień do odczytu, dodaj parametr zapytania auth.

W odpowiedzi serwer będzie wysyłać nazwane zdarzenia, gdy zmieni się stan danych pod żądanym adresem URL zmienia się. Struktura tych wiadomości jest zgodna z protokołem EventSource:

event: event name
data: JSON encoded data payload

Serwer może wysyłać te zdarzenia:

Poniżej znajdziesz przykład zestawu zdarzeń, które serwer może wysłać:

// 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}}

Jeśli używasz Go, zapoznaj się z Firego, czyli wrapperem innej firmy dla interfejsów Firebase REST i Streaming API.