Odczyt danych za pomocą GET
Możemy odczytać dane z naszej bazy danych Firebase, wysyłając żądanie GET
do punktu końcowego adresu URL. Kontynuujmy nasz przykładowy blog z poprzedniej sekcji i przeczytajmy wszystkie dane z naszych postów na blogu:
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
Pomyślne żądanie zostanie oznaczone kodem stanu HTTP 200 OK
, a odpowiedź będzie zawierać dane, które pobieramy.
Dodawanie parametrów URI
Interfejs API REST akceptuje kilka parametrów zapytań podczas odczytu danych z naszej bazy danych Firebase. Poniżej wymieniono najczęściej używane parametry. Pełną listę można znaleźć w dokumencie REST API Reference .
autoryzacja
Parametr żądania auth
umożliwia dostęp do danych chronionych regułami bezpieczeństwa bazy danych Firebase Realtime i jest obsługiwany przez wszystkie typy żądań. Argumentem może być klucz tajny aplikacji Firebase lub token uwierzytelniający, zgodnie z opisem w sekcji Użytkownicy w projektach Firebase . W poniższym przykładzie wysyłamy żądanie GET
z parametrem auth
, gdzie CREDENTIAL
jest albo sekretem Twojej aplikacji Firebase, albo tokenem uwierzytelniającym:
curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'
wydrukować
Określenie print=pretty
zwraca dane w formacie czytelnym dla człowieka.
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'
Określenie print=silent
zwraca w przypadku powodzenia błąd 204 No Content
.
curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'
oddzwonić
Aby wykonywać wywołania REST z przeglądarki internetowej w różnych domenach, możesz użyć JSONP do zawinięcia odpowiedzi w funkcję wywołania zwrotnego JavaScript. Dodaj callback=
, aby interfejs API REST zawinął zwrócone dane w określoną funkcję wywołania zwrotnego. Na 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 zaprojektowana, aby pomóc Ci pracować z dużymi zbiorami danych bez konieczności pobierania wszystkiego. Aby z niego skorzystać, dodaj parametr shallow=true
. Ograniczy to głębokość zwracanych danych. Jeśli dane w lokalizacji są danymi pierwotnymi JSON (łańcuch, liczba lub wartość logiczna), ich wartość zostanie po prostu zwrócona. Jeśli migawka danych w tej lokalizacji jest obiektem JSON, wartości każdego klucza zostaną obcięte do wartości true . Na przykład, korzystając z poniższych 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 za pomocą tego żądania curl
:
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'
koniec czasu
Użyj tej opcji, aby ograniczyć czas odczytu po stronie serwera. Jeśli żądanie odczytu nie zakończy się w wyznaczonym czasie, zakończy się 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
używając następującego formatu: 3ms
, 3s
lub 3min
, z liczbą i jednostką. Jeśli nie zostanie określony, zastosowany zostanie maksymalny timeout
wynoszący 15min
. Jeśli timeout
nie będzie dodatni lub przekroczy wartość maksymalną, żądanie zostanie odrzucone z powodu błędu HTTP 400. W poniższym przykładzie żądanie GET
obejmuje timeout
wynoszący 10 sekund.
curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'
Filtrowanie danych
Możemy konstruować zapytania, aby filtrować dane na podstawie różnych czynników. Na początek określasz sposób filtrowania danych za pomocą parametru orderBy
. Następnie łączysz orderBy
z dowolnym z pozostałych pięciu parametrów: limitToFirst
, limitToLast
, startAt
, endAt
i equalTo
.
Ponieważ wszyscy w Firebase uważamy, że dinozaury są całkiem fajne, użyjemy fragmentu przykładowej bazy danych zawierającej fakty o dinozaurach, aby zademonstrować, w jaki sposób można filtrować dane:
{ "lambeosaurus": { "height": 2.1, "length": 12.5, "weight": 5000 }, "stegosaurus": { "height": 4, "length": 9, "weight": 2500 } }
Możemy filtrować dane na jeden z trzech sposobów: według klucza podrzędnego , według klucza lub według wartości . Zapytanie rozpoczyna się od jednego z tych parametrów, a następnie musi zostać połączone z co najmniej jednym z następujących 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
. Na przykład, aby odzyskać wszystkie dinozaury o wysokości większej niż 3, możemy wykonać następujące 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
. Aby uzyskać szczegółowe informacje na temat uporządkowania danych, zobacz temat Jak uporządkowane są dane .
Firebase obsługuje również zapytania uporządkowane przez głęboko zagnieżdżone elementy podrzędne, a nie tylko podrzędne o jeden poziom niżej. Jest to przydatne, jeśli masz głęboko zagnieżdżone dane, takie jak to:
{ "lambeosaurus": { "dimensions": { "height" : 2.1, "length" : 12.5, "weight": 5000 } }, "stegosaurus": { "dimensions": { "height" : 4, "length" : 9, "weight" : 2500 } } }
Aby teraz zapytać 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ą być filtrowane tylko według jednego klucza na raz. Wielokrotne użycie parametru orderBy
w tym samym żądaniu powoduje błąd.
Filtrowanie według klucza
Możemy także filtrować węzły według ich kluczy za pomocą parametru orderBy="$key"
. Poniższy przykład pobiera wszystkie dinozaury o nazwach zaczynających się na literę a
– m
:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'
Filtrowanie według wartości
Możemy filtrować węzły według wartości ich kluczy podrzędnych za pomocą parametru orderBy="$value"
. Załóżmy, że dinozaury biorą udział w zawodach sportowych dinozaurów i śledzimy ich wyniki w następującym formacie:
{ "scores": { "bruhathkayosaurus": 55, "lambeosaurus": 21, "linhenykus": 80, "pterodactyl": 93, "stegosaurus": 5, "triceratops": 22 } }
Aby odzyskać wszystkie dinozaury z wynikiem wyższym niż 50, możemy złożyć następującą prośbę:
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'
Zobacz Jak uporządkowane są dane , aby uzyskać wyjaśnienie sposobu sortowania wartości null
, boolean, string i obiektu przy użyciu orderBy="$value"
.
Złożone filtrowanie
Możemy łączyć wiele parametrów, aby konstruować bardziej złożone zapytania.
Ogranicz zapytania
Parametry limitToFirst
i limitToLast
służą do ustawienia maksymalnej liczby dzieci, dla których mają być odbierane dane. Jeśli ustalimy limit 100, otrzymamy maksymalnie 100 pasujących dzieci. Jeżeli w naszej bazie danych mamy mniej niż 100 wiadomości, otrzymamy każde dziecko. Jeśli jednak będziemy mieć 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 naszej bazy danych o dinozaurach i orderBy
, możemy znaleźć dwa 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 limitToFirst
:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'
Możemy również przeprowadzać zapytania ograniczające za pomocą orderBy="$value"
. Jeśli chcemy stworzyć tabelę liderów składającą się z trzech najlepszych zawodników Dino Sports, możemy wykonać następujące czynności:
curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'
Zapytania o zakres
Użycie startAt
, endAt
i equalTo
pozwala nam wybrać dowolny punkt początkowy i końcowy naszych zapytań. Na przykład, jeśli chcemy znaleźć wszystkie dinozaury, które mają co najmniej trzy metry wzrostu, 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ć endAt
, aby znaleźć wszystkie dinozaury, których nazwy leksykograficznie występują przed Pterodaktylem:
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 naszego zapytania. Poniższy przykład wyszukuje wszystkie dinozaury, których nazwa zaczyna się na literę „b”:
curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'
Zapytania o zakres są również przydatne, gdy trzeba paginować dane.
Kładąc wszystko razem
Możemy łączyć wszystkie te techniki, aby tworzyć złożone zapytania. Na przykład, może chcesz znaleźć nazwy wszystkich dinozaurów, które są krótsze lub równe naszemu ulubionemu gatunkowi, 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 dane są uporządkowane
W tej sekcji wyjaśniono, w jaki sposób uporządkowane są dane przy użyciu każdego z trzech parametrów filtrowania.
Zamów przez
W przypadku użycia orderBy
z nazwą klucza podrzędnego dane zawierające określony klucz podrzędny zostaną uporządkowane w następujący sposób:
- Dzieci z wartością
null
dla określonego klucza podrzędnego są traktowane jako pierwsze. - Następne są dzieci z wartością
false
dla określonego klucza podrzędnego. Jeśli wiele elementów podrzędnych ma wartośćfalse
, są one sortowane leksykograficznie według klucza. - Następne są dzieci z wartością
true
dla określonego klucza podrzędnego. Jeśli wiele elementów podrzędnych ma wartośćtrue
, są one sortowane leksykograficznie według klucza. - Następne są dzieci z wartością liczbową, posortowane w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość liczbową dla określonego węzła podrzędnego, są one sortowane według klucza.
- Ciągi znaków występują po liczbach i są sortowane leksykograficznie w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość dla określonego węzła podrzędnego, są one uporządkowane leksykograficznie według klucza.
- Obiekty znajdują się na końcu i są sortowane leksykograficznie według kluczy w porządku rosnącym.
zamówienieBy="$key"
W przypadku użycia parametru orderBy="$key"
do sortowania danych, dane zostaną zwrócone w kolejności rosnącej według klucza w następujący sposób. Pamiętaj, że klucze mogą być tylko ciągami znaków.
- Na pierwszym miejscu znajdują się dzieci z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, posortowane w kolejności rosnącej.
- Następne są dzieci, których kluczem jest wartość ciągu, posortowane leksykograficznie w kolejności rosnącej.
zamówienieBy="$wartość"
Jeśli do sortowania danych użyjesz parametru orderBy="$value"
, elementy podrzędne zostaną uporządkowane według ich wartości. Kryteria porządkowania są takie same, jak dane uporządkowane według klucza podrzędnego, z tą różnicą, że zamiast wartości określonego klucza podrzędnego używana jest wartość węzła.
zamówienieBy="$priorytet"
W przypadku użycia parametru orderBy="$priority"
do sortowania danych kolejność elementów podrzędnych jest określana na podstawie ich priorytetu i klucza w następujący sposób. Należy pamiętać, że wartościami priorytetu mogą być tylko liczby lub ciągi znaków.
- Dzieci bez priorytetu (domyślnie) są na pierwszym miejscu.
- Następne są dzieci, dla których priorytetem jest liczba. Są one sortowane numerycznie według priorytetu, od małych do dużych.
- Dzieci, dla których priorytetem jest sznurek, zajmują ostatnie miejsce. Są one posortowane leksykograficznie według priorytetu.
- Jeśli dwoje dzieci ma ten sam priorytet (w tym brak priorytetu), są one sortowane według klucza. Na pierwszym miejscu znajdują się klawisze numeryczne (posortowane numerycznie), po których następują pozostałe klawisze (posortowane leksykograficznie).
Więcej informacji na temat priorytetów można znaleźć w dokumentacji API .
Przesyłanie strumieniowe z interfejsu API REST
Punkty końcowe Firebase REST obsługują protokół EventSource / Server-Sent Events , dzięki czemu można łatwo przesyłać strumieniowo zmiany do jednej lokalizacji w naszej bazie danych Firebase.
Aby rozpocząć przesyłanie strumieniowe, musimy wykonać następujące czynności:
- Ustaw nagłówek Accept klienta na
text/event-stream
- Szanuj przekierowania HTTP, w szczególności kod stanu HTTP 307
- Dołącz parametr zapytania
auth
, jeśli lokalizacja bazy danych Firebase wymaga uprawnień do odczytu
W zamian serwer będzie wysyłał nazwane zdarzenia w miarę zmian stanu danych pod żądanym adresem URL. Struktura tych komunikatów jest zgodna z protokołem EventSource:
event: event name data: JSON encoded data payload
Serwer może wysyłać następujące zdarzenia:
umieścić | Dane zakodowane w JSON będą obiektem z dwoma kluczami: path i data Ścieżka wskazuje lokalizację związaną z adresem URL żądania Klient powinien zastąpić wszystkie dane znajdujące się w tej lokalizacji w swojej pamięci podręcznej danymi podanymi w komunikacie |
skrawek | Dane zakodowane w JSON będą obiektem z dwoma kluczami: path i data Ścieżka wskazuje lokalizację związaną z adresem URL żądania Dla każdego klucza w danych klient powinien zastąpić odpowiedni klucz w swojej pamięci podręcznej danymi dla tego klucza w komunikacie |
utrzymać przy życiu | Dane tego zdarzenia mają wartość null i nie jest wymagane żadne działanie |
anulować | Dane tego zdarzenia mają wartość null To zdarzenie zostanie wysłane, jeśli reguły bezpieczeństwa bazy danych Firebase Realtime powodują, że odczyt w żądanej lokalizacji nie jest już dozwolony |
uwierzytelnienie_odwołane | Dane dla tego zdarzenia to ciąg znaków wskazujący, że poświadczenie wygasło To zdarzenie zostanie wysłane, gdy podany parametr auth przestanie być ważny |
Poniżej znajduje się 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, wypróbuj Firego , opakowanie innej firmy obsługujące interfejsy API REST i Streaming API Firebase.