Pobieram dane

Odczytywanie danych za pomocą GET

Dane z naszej bazy danych Firebase możemy odczytać, wysyłając do niej żą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 zapytania podczas odczytu danych z naszej 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 auth umożliwia dostęp do danych chronionych przez Firebase Realtime Database Security Rules i jest obsługiwany przez wszystkie typy żądań. Argument może być tajnym kluczem aplikacji Firebase lub tokenem uwierzytelniającym, jak opisano 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'

W przypadku powodzenia parametr print=silent 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 REST API owi zawinął zwracane 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ł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. Spowoduje to ograniczenie głębokości zwracanych danych. Jeśli dane w danym miejscu są typu JSON (string, liczba lub wartość logiczna), zwrócona zostanie ich wartość. Jeśli w danym miejscu znajduje się migawka danych w postaci obiektu 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 wykorzystywania pamięci podręcznej.

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 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 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 orderBy z dowolnym z pozostałych 5 parametrów: limitToFirst, limitToLast, startAt, endAt i equalTo.

Ponieważ wszyscy w Firebase uważamy dinozaury za fajne, użyjemy fragmentu przykładowej bazy danych z informacjami o dinosaurach, 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, 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 na 1 poziomie. 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 i śledzimy ich wyniki w takim formacie: 

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

Aby pobrać wszystkie dinozaury z wynikiem wyższym niż 50, możemy przesłać takie żą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, wartości logiczne, ciągi tekstowe i wartości obiektów podczas korzystania z funkcji orderBy="$value", znajdziesz w artykule Uporządkowanie danych.

Filtrowanie złożone

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

Limit zapytań

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źć 2 najkrótsze dinozaury, używając zapytania limitToFirst: 

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

Możemy też przeprowadzać zapytania z ograniczonym zakresem 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 zakresu

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 zakresowe są też przydatne, gdy chcesz podzielić dane na strony.

Łączę wszystko w całość

Możemy łączyć te techniki, aby tworzyć złożone zapytania. Możesz na przykład chcieć znaleźć nazwy wszystkich dinozaurów, które są niższe lub równe wzrostem naszemu ulubieńcowi – 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"

Sposób sortowania danych

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 wiele elementów podrzędnych ma wartość false, są one sortowane alfabetycznie według klucza.
  3. Następnie podawane są elementy podrzędne o wartości true dla określonego klucza podrzędnego. Jeśli wiele elementów podrzędnych ma wartość true, są one sortowane alfabetycznie 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.
Odfiltrowane wyniki są zwracane bez określonej kolejności. Jeśli kolejność danych ma znaczenie, po otrzymaniu danych z Firebase musisz je posortować w aplikacji.

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 kolejności rosnącej.
  2. Następnie występują elementy podrzędne z wartością ciągu znaków jako kluczem, 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 alfabetycznie według priorytetu.
  4. Gdy 2 elementy podrzędne mają ten sam priorytet (w tym brak priorytetu), są one 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.

Odtwarzanie strumieniowe 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 komunikatów jest zgodna z protokołem EventSource: 

event: event name
data: JSON encoded data payload

Serwer może wysyłać te zdarzenia:

put Dane zakodowane w formacie JSON będą obiektem z 2 kluczami: path i data.
Ścieżka wskazuje lokalizację w stosunku do adresu URL żądania.
Klient powinien zastąpić wszystkie dane w tej lokalizacji w swojej pamięci podręcznej danymi podanymi w wiadomości.
patch Dane zakodowane w formacie JSON będą obiektem z 2 kluczami: path i data.
Ścieżka wskazuje lokalizację w stosunku do adresu URL żądania.
W przypadku każdego klucza w danych klient powinien zastąpić odpowiadający mu klucz w swojej pamięci podręcznej danymi tego klucza w wiadomości.
utrzymywanie aktywności Dane tego zdarzenia są puste, nie musisz nic robić
anuluj Dane tego zdarzenia są puste
To zdarzenie zostanie wysłane, jeśli Firebase Realtime Database Security Rules spowoduje, że odczyt w wymaganej lokalizacji nie będzie już dozwolony.
auth_revoked Dane tego zdarzenia to ciąg znaków wskazujący, że dane uwierzytelniające utraciły ważność.
To zdarzenie zostanie wysłane, gdy podany parametr uwierzytelniania nie będzie już ważny.

Poniżej znajdziesz 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.