Pobieram dane

Odczytywanie danych za pomocą GET

Możemy odczytywać dane z bazy danych Firebase, wysyłając żądanie GET do punktu końcowego adresu URL. Wróćmy do przykładu bloga z poprzedniej sekcji i sprawdźmy wszystkie dane z postu:

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

Pomyślne żądanie będzie sygnalizowane kodem stanu HTTP 200 OK, a odpowiedź będzie zawierać dane, które pobieramy.

Dodawanie parametrów identyfikatora URI

Interfejs REST API akceptuje kilka parametrów zapytań podczas odczytu danych z bazy danych Firebase. Poniżej znajdziesz listę najczęściej używanych parametrów. Pełną listę znajdziesz w przewodniku po interfejsie API REST.

uwierzytelnienie

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

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

drukuj

Podanie wartości print=pretty powoduje zwrócenie danych w formacie zrozumiałym dla człowieka.

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

Jeśli print=silent jest określone, w przypadku powodzenia zwraca wartość 204 No Content.

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

wywołanie zwrotne

Aby wykonywać wywołania REST z przeglądarki w różnych domenach, możesz użyć JSONP, aby opakować odpowiedź w funkcję wywołania zwrotnego JavaScript. Dodaj callback=, aby interfejs API REST opakował zwrócone dane we wskazanej 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łytki

Jest to zaawansowana funkcja, która ułatwia pracę z dużymi zbiorami danych bez konieczności pobierania wszystkiego. Aby go użyć, dodaj parametr shallow=true. Ograniczy to szczegółowość zwracanych danych. Jeśli dane w danym miejscu są typu podstawowego JSON (ciąg tekstowy, liczba lub wartość logiczna), zwrócona zostanie po prostu ich wartość. Jeśli zrzut danych w lokalizacji jest obiektem JSON, wartości każdego klucza zostaną obcięte do true. Na przykład:

