Zapisywanie danych

Zapisywanie danych za pomocą metody PUT

Podstawową operacją zapisu za pomocą interfejsu API REST jest PUT. Aby zademonstrować zapisywanie danych, utworzymy aplikację do blogowania z postami i użytkownikami. Wszystkie dane naszej aplikacji będą przechowywane w ścieżce „fireblog” pod adresem URL bazy danych Firebase `https://docs-examples.firebaseio.com/fireblog`.

Zacznijmy od zapisania danych użytkownika w bazie danych Firebase. Każdy użytkownik będzie przechowywany pod unikalną nazwą użytkownika, a także pod imieniem i nazwiskiem oraz datą urodzenia. Każdy użytkownik ma unikalną nazwę, więc zamiast POST warto użyć PUT, ponieważ mamy już klucz i nie musimy go tworzyć.

Za pomocą PUT możemy zapisać w bazie danych Firebase ciąg znaków, liczbę, wartość logiczną, tablicę lub dowolny obiekt JSON. W tym przypadku przekażemy mu obiekt:

curl -X PUT -d '{
  "alanisawesome": {
    "name": "Alan Turing",
    "birthday": "June 23, 1912"
  }
}' 'https://docs-examples.firebaseio.com/fireblog/users.json'

Gdy obiekt JSON jest zapisywany w bazie danych, właściwości obiektu są automatycznie mapowane na lokalizacje podrzędne w sposób zagnieżdżony. Jeśli przejdziemy do nowo utworzonego węzła, zobaczymy wartość „Alan Turing”. Możemy też zapisywać dane bezpośrednio w lokalizacji podrzędnej:

curl -X PUT -d '"Alan Turing"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/name.json'

curl -X PUT -d '"June 23, 1912"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/birthday.json'

Powyższe 2 przykłady – zapisywanie wartości w tym samym czasie co obiekt i zapisywanie ich oddzielnie w lokalizacjach podrzędnych – spowodują zapisanie w bazie danych Firebase tych samych danych:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing"
    }
  }
}

Żądanie zakończone powodzeniem będzie oznaczone kodem stanu HTTP 200 OK, a odpowiedź będzie zawierać dane, które zapisaliśmy w bazie danych. Pierwszy przykład wywoła tylko 1 zdarzenie na klientach, którzy obserwują dane, a drugi przykład wywoła 2 zdarzenia. Pamiętaj, że jeśli w ścieżce użytkownika istniały już dane, pierwsze podejście spowoduje ich zastąpienie, a druga metoda zmodyfikuje tylko wartość każdego oddzielnego węzła podrzędnego, pozostawiając inne węzły podrzędne bez zmian. Zmienna PUT jest odpowiednikiem zmiennej set() w naszym pakiecie SDK JavaScript.

Aktualizowanie danych za pomocą metody PATCH

Za pomocą żądania PATCH możemy zaktualizować informacje o konkretnych dzieciach w danej lokalizacji bez nadpisywania istniejących danych. Dodajmy pseudonim Turinga do jego danych użytkownika za pomocą żądania PATCH:

curl -X PATCH -d '{
  "nickname": "Alan The Machine"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

Powyższa prośba zapisze wartość nickname w obiekcie alanisawesome bez usuwania elementów podrzędnych name ani birthday. Pamiętaj, że gdybyśmy zamiast tego wysłali PUT żądanie, name i birthday zostałyby usunięte, ponieważ nie zostały uwzględnione w żądaniu. Dane w naszej bazie danych Firebase wyglądają teraz tak:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    }
  }
}

Żądanie zakończone powodzeniem będzie oznaczone kodem stanu HTTP 200 OK, a odpowiedź będzie zawierać zaktualizowane dane zapisane w bazie danych.

Firebase obsługuje też aktualizacje wielu ścieżek. Oznacza to, że PATCH może teraz jednocześnie aktualizować wartości w wielu lokalizacjach w bazie danych Firebase. Jest to zaawansowana funkcja, która pomaga denormalizować dane. Korzystając z aktualizacji wielościeżkowych, możemy jednocześnie dodać pseudonimy do obu osób:

