API REST bazy danych Firebase

Użycie API

Jako punktu końcowego REST możesz użyć dowolnego adresu URL bazy danych czasu rzeczywistego Firebase. Wszystko, co musisz zrobić, to dodać rozszerzenie .json na końcu adresu URL i wysłać żądanie ze swojego ulubionego klienta HTTPS.

Wymagany jest protokół HTTPS. Firebase odpowiada tylko na zaszyfrowany ruch, dzięki czemu Twoje dane pozostają bezpieczne.

GET – Odczyt danych

Dane z bazy danych czasu rzeczywistego można odczytać, wysyłając żądanie HTTP GET do punktu końcowego. Poniższy przykład ilustruje sposób pobrania nazwy użytkownika zapisanej wcześniej w bazie danych czasu rzeczywistego.

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

Pomyślne żądanie jest sygnalizowane kodem stanu HTTP 200 OK . Odpowiedź zawiera dane powiązane ze ścieżką w żądaniu GET .

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

PUT – Zapisywanie danych

Możesz zapisywać dane za pomocą żądania PUT .

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

Pomyślne żądanie jest sygnalizowane kodem stanu HTTP 200 OK . Odpowiedź zawiera dane określone w żądaniu PUT .

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

POST — przesyłanie danych

Aby osiągnąć odpowiednik metody JavaScript push() (zobacz Listy danych ), możesz wysłać żądanie POST .

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

Pomyślne żądanie jest sygnalizowane kodem stanu HTTP 200 OK . Odpowiedź zawiera nazwę podrzędną nowych danych określonych w żądaniu POST .

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

PATCH – aktualizacja danych

Możesz zaktualizować określone elementy podrzędne w lokalizacji bez nadpisywania istniejących danych za pomocą żądania PATCH . Nazwane dzieci w danych zapisywanych za pomocą PATCH są nadpisywane, ale pominięte dzieci nie są usuwane. Jest to odpowiednik funkcji update() JavaScript.

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

Pomyślne żądanie jest sygnalizowane kodem stanu HTTP 200 OK . Odpowiedź zawiera dane określone w żądaniu PATCH .

{ "last": "Jones" }

USUŃ – Usuwanie danych

Możesz usunąć dane za pomocą żądania DELETE :

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

Pomyślne żą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 z przeglądarki, która nie obsługuje powyższych metod, możesz zastąpić metodę żądania, wykonując żądanie POST i ustawiając metodę przy użyciu nagłówka żą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 także 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, odpowiednik REST operacji transakcyjnych SDK, aktualizują dane zgodnie z określonym warunkiem. Zobacz przegląd przepływu pracy i dowiedz się więcej o żądaniach warunkowych REST w sekcji Zapisywanie danych .

Firebase ETag

Firebase ETag to unikalny identyfikator bieżących danych w określonej lokalizacji. Jeśli dane ulegną zmianie w tej lokalizacji, zmieni się także ETag. Wartość ETag Firebase musi być określona w nagłówku początkowego żądania REST (zazwyczaj GET , ale może mieć dowolną wartość inną niż PATCH ).

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

jeśli pasuje

Warunek if-match określa wartość ETag dla danych, które chcesz zaktualizować. Jeśli użyjesz tego warunku, Baza danych czasu rzeczywistego zakończy żądania tylko wtedy, gdy ETag określony w żądaniu zapisu pasuje do ETag istniejących danych w bazie danych. Pobierz ETag z lokalizacji za pomocą żądania ETag Firebase. Jeśli chcesz zastąpić dowolną lokalizację o wartości 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

Poniższa tabela zawiera przegląd oczekiwanych odpowiedzi dla każdego typu żądania na podstawie dopasowania ETag.

Typ żądania „X-Firebase-ETag: prawda” Dopasowania ETag
if_match: <matching etag>
ETag nie pasuje
if_match: <no matching etag>
DOSTAWAĆ Stan/treść odpowiedzi 200: „<ścieżka_danych>” 400: „...nieobsługiwane..” 400: „...nieobsługiwane..”
Dodano nagłówki ETag: <ETag_danych> Nie dotyczy Nie dotyczy
UMIEŚCIĆ Stan/treść odpowiedzi 200: „<put_data>” 200: „<put_data>” 412: „...Niezgodność tagu ET..”
Dodano nagłówki ETag: <ETag_of_put_data> Nie dotyczy ETag: <database_ETag>
POST Stan/treść odpowiedzi 200: „<dane_postu>” 400: „...nieobsługiwane..” 400: „...nieobsługiwane..”
Dodano nagłówki ETag: <ETag_of_post_data> Nie dotyczy Nie dotyczy
SKRAWEK Stan/treść odpowiedzi 400: „...nieobsługiwane..” 400: „...nieobsługiwane..” 400: „...nieobsługiwane..”
Dodano nagłówki Nie dotyczy Nie dotyczy Nie dotyczy
USUWAĆ Stan/treść odpowiedzi 200: zero 200: „<data_after_put>” 412: „...Niezgodność tagu ET..”
Dodano nagłówki ETag: <ETag_of_null> Nie dotyczy ETag: <database_ETag>

