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 ETagif_match: <matching etag> | ETag nie pasujeif_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:
|
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. |
O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.
Ostatnia aktualizacja: 2024-03-20 UTC.