curl -X PATCH -d '{
  "alanisawesome/nickname": "Alan The Machine",
  "gracehopper/nickname": "Amazing Grace"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

Po tej aktualizacji zarówno Alan, jak i Grace mają dodane pseudonimy:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "date_of_birth": "December 9, 1906",
      "full_name": "Grace Hopper",
      "nickname": "Amazing Grace"
    }
  }
}

Pamiętaj, że próba zaktualizowania obiektów przez zapisanie obiektów ze ścieżkami spowoduje inne działanie. Zobaczmy, co się stanie, jeśli spróbujemy zaktualizować dane Grzegorza i Alana w ten sposób:

curl -X PATCH -d '{
  "alanisawesome": {"nickname": "Alan The Machine"},
  "gracehopper": {"nickname": "Amazing Grace"}
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

Powoduje to inne działanie, a mianowicie zastąpienie całego węzła /fireblog/users:

{
  "users": {
    "alanisawesome": {
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "nickname": "Amazing Grace"
    }
  }
}

Aktualizowanie danych za pomocą żądań warunkowych

1. Aby wykonać żądanie warunkowe w lokalizacji, uzyskaj unikalny identyfikator bieżących danych w tej lokalizacji lub ETag. Jeśli dane w tej lokalizacji ulegną zmianie, zmieni się też tag ETag. Możesz poprosić o ETag za pomocą dowolnej metody innej niż PATCH. W przykładzie poniżej użyto żądania GET.

   curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

   Wywołanie ETag w nagłówku zwraca ETag określonej lokalizacji w odpowiedzi HTTP.

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   10 // Current value of the data at the specified location

2. Do następnego żądania PUT lub DELETE dołącz zwrócony tag ETag, aby zaktualizować dane, które są zgodne z wartością tego tagu. W naszym przykładzie, aby zaktualizować licznik do 11, czyli o 1 więcej niż początkowa pobrana wartość 10, i odrzucić żądanie, jeśli wartość nie pasuje już do tej wartości, użyj tego kodu:

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

   Jeśli wartość danych w określonej lokalizacji nadal wynosi 10, tag ETag w żądaniu PUT jest zgodny, a żądanie się powiedzie, zapisując w bazie danych wartość 11.

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   Cache-Control: no-cache
   
   11 // New value of the data at the specified location, written by the conditional request

   Jeśli lokalizacja nie pasuje już do tagu ETag (co może się zdarzyć, gdy inny użytkownik zapisze w bazie danych nową wartość), żądanie zakończy się niepowodzeniem bez zapisywania w lokalizacji. Odpowiedź zwrotna zawiera nową wartość i ETag.

   HTTP/1.1 412 Precondition Failed
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   12 // New value of the data at the specified location

3. Jeśli zdecydujesz się ponownie przesłać prośbę, użyj nowych informacji. Realtime Database nie ponawia automatycznie nieudanych żądań warunkowych. Możesz jednak użyć nowej wartości i znacznika ETag, aby utworzyć nowe żądanie warunkowe z informacjami zwróconymi przez odpowiedź o błędzie.

Żądania warunkowe oparte na REST implementują standard HTTP if-match. Różnią się one jednak od standardowych w tych aspektach:

• W przypadku każdego żądania if-match możesz podać tylko jedną wartość ETag, a nie kilka.
• Standard sugeruje, aby tagi ETag były zwracane w przypadku wszystkich żądań, ale Baza danych w czasie rzeczywistym zwraca je tylko w przypadku żądań zawierających nagłówek X-Firebase-ETag. Obniża to koszty rozliczeń w przypadku standardowych żądań.

Żądania warunkowe mogą też działać wolniej niż typowe żądania REST.

Zapisywanie list danych

Aby wygenerować unikalny klucz oparty na sygnaturze czasowej dla każdego elementu podrzędnego dodanego do odwołania do bazy danych Firebase, możemy wysłać żądanie POST. W przypadku ścieżki users zdefiniowanie własnych kluczy miało sens, ponieważ każdy użytkownik ma unikalną nazwę użytkownika. Gdy jednak użytkownicy dodadzą posty na blogu do aplikacji, użyjemy żądania POST, aby automatycznie wygenerować klucz dla każdego z nich:

