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.

uwierzytelnienie

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'

Jeśli flaga debug tokena jest ustawiona, informacje do debugowania można znaleźć w nagłówku X-Firebase-Auth-Debug odpowiedzi.

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 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 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 tej 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 curlzapytanie:

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

shallow nie można używać z żadnym z parametrów zapytania „filtrowanie danych”.

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 pamięci podręcznej.

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.

Odfiltrowane dane są zwracane w nieokreślonej kolejności: gdy używasz interfejsu REST API, odfiltrowane wyniki są zwracane w nieokreślonej kolejności, ponieważ interpretery JSON nie wymuszają żadnej kolejności. Jeśli kolejność danych jest ważna, posortuj wyniki w aplikacji po ich zwróceniu z Firebase.

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 tych znajdujących się na jednym poziomie niżej. 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.

Dodaj indeksowanie do pliku Firebase Realtime Database Security Rules: jeśli w aplikacji używasz orderBy, musisz zdefiniować klucze, które będziesz indeksować, za pomocą reguły .indexOn w pliku Firebase Realtime Database Security Rules. Więcej informacji o regule .indexOn znajdziesz w dokumentacji.

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 orderBy="$value", znajdziesz w sekcji Jak są porządkowane dane.

Dodaj indeksowanie do Firebase Realtime Database Security Rules: jeśli w aplikacji używasz orderBy="$value", musisz dodać .value do reguł w odpowiednim indeksie. Więcej informacji o regule .indexOn znajdziesz w dokumentacji.

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 dotyczące 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 limity 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'

Za pomocą znaku 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'

Znaki startAt i endAt są włączające, co oznacza, że zapytanie powyżej będzie pasować do słowa „pterodactyl”.

Możemy połączyć startAt i endAt, aby ograniczyć obie strony zapytania. Poniższy przykład pozwala znaleźć 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'

Znak \uf8ff użyty w powyższym zapytaniu ma bardzo wysoki punkt kodowy w zakresie Unicode. Ponieważ w standardzie Unicode występuje po większości zwykłych znaków, zapytanie dopasowuje wszystkie wartości, które zaczynają się od litery „b”.

Zapytania zakresowe są też przydatne, gdy musisz podzielić dane na strony.

Podsumowanie

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 równe wysokością naszemu ulubionemu gatunkowi, 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.

Interfejs API REST zwraca nieposortowane wyniki: interpretery JSON nie wymuszają żadnego porządku w zbiorze wyników. orderBy można używać w połączeniu z startAt, endAt, limitToFirst lub limitToLast, aby zwracać podzbiór danych, ale zwrócone wyniki nie będą posortowane. Dlatego jeśli kolejność jest ważna, może być konieczne ręczne posortowanie wyników.

orderBy

Gdy używasz funkcji orderBy z nazwą klucza podrzędnego, dane zawierające określony klucz podrzędny są porzą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.

Odfiltrowane wyniki są zwracane w nieuporządkowanej kolejności. Jeśli kolejność danych jest ważna, posortuj wyniki w aplikacji po ich zwróceniu z Firebase.

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 wyświetlane są 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.

Priorytety liczbowe są przechowywane i porządkowane jako liczby zmiennoprzecinkowe podwójnej precyzji zgodne ze standardem IEEE 754. Klucze są zawsze przechowywane jako ciągi znaków i traktowane jako liczbowe tylko wtedy, gdy można je przeanalizować jako 32-bitową liczbę całkowitą.

1. Najpierw wyświetlane są elementy podrzędne bez priorytetu (domyślnego).
2. Następnie wyświetlane są 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 się zmieni. 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:

put	Dane zakodowane w formacie JSON będą obiektem z 2 kluczami: path i data. Klucz path wskazuje lokalizację względem adresu URL żądania. Klient powinien zastąpić wszystkie dane w tej lokalizacji w 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ę względem adresu URL żądania. W przypadku każdego klucza w danych klient powinien zastąpić odpowiedni klucz w pamięci podręcznej danymi dla tego klucza w wiadomości.
utrzymywanie aktywności	Dane tego zdarzenia mają wartość null, nie musisz nic robić
anuluj	Dane tego zdarzenia mają wartość null. To zdarzenie zostanie wysłane, jeśli Firebase Realtime Database Security Rules spowoduje, że odczyt w żądanej lokalizacji nie będzie już dozwolony.
auth_revoked	Dane tego zdarzenia to ciąg znaków wskazujący, że dane logowania utraciły ważność. To zdarzenie zostanie wysłane, gdy podany parametr autoryzacji nie będzie już ważny.

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.