Parametry zapytania

Interfejs API REST bazy danych Firebase akceptuje następujące parametry i wartości zapytań:

token_dostępu

Obsługiwane przez wszystkie typy żądań. Uwierzytelnia to żądanie, aby umożliwić dostęp do danych chronionych przez reguły bezpieczeństwa bazy danych Firebase Realtime. Aby uzyskać szczegółowe informacje, zobacz dokumentację uwierzytelniania REST .

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

płytki

Jest to zaawansowana funkcja zaprojektowana, aby pomóc Ci pracować z dużymi zbiorami danych bez konieczności pobierania wszystkiego. Ustaw tę opcję na true , aby ograniczyć głębokość danych zwracanych w lokalizacji. 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 true .

Argumenty Metody odpoczynku Opis
płytki DOSTAWAĆ Ogranicz głębokość odpowiedzi.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Należy pamiętać, że shallow nie mogą być łączone z żadnymi innymi parametrami zapytania.

wydrukować

Formatuje dane zwrócone w odpowiedzi z serwera.

Argumenty Metody odpoczynku Opis
ładny POBIERZ, WSTAW, WYŚLIJ, POPRAW, USUŃ Przeglądaj dane w formacie czytelnym dla człowieka.
cichy POBIERZ, WSTAW, WYŚLIJ, POPRAW Służy do ukrywania danych wyjściowych z serwera podczas zapisywania danych. Wynikowa odpowiedź będzie pusta i oznaczona kodem 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'

oddzwonić

Obsługiwane tylko przez GET . 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.

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

format

Jeśli ustawione na export , serwer będzie kodować priorytety w odpowiedzi.

Argumenty Metody odpoczynku Opis
eksport DOSTAWAĆ Dołącz informacje o priorytecie w odpowiedzi.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

pobierać

Obsługiwane tylko przez GET . Jeśli chcesz uruchomić pobieranie pliku danych z przeglądarki internetowej, dodaj download= . Powoduje to, że usługa REST dodaje odpowiednie nagłówki, aby przeglądarki wiedziały, że mają zapisać dane do pliku.

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

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.

napiszSizeLimit

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

Jeśli określisz opcję unlimited , dozwolone będą wyjątkowo duże zapisy (z ładunkiem do 256 MB), co może potencjalnie blokować kolejne żądania, podczas gdy baza danych przetwarza bieżącą operację. Zapisów nie można anulować po dotarciu do serwera.

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

Jeśli zapis jest za duży, pojawi się następujący 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 instancji bazy danych, korzystając z interfejsu CLI Firebase. Ten limit dotyczy wszystkich żądań, w tym żądań z pakietów SDK. Nowe bazy danych są tworzone z defaultWriteSizeLimit ustawioną na large . Nie można ustawić defaultWriteSizeLimit na tiny przy użyciu interfejsu wiersza polecenia Firebase.

firebase database:settings:set defaultWriteSizeLimit large

Zamów przez

Aby uzyskać więcej informacji, zobacz sekcję przewodnika dotyczącą uporządkowanych danych .

limitToFirst, limitToLast, startAt, endAt, RówneTo

Aby uzyskać więcej informacji, zobacz sekcję przewodnika dotyczącą filtrowania danych .

Przesyłanie strumieniowe z interfejsu API REST

Punkty końcowe REST Firebase obsługują protokół EventSource / Server-Sent Events . Aby przesyłać strumieniowo zmiany do pojedynczej lokalizacji w bazie danych czasu rzeczywistego, musisz wykonać kilka czynności:

  • Ustaw nagłówek Accept klienta na "text/event-stream"
  • Szanuj przekierowania HTTP, w szczególności kod stanu HTTP 307
  • Jeśli lokalizacja wymaga uprawnień do odczytu, należy dołączyć parametr auth

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 formacie JSON to obiekt posiadający dwa klucze: path i data . Klucz ścieżki wskazuje lokalizację względem adresu URL żądania. Klient powinien zastąpić wszystkie dane w tej lokalizacji w swojej pamięci podręcznej danymi .

skrawek

Dane zakodowane w formacie JSON to obiekt posiadający dwa klucze: path i data . Klucz ścieżki wskazuje lokalizację względem adresu 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ą null . Nie jest wymagane żadne działanie.

anulować

Niektóre nieoczekiwane błędy mogą spowodować wysłanie zdarzenia „anuluj” i zakończenie połączenia. Przyczynę opisano w danych przekazanych dla tego zdarzenia. Oto niektóre potencjalne przyczyny: 1. Reguły bezpieczeństwa bazy danych Firebase Realtime nie pozwalają już na odczyt w żądanej lokalizacji. Opis `danych` dla tej przyczyny to „Odmowa pozwolenia”. 2. Zapis wyzwolił streamer zdarzeń, który wysłał duże drzewo JSON przekraczające nasz limit, czyli 512 MB. „Dane” w tym przypadku to: „Określony ładunek jest za duży. Proszę zażądać lokalizacji z mniejszą ilością danych”.