{
  "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 na przykładzie prośby curl:

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

czas oczekiwania

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

Określ timeouts w tym formacie: 3ms, 3s lub 3min, z liczbą i jednostką. Jeśli nie podasz żadnej wartości, zostanie zastosowana maksymalna wartość timeout 15min. Jeśli timeout nie jest dodatnia lub przekracza maksymalną wartość, żądanie zostanie odrzucone z błędem HTTP 400. W tym przykładzie żądanie GET zawiera timeout o długoś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 mają być filtrowane dane, używając parametru orderBy. Następnie łączysz parametr orderBy z dowolnym z pozostałych 5 parametrów: limitToFirst, limitToLast, startAt, endAt i equalTo.

Ponieważ wszyscy w Firebase uważamy, że dinozaury są całkiem fajne, użyjemy fragmentu z przykładowej bazy danych faktów o tych dinozaurach, aby zademonstrować, 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, według klucza lub według wartości. Zapytanie zaczyna się od jednego z tych parametrów, a następnie musi być połączone z jednym lub kilkoma z tych parametrów: startAt, endAt, limitToFirst, limitToLast lub equalTo.

Filtrowanie według określonego klucza podrzędnego

Możemy filtrować węzły 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, wykonaj 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 przeprowadzamy filtrowanie, zostanie posortowany z wartością null. Szczegółowe informacje o tym, jak są sortowane dane, znajdziesz w artykule Sortowanie danych.

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 znajdujących się o jeden poziom niżej. Jest to przydatne, jeśli masz głęboko zagnieżdżone dane, np. takie:

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

Aby teraz zapytać o wysokość, użyjemy pełnej ścieżki do obiektu zamiast pojedynczego klucza:

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

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

Filtrowanie według klucza

Możemy też filtrować węzły według ich kluczy za pomocą parametru orderBy="$key". Poniższy przykład zwraca wszystkich dinozaurów o nazwie zaczynającej 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

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

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

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

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

W sekcji Sposób sortowania danych dowiesz się, jak są sortowane wartości null, wartości logiczne, ciągi znaków i obiekty podczas korzystania z orderBy="$value".

Filtrowanie złożone

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

Ogranicz zapytania

Parametry limitToFirst i limitToLast służą do określania maksymalnej liczby elementów podrzędnych, których dane mają być otrzymywane. Jeśli ustawimy limit na 100 wartości, otrzymamy maksymalnie 100 pasujących elementów podrzędnych. Jeśli w naszej bazie danych jest mniej niż 100 wiadomości, otrzymamy wszystkie dzieci. Jeśli jednak mamy ponad 100 wiadomości, otrzymamy dane tylko o 100 z nich. W przypadku funkcji limitToFirst będą to pierwsze 100 uporządkowanych wiadomości, a w przypadku funkcji limitToLast – ostatnie 100 uporządkowanych wiadomości.

Korzystając z naszej bazy danych o dinosaurach i z 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źć dwa najkrótsze dinozaury, używając funkcji limitToFirst:

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

Możemy również wykonywać zapytania dotyczące limitów za pomocą funkcji orderBy="$value". Jeśli chcemy utworzyć tabelę wyników z trzema najlepszymi zawodnikami w grze Dino Sports, możemy:

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

Zapytania dotyczące zakresów

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

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

Za pomocą endAt możemy znaleźć wszystkie dinozaury, których nazwy występują w alfabetycznym porządku przed nazwą Pterodactyl:

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. W tym przykładzie zostaną znalezione 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 dotyczące zakresów są też przydatne przy dzieleniu danych na strony.

Łączę wszystko w całość

Możemy łączyć te techniki, aby tworzyć złożone zapytania. Możesz na przykład wyszukać nazwy wszystkich dinozaurów o wzroście krótszym lub równym naszemu ulubionemu rodzajowi dinozaurowi (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"

W jaki sposób dane są porządkowane

W tej sekcji wyjaśniamy, jak są sortowane dane, gdy używasz 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 zostaną posortowane w ten sposób:

1. Najpierw są wybierane elementy podrzędne, dla których wartość atrybutu podrzędnego to null.
2. Następnie podawane są elementy podrzędne o 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 podawane są elementy podrzędne o 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 pojawiają się elementy z wartością liczbową, posortowane w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość numeryczną 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 alfabetycznie w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość w określonym węźle podrzędnym, są one uporządkowane alfabetycznie według klucza.
6. Obiekty znajdują się na końcu i są posortowane leksykograficznie według klucza w kolejności rosnącej.

orderBy="$key"

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

1. Najpierw wyświetlane są dzieci, których klucz można przeanalizować jako 32-bitową liczbę całkowitą, w porządku rosnącym.
2. Następne elementy podrzędne z wartością w postaci ciągu znaków są posortowane leksykograficznie w kolejności rosnącej.

orderBy="$value"

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

orderBy="$priority"

Gdy do sortowania danych używasz parametru orderBy="$priority", kolejność dzieci jest określana przez ich priorytet i klucz w następujący sposób: Pamiętaj, że wartości priorytetu mogą być tylko liczbami lub ciągami znaków.

1. Najpierw są wyświetlane dzieci bez priorytetu (domyślnie).
2. Następnie wyświetlane są dzieci z numerem priorytetu. Są one posortowane według priorytetu, od najmniejszego do największego.
3. Dzieci z ciągiem znaków jako priorytetem są wyświetlane na końcu. Są one sortowane leksykograficznie według priorytetu.
4. Gdy 2 elementy podrzędne mają ten sam priorytet (w tym brak priorytetu), są sortowane według klucza. Najpierw podawane są klucze liczbowe (posortowane według wartości liczbowej), a potem pozostałe klucze (posortowane alfabetycznie).

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

Transmisja strumieniowa z interfejsu API typu REST

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

Aby rozpocząć strumieniowe przesyłanie danych, wykonaj 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. Dołącz parametr zapytania auth, jeśli lokalizacja bazy danych Firebase wymaga uprawnienia do odczytu.

W zamian serwer będzie wysyłać nazwane zdarzenia, gdy stan danych pod podanym adresem URL będzie się zmieniać. 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 znajduje się przykładowy zestaw zdarzeń, które może wysyłać serwer:

// 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 interfejsem Firego, czyli zewnętrznym opakowaniem interfejsów API Firebase REST i Streaming.