Interfejs API typu REST bazy danych Firebase

Wykorzystanie interfejsu API

Jako punktu końcowego REST możesz użyć dowolnego adresu URL Bazy danych czasu rzeczywistego Firebase. Wszystko, czego potrzebujesz należy dodać .json na końcu adresu URL i wysłać żądanie z Twojego ulubionego klienta HTTPS.

Wymagany jest protokół HTTPS. Firebase odpowiada tylko na zaszyfrowany ruch, więc Twoje dane są bezpieczne.

GET – odczytywanie danych

Dane z urządzenia Realtime Database można odczytać, wysyłając żądanie HTTP GET do punktu końcowego. Przykład poniżej pokazuje, jak można pobrać dane użytkownika nazwę zapisaną wcześniej w usłudze Realtime Database. 

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Udane żądanie jest sygnalizowane przez HTTP 200 OK kodu stanu. Odpowiedź zawiera dane powiązane z parametrem w żądaniu GET. 

{ "first": "Jack", "last": "Sparrow" }

PUT – Zapisywanie danych

Dane można zapisywać za pomocą żądania PUT. 

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Udane żądanie jest sygnalizowane przez HTTP 200 OK kodu stanu. Odpowiedź zawiera dane określone w tagu Prośba o: PUT. 

{ "first": "Jack", "last": "Sparrow" }

POST – przekazywanie danych

Aby uzyskać odpowiednik JavaScriptu push() (patrz Listy danych), możesz wysłać prośbę POST. 

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

Udane żądanie jest sygnalizowane stanem HTTP 200 OK w kodzie. Odpowiedź zawiera nazwę podrzędną nowych danych określone w żądaniu POST. 

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH – Aktualizowanie danych

Możesz zaktualizować elementy podrzędne w lokalizacji bez zastępowania ich dotychczasowe dane za pomocą żądania PATCH. Dzieci otrzymały imiona dane zapisywane za pomocą funkcji PATCH są zastępowane, ale są pomijane elementy podrzędne nie są usuwane. Jest to odpowiednik JavaScriptu update(). 

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

Udane żądanie jest sygnalizowane stanem HTTP 200 OK w kodzie. Odpowiedź zawiera dane określone w tagu Prośba o: PATCH. 

{ "last": "Jones" }

USUŃ – usuwanie danych

Jeśli chcesz usunąć dane, wyślij prośbę DELETE: 

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Udane żądanie DELETE jest wskazywane przez Kod stanu HTTP 200 OK z odpowiedzią zawierającą JSON null

Zastąpienie metody

Jeśli wykonujesz wywołania REST w przeglądarce, która nie obsługuje poprzednich metod, możesz zastąpić metodę żądania, tworząc POST żądanie i ustawianie metody za pomocą funkcji w nagłówku żądania X-HTTP-Method-Override. 

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Możesz też użyć parametru zapytania x-http-method-override. 

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

Żądania warunkowe

Żądania warunkowe, będące odpowiednikiem operacji transakcji pakietu SDK REST, aktualizują dane zgodnie z określony warunek. Zapoznaj się z omówieniem przepływu pracy i dowiedz się więcej o żądaniach warunkowych dla REST w sekcji Zapisywanie danych.

ETag Firebase

ETag Firebase to unikalny identyfikator bieżących danych w określonej lokalizacji. Jeśli lub inne dane, zmienia się też tag ETag. Tag ETag Firebase należy określić w sekcji w nagłówku początkowego żądania REST (zwykle jest to GET, ale może być cokolwiek innego niż PATCH). 

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

jeśli-dopasowanie

Warunek if-match określa wartość ETag danych, które chcesz zaktualizować. Jeśli użyjesz warunku, Realtime Database realizuje tylko żądania, w których przypadku tag ETag określony w parametrze żądanie zapisu pasuje do ETag istniejących danych w bazie danych. Pobierz ETag w lokalizacji z żądaniem ETag Firebase. Jeśli chcesz zastąpić dowolną lokalizację null, użyj null_etag.

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

Oczekiwane odpowiedzi

W tabeli poniżej znajdziesz przegląd oczekiwanych odpowiedzi w przypadku poszczególnych typów żądań: na podstawie dopasowania ETag.