uwierzytelnienie_odwołane

Dane dla tego zdarzenia to ciąg znaków wskazujący, że poświadczenie wygasło. To zdarzenie jest wysyłane, gdy podany parametr auth nie jest już ważny.

Oto przykładowy zestaw 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}}

Priorytety

Do informacji o priorytecie lokalizacji można odwoływać się za pomocą „wirtualnego elementu podrzędnego” o nazwie .priority . Możesz czytać priorytety za pomocą żądań GET i zapisywać je za pomocą żądań PUT . Na przykład następujące żądanie pobiera priorytet węzła users/tom :

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

Aby jednocześnie zapisywać priorytet i dane, możesz dodać element podrzędny .priority do ładunku JSON:

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

Aby jednocześnie zapisać priorytet i wartość pierwotną (np. ciąg znaków), możesz dodać dziecko .priority i umieścić wartość pierwotną w dziecku .value :

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

To pisze "Tom" z priorytetem 1.0 . Priorytety można uwzględnić na dowolnej głębokości w ładunku JSON.

Wartości serwera

Możesz zapisać wartości serwera w lokalizacji, używając wartości zastępczej, która jest obiektem z pojedynczym kluczem .sv . Wartość tego klucza to typ wartości serwera, który chcesz ustawić. Na przykład następujące żądanie ustawia wartość węzła na bieżący znacznik czasu serwera Firebase:

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

Możesz także zapisać priorytety, używając wartości serwera, korzystając ze ścieżki „wirtualnego dziecka” wskazanej powyżej.

Obsługiwane wartości serwera obejmują:

Wartość serwera
znak czasu Czas od epoki UNIX, w milisekundach.
przyrost Podaj całkowitą lub zmiennoprzecinkową wartość delta w postaci { ".sv": {"increment": <delta_value> }} , za pomocą której chcesz niepodzielnie zwiększyć bieżącą wartość bazy danych. Jeśli dane jeszcze nie istnieją, aktualizacja ustawi dane na wartość delta. Jeśli którakolwiek wartość delta lub istniejące dane są liczbami zmiennoprzecinkowymi, obie wartości zostaną zinterpretowane jako liczby zmiennoprzecinkowe i zastosowane na zapleczu jako wartość podwójna. Podwójna arytmetyka i reprezentacja podwójnych wartości są zgodne z semantyką IEEE 754. W przypadku dodatniego/ujemnego przekroczenia liczby całkowitej suma jest obliczana jako podwójna.

Pobieranie i aktualizowanie reguł bezpieczeństwa bazy danych Firebase Realtime

Interfejsu API REST można również używać do pobierania i aktualizowania reguł bezpieczeństwa bazy danych Firebase Realtime dla projektu Firebase. Będziesz potrzebować sekretu swojego projektu Firebase, który znajdziesz w panelu Konta usług w ustawieniach projektu 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'

Uwierzytelnij żądania

Domyślnie żądania REST są wykonywane bez uwierzytelniania i zakończą się sukcesem tylko wtedy, gdy reguły bazy danych czasu rzeczywistego zezwalają na publiczny dostęp do odczytu lub zapisu danych. Aby uwierzytelnić żądanie, użyj parametrów zapytania access_token= lub auth= .

Dowiedz się więcej o uwierzytelnianiu za pośrednictwem interfejsu API REST w artykule Uwierzytelnianie żądań REST .

Warunki błędu

Interfejs API REST bazy danych Firebase może zwracać następujące kody błędów.

Kody stanu HTTP
400 Złych żądań

Jeden z następujących warunków błędu:

  • Nie można przeanalizować danych PUT lub POST .
  • Brak danych PUT lub POST .
  • Żądanie podejmuje próbę przesłania zbyt dużych danych PUT lub POST .
  • 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 regułach bezpieczeństwa bazy danych Firebase Realtime .
  • Żądanie nie obsługuje jednego z podanych parametrów zapytania.
  • Żądanie łączy parametry zapytania z płytkim żądaniem GET .
401 Nieautoryzowane

Jeden z następujących warunków błędu:

404 Nie Znaleziono Nie znaleziono określonej bazy danych czasu rzeczywistego.
500 wewnętrzny błąd serwera Serwer zwrócił błąd. Dalsze szczegóły znajdziesz w komunikacie o błędzie.
503 Usługa niedostępna Podana baza danych Firebase Realtime jest tymczasowo niedostępna, co oznacza, że ​​nie podjęto próby żądania.
412 Warunek wstępny nie powiódł się Wartość ETag określona w żądaniu w nagłówku if-match nie jest zgodna z wartością serwera.