curl -X POST -d '{
  "author": "alanisawesome",
  "title": "The Turing Machine"
}' 'https://docs-examples.firebaseio.com/fireblog/posts.json'

Ścieżka posts zawiera teraz te dane:

{
  "posts": {
    "-JSOpn9ZC54A4P4RoqVa": {
      "author": "alanisawesome",
      "title": "The Turing Machine"
    }
  }
}

Zwróć uwagę, że klucz -JSOpn9ZC54A4P4RoqVa został wygenerowany automatycznie, ponieważ użyliśmy żądania POST. Żądanie zakończone powodzeniem będzie oznaczone kodem stanu HTTP 200 OK, a odpowiedź będzie zawierać klucz nowych dodanych danych:

{"name":"-JSOpn9ZC54A4P4RoqVa"}

Usuwanie danych

Aby usunąć dane z bazy danych, możemy wysłać DELETE z adresem URL ścieżki, z której chcemy usunąć dane. W tym przypadku Alan zostanie usunięty z naszej ścieżki users:

curl -X DELETE \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

Pomyślne żądanie DELETE będzie oznaczone kodem stanu HTTP 200 OK z odpowiedzią zawierającą JSON null.

Parametry URI

Podczas zapisywania danych w bazie danych interfejs API REST akceptuje te parametry URI:

uwierzytelnienie

Parametr żądania auth umożliwia dostęp do danych chronionych przez Firebase Realtime Database Security Rules i jest obsługiwany przez wszystkie typy żądań. Argumentem może być tajny klucz aplikacji Firebase lub token uwierzytelniania, o którym piszemy w sekcji dotyczącej autoryzacji użytkownika. W przykładzie poniżej wysyłamy żądanie POST z parametrem auth, gdzie CREDENTIAL to tajny klucz aplikacji Firebase lub token uwierzytelniający:

curl -X POST -d '{"Authenticated POST request"}' \
  'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

drukuj

Parametr print umożliwia określenie formatu odpowiedzi z bazy danych. Dodanie do żądania znaku print=pretty spowoduje zwrócenie danych w formacie czytelnym dla człowieka. print=pretty jest obsługiwany przez żądania GET, PUT, POST, PATCH i DELETE.

Aby podczas zapisywania danych pominąć dane wyjściowe z serwera, możemy dodać do żądania fragment kodu print=silent. Jeśli żądanie zostanie zrealizowane, odpowiedź będzie pusta i oznaczona kodem stanu HTTP 204 No Content. Żądania print=silent są obsługiwane przez żądania GET, PUT, POST i PATCH.

Zapisywanie wartości z serwera

Wartości serwera można zapisywać w lokalizacji za pomocą wartości zastępczej, która jest obiektem z jednym kluczem ".sv". Wartość tego klucza to typ wartości serwera, którą chcemy ustawić. Aby na przykład ustawić sygnaturę czasową utworzenia użytkownika, możemy wykonać te czynności:

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'

"timestamp" to jedyna obsługiwana wartość serwera. Jest to czas od epoki systemu UNIX w milisekundach.

Zwiększanie wydajności zapisu

Jeśli zapisujemy w bazie danych duże ilości danych, możemy użyć parametru print=silent, aby zwiększyć wydajność zapisu i zmniejszyć wykorzystanie przepustowości. W przypadku normalnego zachowania zapisu serwer odpowiada danymi JSON, które zostały zapisane. Gdy określono wartość print=silent, serwer natychmiast zamyka połączenie po otrzymaniu danych, co zmniejsza wykorzystanie przepustowości.

W przypadku, gdy wysyłamy do bazy danych wiele żądań, możemy ponownie wykorzystać połączenie HTTPS, wysyłając żądanie Keep-Alive w nagłówku HTTP.

Warunki błędu

W takich przypadkach interfejs API REST zwraca kody błędów:

Zabezpieczanie danych

Firebase ma język zabezpieczeń, który pozwala określać, którzy użytkownicy mają uprawnienia do odczytu i zapisu w różnych węzłach danych. Więcej informacji na ten temat znajdziesz w artykule Realtime Database Security Rules.