Typ wniosku „X-Firebase-ETag: true” ETag pasuje do
if_match: <matching etag>		 ETag nie pasuje do
if_match: <no matching etag>
POBIERZ Stan i treść odpowiedzi 200: "<ścieżka_danych>" 400: „...nieobsługiwany..” 400: „...nieobsługiwany..”
Dodane nagłówki ETag: <ETag_danych> Nie dotyczy Nie dotyczy
UDERZENIE Stan i treść odpowiedzi 200: „<dane_danych>” 200: „<dane_danych>” 412: „...Niezgodność tagów..”
Dodane nagłówki ETag: <ETag_of_put_data>, Nie dotyczy ETag: <baza_danych_ETag>
POST Stan i treść odpowiedzi 200: „<dane_postów>” 400: „...nieobsługiwany..” 400: „...nieobsługiwany..”
Dodane nagłówki ETag: <ETag_of_post_data> Nie dotyczy Nie dotyczy
WERSJA Stan i treść odpowiedzi 400: „...nieobsługiwany..” 400: „...nieobsługiwany..” 400: „...nieobsługiwany..”
Dodane nagłówki Nie dotyczy Nie dotyczy Nie dotyczy
USUŃ Stan i treść odpowiedzi 200: wartość null 200: „<data_after_put>” 412: „...Niezgodność tagów..”
Dodane nagłówki ETag: <ETag_of_null> Nie dotyczy ETag: <baza_danych_ETag>

Parametry zapytania

Interfejs API typu REST bazy danych Firebase akceptuje poniższe parametry zapytania i wartości:

access_token

Obsługiwane przez wszystkie typy żądań. Uwierzytelnia to żądanie, aby zezwolić na dostępu do danych chronionych przez Firebase Realtime Database Security Rules. Zobacz dokumentacji uwierzytelniania REST. 

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

płytka

To zaawansowana funkcja zaprojektowana do pracy z dużymi na zbiorach danych bez konieczności pobierania wszystkiego. Ustaw na true, aby ograniczyć szczegółowość zwracanych danych w danym miejscu. Jeśli dane w lokalizacji są obiektem podstawowym JSON (ciąg znaków, liczba lub wartość logiczna), jego wartość zostanie po prostu zwrócona. Jeśli zrzut danych w tej lokalizacji jest obiektem JSON, wartości każdego klucza zostaną skrócone do true.

Argumenty Metody REST Opis
płytki POBIERZ Ogranicz złożoność odpowiedzi. 
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Pamiętaj, że zapytania shallow nie można łączyć z żadnym innym zapytaniem. .

drukuj

Formatuje dane zwrócone z serwera w odpowiedzi.

Argumenty Metody REST Opis
ładne GET, PUT, POST, PATCH, DELETE Wyświetl dane w formacie zrozumiałym dla człowieka.
ciche GET, PUT, POST, PATCH Służy do blokowania danych wyjściowych serwera podczas zapisywania danych. Otrzymana odpowiedź będzie pusta i oznaczona symbolem kod stanu HTTP 204 No Content. 
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

wywołanie zwrotne

Obsługiwane tylko przez GET. Wykonywanie wywołań REST w przeglądarce między domenami, możesz użyć formatu JSONP, aby opakować odpowiedź w kodzie JavaScript funkcji wywołania zwrotnego. Dodaj callback=, aby opakować interfejs API REST zwrócone dane w określonej funkcji wywołania zwrotnego. 

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

format

Jeśli ustawisz wartość export, serwer zakoduje priorytety w .

Argumenty Metody REST Opis
eksport POBIERZ Umieść w odpowiedzi informacje o priorytecie. 
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

pobierz

Obsługiwane tylko przez GET. Jeśli chcesz wywołać plik pobierz swoje dane z przeglądarki, dodaj download=. Powoduje to, że usługa REST dodaje odpowiednie nagłówki, że przeglądarki muszą zapisać dane w pliku. 

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

czas oczekiwania

Służy do ograniczania czasu odczytu po stronie serwera. Jeśli odczyt nie kończy się w wyznaczonym czasie i kończy się żądaniem HTTP Błąd 400. Jest to szczególnie przydatne, gdy spodziewasz się niewielkiego przeniesienia danych i nie chcemy zbyt długo czekać, aż zdobędziecie potencjalnie ogromne poddrzewo. Rzeczywista czas odczytu może się różnić w zależności od rozmiaru danych i pamięci podręcznej.

Podaj wartość timeouts w tym formacie: 3ms, 3s lub 3min z liczbą i jednostką. Jeśli nie, wartość maksymalna timeout z 15min wynosi zastosowano. Jeśli timeout nie jest liczbą dodatnią lub przekracza wartość maksymalną, Żądanie zostanie odrzucone z powodu błędu HTTP 400.

