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.
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ę.
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.
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.
- Zwróć kod stanu HTTP ustawiony na
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ładnieCreateBookingRequest
została otrzymana po raz drugi (z tą samą wartościąidempotency_token
), musi zostać zwrócony ten samCreateBookingResponse
. 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.