Pobieram dane

Odczytywanie danych za pomocą metody GET

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

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ć pobierane dane.

Dodawanie parametrów URI

Interfejs REST API akceptuje kilka parametrów zapytania podczas odczytywania danych z bazy danych Firebase. Poniżej znajdziesz najczęściej używane parametry. Pełną listę znajdziesz w przewodniku po interfejsie API REST.

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 przykładzie poniżej 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 zwraca 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, aby opakować odpowiedź 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 zaawansowana funkcja, która pomaga pracować z dużymi zbiorami danych bez konieczności pobierania wszystkich informacji. Aby go użyć, dodaj shallow=true jako parametr. Ograniczy to głębokość zwracanych danych. Jeśli dane w lokalizacji są typem prostym JSON (ciąg tekstowy, 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 na podstawie 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, wysyłając to curlżądanie:

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 ukończone w przydzielonym czasie, zostanie zakończone 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, podając liczbę i jednostkę. Jeśli nie określisz tu żadnej wartości, zostanie zastosowana maksymalna wartość timeout 15min. Jeśli wartość timeout nie jest dodatnia lub przekracza wartość maksymalną, żądanie zostanie odrzucone z błędem HTTP 400. W tym przykładzie żądanie GET zawiera timeout o wartości 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 pozostałych 5 parametrów: limitToFirst, limitToLast, startAt, endAt i equalTo.

Wszyscy w Firebase uważamy, że dinozaury są fajne, więc użyjemy fragmentu 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 kolejności danych znajdziesz w artykule 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 jednym 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 jednego klucza naraz. Użycie parametru orderBy wiele razy w tym samym żądaniu powoduje błąd.

Filtrowanie według klucza

Możemy też filtrować węzły według kluczy za pomocą parametru orderBy="$key". W tym przykładzie pobierane są 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 i ś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 sortowane są wartości null, logiczne, ciągi tekstowe i obiekty podczas korzystania z funkcji orderBy="$value", znajdziesz w sekcji Jak są porządkowane dane.

Filtrowanie złożone

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

Ograniczanie zapytań

Parametry limitToFirst i limitToLast służą do ustawiania maksymalnej liczby dzieci, dla których mają być odbierane dane. Jeśli ustawimy limit 100, otrzymamy tylko maksymalnie 100 pasujących dzieci. Jeśli w naszej bazie danych jest mniej niż 100 wiadomości, otrzymamy wszystkie wiadomości od dziecka. Jeśli jednak mamy ponad 100 wiadomości, otrzymamy dane tylko dla 100 z nich. Będzie to pierwszych 100 uporządkowanych wiadomości, jeśli używamy limitToFirst, lub ostatnich 100 uporządkowanych wiadomości, jeśli używamy limitToLast.

Korzystając z naszej bazy danych 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 za pomocą funkcji limitToFirst:

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

Możemy też wykonywać zapytania o limit za pomocą orderBy="$value". Jeśli chcemy utworzyć ranking 3 najlepszych zawodników w dino sporcie, możemy to zrobić w ten sposób:

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

Zapytania dotyczące zakresu

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

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

Możemy użyć znaku endAt, aby znaleźć wszystkie dinozaury, których nazwy występują przed słowem Pterodactyl w porządku leksykograficznym:

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

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

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

Zapytania zakresowe są też przydatne, gdy musisz 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 znaleźć nazwy wszystkich dinozaurów, które są niższe lub tak samo wysokie jak nasz ulubiony gatunek, czyli stegozaur:

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"

Sposób porządkowania danych

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

orderBy

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

1. Najpierw pojawiają się dzieci z wartością null dla określonego klucza dziecka.
2. Następnie pojawią się elementy podrzędne z wartością false dla określonego klucza elementu podrzędnego. Jeśli wiele elementów podrzędnych ma wartość false, są one sortowane leksykograficznie według klucza.
3. Następnie pojawią się elementy podrzędne z wartością true dla określonego klucza elementu podrzędnego. Jeśli kilka elementów podrzędnych ma wartość true, są one sortowane leksykograficznie według klucza.
4. Następnie pojawiają się 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ą w przypadku określonego węzła podrzędnego, są one sortowane według klucza.
5. Ciągi znaków występują po liczbach i są sortowane leksykograficznie w kolejności rosnącej. Jeśli kilka węzłów podrzędnych ma tę samą wartość w przypadku określonego węzła podrzędnego, są one porządkowane leksykograficznie według klucza.
6. Obiekty są umieszczane na końcu i sortowane leksykograficznie według klucza w kolejności rosnącej.

orderBy="$key"

Jeśli do sortowania danych użyjesz parametru orderBy="$key", dane będą 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 pojawiają się dzieci z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, posortowane w kolejności rosnącej.
2. Następnie pojawiają się dzieci z wartością ciągu znaków jako kluczem, posortowane leksykograficznie w kolejności rosnącej.

orderBy="$value"

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

orderBy="$priority"

Jeśli do sortowania danych używasz parametru orderBy="$priority", 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 wyświetlane są elementy podrzędne bez priorytetu (domyślnego).
2. Następnie wyświetlane są treści dla dzieci z numerem jako priorytetem. Są one posortowane numerycznie według priorytetu, od najmniejszego do największego.
3. Dzieci z ciągiem znaków jako priorytetem są ostatnie. Są one sortowane leksykograficznie według priorytetu.
4. Jeśli 2 węzły podrzędne mają ten sam priorytet (w tym brak priorytetu), są sortowane według klucza. Najpierw pojawiają się klucze numeryczne (posortowane numerycznie), a potem pozostałe klucze (posortowane leksykograficznie).

Więcej informacji o priorytetach znajdziesz w dokumentacji API.

Streaming z interfejsu REST API

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

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

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

W zamian serwer będzie wysyłać nazwane zdarzenia, gdy stan danych pod żądanym adresem URL ulegnie zmianie. 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 zewnętrzną otoczką interfejsów API REST i Streaming Firebase.