Limit wielkości zapisu

Aby ograniczyć rozmiar zapisu, może określić parametr zapytania writeSizeLimit jako tiny (cel=1 s), small (cel=10 s), medium (cel=30 s), large (cel=60 s). Baza danych czasu rzeczywistego szacuje rozmiar każdego żądania zapisu i przerywa żądań, które trwają dłużej niż czas docelowy.

Jeśli wybierzesz unlimited, bardzo duże zapisy (do 256 MB ładunku) są dozwolone, co może blokować kolejne żądania, gdy baza danych przetwarza podczas wykonywania bieżącej operacji. Nie można anulować zapisów po dotarciu do serwera. 

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

Jeśli zapis jest zbyt duży, zobaczysz ten komunikat o błędzie: 

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

Dodatkowo możesz ustawić defaultWriteSizeLimit dla całej bazy danych. za pomocą interfejsu wiersza poleceń Firebase. Ten limit dotyczy wszystkich żądań, w tym żądań z pakietów SDK. Tworzone są nowe bazy danych z wartością defaultWriteSizeLimit ustawioną na large. Nie możesz ustawić wartości defaultWriteSizeLimit na tiny za pomocą interfejsu wiersza poleceń Firebase. 

firebase database:settings:set defaultWriteSizeLimit large

orderBy

Zapoznaj się z sekcją przewodnika dotyczącą uporządkowane dane .

limitToFirst, limitToLast, startAt, endAt, równeTo

Zapoznaj się z sekcją przewodnika dotyczącą filtrowania danych dla znajdziesz więcej informacji.

Strumieniowe przesyłanie z interfejsu API REST

Punkty końcowe Firebase REST obsługują EventSource / zdarzenia wysłane przez serwer protokołu. Aby przesyłać strumieniowo zmiany do jednej lokalizacji na koncie Realtime Database, musisz wykonać kilka czynności:

  • Ustaw nagłówek Accept klienta na "text/event-stream"
  • Przestrzegaj przekierowań HTTP, a w szczególności kodu stanu HTTP 307
  • Jeśli lokalizacja wymaga uprawnień do odczytu, musisz dołączyć parametr Parametr auth

Z kolei serwer będzie wysyłać nazwane zdarzenia jako stan danych w żądany adres URL ulegnie zmianie. Struktura tych wiadomości jest zgodna z protokół EventSource. 

event: event name
data: JSON encoded data payload

Serwer może wysyłać te zdarzenia:

Włącz

Dane zakodowane w formacie JSON to obiekt z 2 kluczami: path i danych. Ścieżka w stosunku do adresu URL z żądania. Klient powinien zastąpić wszystkie z tych dane w tej lokalizacji w pamięci podręcznej razem z atrybutem data.

patch

Dane zakodowane w formacie JSON to obiekt z 2 kluczami: path i danych. Ścieżka w stosunku do adresu URL z żądania. Dla każdego klucza w data, klient powinien zastąpić odpowiadającym kluczowi w jego pamięci podręcznej z danymi tego klucza z wiadomości.

utrzymywanie aktywności

Dane tego zdarzenia: null. Nie musisz podejmować żadnych działań.

anuluj

Niektóre nieoczekiwane błędy mogą wysłać zdarzenie „cancel” (anulowanie) i zakończyć połączenie. Przyczyna jest opisana w danych dostarczonych dla tego zdarzenia. Niektóre potencjalne przyczyny następujące: 1. Firebase Realtime Database Security Rules nie zezwala już na odczyt w żądanej lokalizacji. Opis „dane” tej przyczyny to „Odmowa dostępu”. 2. Zapis aktywował transmisję strumieniową zdarzeń, która wysłała duże drzewo JSON, które przekracza nasz limit. 512MB. „Dane” z tej przyczyny to „Określony ładunek jest zbyt duży. Poproś o o lokalizacji z mniejszą ilością danych”.

unieważnienie autoryzacji

Dane tego zdarzenia to ciąg znaków wskazujący, że dane logowania wygasła. To zdarzenie jest wysyłane, gdy podany element auth jest już nieważny.

Oto 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}}

Priorytety

Do informacji o priorytecie lokalizacji można się odwołać za pomocą „wirtualne dziecko” o nazwie .priority. Priorytety możesz odczytać w następujący sposób: Żądania typu GET i zapisz je w żądaniach typu PUT. Na przykład to żądanie pobiera priorytet users/tom węzeł: 

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

