Pobieranie danych

Odczyt danych za pomocą GET

Możemy odczytywać dane z naszej bazy danych Firebase, wysyłając żądanie GET do jej punktu końcowego adresu URL. Kontynuujmy nasz przykład na blogu z poprzedniej sekcji i przeczytajmy wszystkie dane z naszych postów na blogu:

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

Udane żą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 czasu rzeczywistego Firebase 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 kluczem tajnym aplikacji Firebase lub 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 204 No Content w przypadku sukcesu.

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 go użyć, dodaj parametr shallow=true . Ograniczy to głębokość zwracanych danych. Jeśli dane w lokalizacji są prymitywami JSON (łańcuch znaków, liczba lub wartość logiczna), ich wartość zostanie po prostu zwrócona. Jeśli migawka danych w lokalizacji jest obiektem JSON, wartości dla każdego klucza zostaną obcięte do 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 tego, aby ograniczyć czas potrzebny na odczyt 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 oczekujesz niewielkiego transferu danych i nie chcesz czekać zbyt długo na pobranie potencjalnie ogromnego 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 , podając liczbę i jednostkę. Jeśli nie zostanie określony, zastosowany zostanie maksymalny timeout wynoszący 15min . Jeśli timeout nie jest dodatni lub przekracza wartość maksymalną, żądanie zostanie odrzucone z błędem HTTP 400. W poniższym przykładzie żądanie GET zawiera timeout wynoszący 10 sekund.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

Filtrowanie danych

Możemy konstruować zapytania do filtrowania danych na podstawie różnych czynników. Aby rozpocząć, określ 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 faktów o dinozaurach, aby zademonstrować, jak 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 potomnego , 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 większą liczbą 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 potomnego, 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, który filtrujemy, zostanie posortowany z wartością null . Aby uzyskać szczegółowe informacje na temat porządkowania danych, zobacz Jak uporządkowane są dane .

Firebase obsługuje również zapytania uporządkowane przez głęboko zagnieżdżone dzieci, a nie tylko dzieci o jeden poziom 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 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 naraz. Wielokrotne użycie parametru orderBy w tym samym żądaniu spowoduje zgłoszenie błędu.

Filtrowanie według klucza

Możemy również filtrować węzły według ich kluczy za pomocą parametru orderBy="$key" . Poniższy przykład pobiera 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

Możemy filtrować węzły według wartości ich kluczy potomnych za pomocą parametru orderBy="$value" . Załóżmy, że dinozaury organizują zawody sportowe dinozaurów, a my ś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 wykonać następujące żądanie:

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

Zobacz Jak uporządkowane są dane , aby uzyskać wyjaśnienie, w jaki sposób wartości null , boolean, string i object są sortowane 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 elementów podrzędnych, dla których mają zostać odebrane dane. Jeśli ustalimy limit 100, otrzymamy tylko do 100 pasujących dzieci. Jeśli w naszej bazie mamy mniej niż 100 wiadomości, otrzymamy każde dziecko. Jeśli jednak mamy 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 faktów 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 o limit za pomocą orderBy="$value" . Jeśli chcemy stworzyć tabelę liderów z trzema najlepszymi zawodnikami dinosportowymi, 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żywanie startAt , endAt i equalTo pozwala nam wybrać dowolne punkty początkowe i końcowe dla naszych zapytań. Na przykład, gdybyśmy chcieli znaleźć wszystkie dinozaury, które mają co najmniej trzy metry wysokości, 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 występują leksykograficznie 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 znajduje 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 podzielić dane na strony.

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ą niższe lub równe naszemu ulubionemu rodzajowi, 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 uporządkowane są dane

W tej sekcji wyjaśniono, w jaki sposób uporządkowane są dane podczas korzystania z 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ą na pierwszym miejscu.
2. Dzieci z wartością false dla określonego klucza potomnego są następne. Jeśli wiele elementów podrzędnych ma wartość false , są one sortowane leksykograficznie według klucza.
3. Dzieci z wartością true dla określonego klucza podrzędnego są następne. 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 rosnąco. 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 występują po liczbach i są sortowane leksykograficznie w porządku rosnącym. 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 są na końcu i są sortowane leksykograficznie według klucza w porządku rosnącym.

orderBy="$ klucz"

W przypadku użycia parametru orderBy="$key" do sortowania danych dane zostaną zwrócone w porządku rosnącym według klucza w następujący sposób. Pamiętaj, że klucze mogą być tylko łańcuchami.

1. Dzieci z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, są pierwsze, posortowane w porządku rosnącym.
2. Dzieci z wartością ciągu jako kluczem są następne, posortowane leksykograficznie w porządku rosnącym.

orderBy="$wartość"

Gdy używasz parametru orderBy="$value" do sortowania danych, 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 wyjątkiem tego, że zamiast wartości określonego klucza podrzędnego używana jest wartość węzła.

orderBy="$priorytet"

Gdy używasz 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. Pamiętaj, że wartościami priorytetów mogą być tylko liczby lub ciągi znaków.

1. Dzieci bez priorytetu (domyślnie) mają pierwszeństwo.
2. Dzieci, których priorytetem jest liczba, są następne. Są one sortowane numerycznie według priorytetu, od małych do dużych.
3. Dzieci, których priorytetem jest sznurek, zajmują ostatnie miejsce. Są one sortowane leksykograficznie według priorytetu.
4. Ilekroć dwoje dzieci ma ten sam priorytet (w tym brak priorytetu), są one sortowane według klucza. Najpierw są klawisze numeryczne (posortowane numerycznie), a następnie pozostałe klucze (posortowane leksykograficznie).

Aby uzyskać więcej informacji na temat priorytetów, zobacz informacje o interfejsie API .

Przesyłanie strumieniowe z interfejsu API REST

Punkty końcowe Firebase REST obsługują protokół EventSource / Server-Sent Events , co ułatwia strumieniowe przesyłanie zmian do pojedynczej 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 wyśle ​​nazwane zdarzenia, gdy zmieni się stan 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 wysłać następujące zdarzenia:

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 wokół interfejsów Firebase REST i Streaming API.