Pobieranie danych

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ę am :

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:

  1. Dzieci z wartością null dla określonego klucza podrzędnego są traktowane jako pierwsze.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Obiekty znajdują się na końcu i są sortowane leksykograficznie według kluczy w porządku rosnącym.
Przefiltrowane wyniki są zwracane w postaci nieuporządkowanej. Jeśli kolejność danych jest ważna, powinieneś posortować wyniki w aplikacji po ich zwróceniu z Firebase.

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.

  1. 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.
  2. 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.

  1. Dzieci bez priorytetu (domyślnie) są na pierwszym miejscu.
  2. Następne są dzieci, dla których priorytetem jest liczba. Są one sortowane numerycznie według priorytetu, od małych do dużych.
  3. Dzieci, dla których priorytetem jest sznurek, zajmują ostatnie miejsce. Są one posortowane leksykograficznie według priorytetu.
  4. 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:

  1. Ustaw nagłówek Accept klienta na text/event-stream
  2. Szanuj przekierowania HTTP, w szczególności kod 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 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.