Aby w tym samym czasie zapisać priorytet i dane, możesz dodać atrybut .priority do ładunku JSON: 

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

Aby zapisać priorytet i wartość podstawową (np. ciąg znaków) jednocześnie, możesz dodać element podrzędny .priority i umieścić wartość podstawową w przypadku dziecka z .value: 

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

Powoduje to zapis "Tom" z priorytetem 1.0. Priorytety można umieszczać w ładunku JSON na dowolnym poziomie.

Wartości serwera

Wartości serwera w lokalizacji możesz zapisywać za pomocą wartości zmiennej, która to obiekt z jednym kluczem .sv. Wartość tego klucza to typ wartości serwera, którą chcesz ustawić. Na przykład: ustawia wartość węzła na obecną wartość serwera Firebase sygnatura czasowa: 

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

Priorytety można też zapisywać za pomocą wartości serwera za pomocą polecenia „wirtualne dziecko” wskazanej powyżej ścieżki.

Obsługiwane wartości serwera obejmują:

Wartość serwera
sygnatura czasowa Czas od epoki UNIX (w milisekundach).
wzrost Podaj liczbę całkowitą lub wartość delta zmiennoprzecinkowej w postaci { ".sv": {"increment": <delta_value> }}, który określa atomowo zwiększyć bieżącą wartość bazy danych. Jeśli dane jeszcze nie istnieją, aktualizacja zostanie ustawiona do wartości delta. Jeśli jedna z wartości delta lub istniejące dane są swobodne liczby punktów, obie te wartości zostaną zinterpretowane jako liczby zmiennoprzecinkowe i zastosowane do funkcji podwójnej wartości. Podwójna arytmetyka i reprezentacja wartości podwójnej precyzji Semantyka IEEE 754. Jeśli występuje dodatnie/ujemne przekroczenie liczby całkowitej, obliczana jest suma podwójnej precyzji.

Pobieram i aktualizuję aplikację Firebase Realtime Database Security Rules

Za pomocą interfejsu API REST można również pobierać i aktualizować Firebase Realtime Database Security Rules za do projektu Firebase. Potrzebny będzie tajny klucz projektu Firebase, znajdziesz w sekcji panelu Konta usługi w projekcie Firebase . 

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

Uwierzytelniaj żądania

Domyślnie żądania REST są wykonywane bez uwierzytelniania i będą skuteczne tylko wtedy, gdy Reguły Realtime Database zezwalają na publiczny dostęp z uprawnieniami do odczytu i zapisu w: danych. Aby uwierzytelnić żądanie, użyj Parametry zapytania access_token= lub auth=.

Więcej informacji o uwierzytelnianiu za pomocą interfejsu API REST znajdziesz w artykule Uwierzytelniaj żądania REST.

Warunki błędu

Interfejs API typu REST Firebase Database może zwrócić poniższe kody błędów.

Kody stanu HTTP
400 Nieprawidłowe żądanie

Jeden z tych warunków błędu:

  • Nie udało się przeanalizować danych PUT ani POST.
  • Brak danych: PUT lub POST.
  • Żądanie próbuje użyć danych PUT lub POST który jest za duży.
  • Wywołanie interfejsu API REST zawiera w ścieżce nieprawidłowe nazwy podrzędne.
  • Ścieżka wywołania interfejsu API REST jest za długa.
  • Żądanie zawiera nierozpoznaną wartość serwera.
  • Indeks zapytania nie jest zdefiniowany w Twojej Firebase Realtime Database Security Rules
  • Żądanie nie obsługuje jednego ze podanych parametrów zapytania.
  • Żądanie łączy parametry zapytania z płytkim żądaniem GET.
401 Brak autoryzacji

Jeden z tych warunków błędu:

  • Token uwierzytelniania wygasł.
  • Token uwierzytelniania użyty w żądaniu jest nieprawidłowy.
  • Nie udało się uwierzytelnić przy użyciu tokena access_token.
  • Ta prośba narusza Twoje Firebase Realtime Database Security Rules.
404 Nie znaleziono Nie znaleziono określonego elementu Realtime Database.
500 – wewnętrzny błąd serwera Serwer zwrócił błąd. Więcej informacji znajdziesz w komunikacie o błędzie .
503 Usługa niedostępna Podana Baza danych czasu rzeczywistego Firebase jest tymczasowo niedostępna, co oznacza, że prośba nie została podjęta.
412 Nie spełniono warunku wstępnego Podana w żądaniu wartość ETag w nagłówku if-match nie była zgodna z wartością serwera.