Wdrażanie serwera rezerwacji

Aby umożliwić funkcji Zarezerwuj z Google wywołanie zwrotne i utworzenie w Twoim imieniu rezerwacji, musisz skonfigurować serwer rezerwacji.

• Wdrożenie standardowe. Dzięki niemu funkcja Zarezerwuj z Google może tworzyć w imieniu użytkownika spotkania i rezerwacje w ich imieniu.

Informacje o konfigurowaniu połączenia z piaskownicą i produkcyjnymi serwerami rezerwacji znajdziesz w dokumentacji portalu dla partnerów.

Wdrażanie interfejsu API REST

Zaimplementuj interfejs API oparty na REST. Umożliwia to Google wysyłanie żądań serwera rezerwacji przez HTTP.

Zacznij od skonfigurowania serwera rezerwacji lub środowiska programistycznego, który można połączyć ze środowiskiem piaskownicy Zarezerwuj z Google. Przeniesienie do środowiska produkcyjnego nastąpi dopiero po całkowitym przetestowaniu serwera piaskownicy.

Metody

Dla każdego typu serwera rezerwacji wymagamy innego zestawu metod API. Opcjonalnie możesz pobrać definicję usługi w formacie proto, aby rozpocząć implementację interfejsu API. W tabelach poniżej podano metody każdej implementacji oraz linki do formatów usługi.

Implementacja standardowa
Standardowa definicja usługi – pobierz plik definicji usługi proto.

Metoda	Żądanie HTTP
Kontrola stanu	Pobierz /v3/HealthCheck/
Wyszukiwanie dostępności wsadowej	POST /v3/BatchAvailabilityLookup/
CreateBooking	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBooking	POST /v3/ListBookings/

Zasoby interfejsu API

Rezerwacja

W standardowej implementacji używane są te typy zasobów:

• Boks: boks reklamowy.
• Rezerwacje: spotkanie dotyczące przedziału zasobów reklamowych.

Proces: tworzenie rezerwacji

Z tej sekcji dowiesz się, jak utworzyć rezerwację na potrzeby implementacji standardowej.

Ilustracja 1. Przepływ pracy tworzenia rezerwacji na podstawie przedziału

Gdy użytkownik utworzy rezerwację, Google wyśle mu imię, nazwisko, numer telefonu i adres e-mail. Z Twojego punktu widzenia ta rezerwacja musi być traktowana jako proces gościa, ponieważ usługa Zarezerwuj z Google nie może znaleźć konta użytkownika w Twoim systemie. Upewnij się, że ostatnia rezerwacja wygląda tak samo jak ta dokonana przez sprzedawcę. W przypadku bezpłatnych rezerwacji domyślnie dostępne są płatności w trybie gościa i dodatkowe adresy e-mail.

Bezpieczeństwo i uwierzytelnianie

Cała komunikacja z serwerem rezerwacji odbywa się przez HTTPS, dlatego ważne jest, aby serwer miał prawidłowy certyfikat TLS zgodny z nazwą DNS. Aby pomóc w skonfigurowaniu serwera, zalecamy użycie dostępnego publicznie narzędzia do weryfikacji SSL/TLS, takiego jak test serwera SSL Qualys.

Wszystkie żądania wysyłane przez Google do serwera rezerwacji będą uwierzytelniane przy użyciu podstawowego uwierzytelniania HTTP. Podstawowe dane logowania (nazwa użytkownika i hasło) do serwera rezerwacji można podać na stronie konfiguracji serwera rezerwacji w portalu partnera. Hasła muszą być wyświetlane co 6 miesięcy.

Uwaga: nazwę użytkownika i hasło musisz ustawić oddzielnie w trybie piaskownicy i przy użyciu środowiska produkcyjnego, korzystając z przełącznika środowiska.

Przykładowe implementacje szkieletów

Na początek zapoznaj się z tymi przykładami szkieletów serwera rezerwacji napisanymi jako środowiska Node.js i Java:

• Szkielet węzła Node.js js-maps-booking-rest-server-v3-skeleton
• Szkielet Java java-maps-booking-rest-server-v3-skeleton

Te serwery nie korzystają z metod REST.

Wymagania

Błędy HTTP i logiki biznesowej

Kiedy backend obsługuje żądania HTTP, mogą wystąpić 2 typy błędów.

• Błędy związane z infrastrukturą lub nieprawidłowe dane
  • Zwróć te błędy do klienta, używając standardowych kodów błędów HTTP. Zobacz pełną listę kodów stanu HTTP.
• Błędy związane z logiką biznesową
  • Zwróć kod stanu HTTP ustawiony na 200 OK i określ błąd logiczny biznesowy w treści odpowiedzi. Rodzaje błędów logiki biznesowej, które możesz napotkać, są różne w przypadku różnych typów implementacji serwera.

W przypadku implementacji standardowej możliwe błędy logiki biznesowej są zapisywane w sekcji Błąd rezerwacji, a odpowiedzi zwracane w odpowiedzi HTTP. Podczas tworzenia lub aktualizowania zasobu mogą wystąpić błędy logiczne. Na przykład gdy obsługujesz metody CreateBooking lub UpdatingBooking. Oto kilka przykładów:

• Jeśli żądany boks jest już niedostępny, używana jest wartość SLOT_UNAVAILABLE.
• PAYMENT_ERROR_CARD_TYPE_REJECTED jest używana, jeśli podany typ karty kredytowej nie jest akceptowany.

Idempotentność

Komunikacja przez sieć nie zawsze jest niezawodna, dlatego Google może ponawiać żądania HTTP, jeśli nie otrzyma ona odpowiedzi. Z tego powodu wszystkie metody zmieniające stan muszą być idempotentne:

• CreateBooking
• UpdateBooking

Każda wiadomość żądania oprócz UpdateBooking zawiera tokeny idempotentności, które jednoznacznie identyfikują żądanie. Dzięki temu można odróżnić powtarzane wywołanie REST z zamiarem utworzenia pojedynczego żądania i 2 osobnych żądań. UpdateBooking jest jednoznacznie identyfikowany na podstawie identyfikatorów wpisów dotyczących rezerwacji, więc w żądaniach nie ma tokena idempotentności.

Oto kilka przykładów obsługi serwerów rezerwacji na podstawie idempotentności:

• Pomyślna odpowiedź HTTP CreateBooking zawiera utworzoną rezerwację. W niektórych przypadkach płatność jest przetwarzana w ramach procesu rezerwacji. Jeśli dokładnie CreateBookingRequest została otrzymana po raz drugi (z tą samą wartością idempotency_token), musi zostać zwrócony ten sam CreateBookingResponse. Nie zostanie utworzona druga rezerwacja, a użytkownik zostanie obciążony dokładnie raz, jeśli wystąpi taka potrzeba.

  Pamiętaj, że jeśli próba wykonania operacji CreateBooking zakończy się niepowodzeniem i to samo żądanie zostanie wysłane ponownie, w tym przypadku backend powinien spróbować ponownie.

Wymaganie idempotentności dotyczy wszystkich metod, które zmieniają stan.