Musisz skonfigurować serwer rezerwacji, aby umożliwić Centrum akcji wykonywanie połączeń zwrotnych w celu tworzenia i aktualizowania rezerwacji w Twoim imieniu.
- Implementacja standardowa. Pozwoli to Centrum działań tworzyć spotkania, rezerwacje i rezerwacje z Tobą w imieniu użytkownika.
Informacje o tym, jak skonfigurować połączenie z serwerem rezerwacji w trybie piaskownicy i serwerów rezerwacji w środowisku produkcyjnym, znajdziesz w dokumentacji portalu dla partnerów.
Wdrażanie interfejsu API typu REST
Wdróż interfejs API oparty na REST. Dzięki temu Google może wysyłać żądania do serwera rezerwacji przez HTTP.
Na początek skonfiguruj serwer rezerwacji w trybie programistycznym lub w trybie piaskownicy, który można połączyć ze środowiskiem piaskownicy Actions Center. Przejdź do środowiska produkcyjnego dopiero po pełnym przetestowaniu serwera piaskownicy.
Metody
W przypadku każdego typu serwera rezerwacji wymagany jest po Twojej stronie inny zestaw metod interfejsu API. Opcjonalnie możesz pobrać definicję usługi w formacie proto, aby rozpocząć implementację interfejsu API. Tabele poniżej przedstawiają metody każdej implementacji i zawierają linki do formatów protokołów usługi.
Implementacja standardowa |
---|
Definicja usługi standardowej: pobierz plik definicji usługi proto. |
Metoda | Żądanie HTTP |
---|---|
HealthCheck | POBIERZ /v3/HealthCheck/ |
BatchAvailabilityLookup | POST /v3/BatchAvailabilityLookup/ |
CreateBooking | POST /v3/CreateBooking/ |
UpdateBooking | POST /v3/UpdateBooking/ |
GetBookingStatus | POST /v3/GetBookingStatus/ |
ListBookings | POST /v3/ListBookings/ |
Zasoby interfejsu API
Rezerwacja
W implementacji standardowej używane są te typy zasobów:
- Boks: boks reklamowy.
- Rezerwacja: spotkanie dotyczące przedziału czasu na zasoby reklamowe.
Proces: tworzenie rezerwacji
Z tej sekcji dowiesz się, jak utworzyć rezerwację w ramach implementacji standardowej.
Gdy użytkownik utworzy rezerwację, Google wyśle Ci jego imię, nazwisko, numer telefonu i adres e-mail. Z Twojego punktu widzenia ta rezerwacja powinna być traktowana jako płatność bez logowania, ponieważ Centrum działań nie może wyszukać konta użytkownika w Twoim systemie. Sprawdź, czy ostateczna rezerwacja wygląda tak samo jak rezerwacje sprzedawców pochodzące z Twojego systemu rezerwacji.
Zabezpieczenia i uwierzytelnianie
Cała komunikacja z serwerem rezerwacji odbywa się przez HTTPS, dlatego serwer musi mieć prawidłowy certyfikat TLS zgodny z jego nazwą DNS. Aby ułatwić sobie konfigurowanie serwera, zalecamy użycie publicznie dostępnego narzędzia do weryfikacji SSL/TLS, takiego jak Test serwera SSL firmy Qualys.
Wszystkie żądania, które Google będzie wysyłać do Twojego serwera rezerwacji, będą uwierzytelniane za pomocą podstawowego uwierzytelniania HTTP. Podstawowe dane uwierzytelniające (nazwę użytkownika i hasło) serwera rezerwacji można wpisać na stronie konfiguracji serwera rezerwacji w portalu dla partnerów. Hasła należy zmieniać co 6 miesięcy.
Przykładowe wdrożenia szkieletu
Zacznij od obejrzenia tych przykładowych szkieletów serwera rezerwacji napisanego dla platform Node.js i Java:
- Szkielet Node.js js-maps-booking-rest-server-v3-skeleton
- Szkielet Javy java-maps-booking-rest-server-v3-skeleton
Te serwery mają skrócone metody REST.
Wymagania
Błędy HTTP i błędy logiki biznesowej
Gdy backend obsługuje żądania HTTP, mogą wystąpić 2 rodzaje błędów.
- Błędy związane z infrastrukturą lub nieprawidłowymi danymi
- Zwróć te błędy klientowi ze standardowymi kodami 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 wskaż błąd logiki biznesowej w treści odpowiedzi. Typy błędów logiki biznesowej, które możesz napotkać, są różne w zależności od typu implementacji serwera.
- Zwróć kod stanu HTTP ustawiony na
W przypadku implementacji Standard potencjalne błędy w logice biznesowej są rejestrowane w polu Błąd rezerwacji i zwracane w odpowiedzi HTTP. Podczas tworzenia lub aktualizacji zasobu mogą wystąpić błędy logiki biznesowej. gdy np. obsługujesz metody CreateBooking
lub UpdatingBooking
. Oto kilka przykładów:
- Jeśli żądany przedział nie jest już dostępny, używany jest
SLOT_UNAVAILABLE
. - Jeśli podany typ karty kredytowej nie jest akceptowany, używana jest karta
PAYMENT_ERROR_CARD_TYPE_REJECTED
.
Idempotentność
Komunikacja przez sieć nie zawsze jest niezawodna i Google może ponawiać żądania HTTP, jeśli nie otrzyma odpowiedzi. Z tego powodu wszystkie metody, które mutują stan, muszą być idempotentne:
CreateBooking
UpdateBooking
W przypadku każdej wiadomości żądania oprócz UpdateBooking
dołączane są tokeny idempotentności, które pozwalają jednoznacznie zidentyfikować żądanie. Dzięki temu możesz odróżnić ponownie użyte wywołanie REST z zamiarem utworzenia pojedynczego żądania i 2 osobne żądania.
Obiekt UpdateBooking
jest jednoznacznie identyfikowany przez identyfikatory wpisów rezerwacji, więc w żądaniach nie jest uwzględniony token idempotentności.
Oto kilka przykładów tego, jak serwery rezerwacji obsługują idempotentność:
Pomyślna odpowiedź HTTP
CreateBooking
będzie zawierać utworzoną rezerwację. W niektórych przypadkach płatność jest przetwarzana w ramach procesu rezerwacji. Jeśli po raz drugi otrzymasz dokładnie taką samą wartośćCreateBookingRequest
(z tą samą wartościąidempotency_token
), musi zostać zwrócona ta sama wartośćCreateBookingResponse
. Nie jest tworzona druga rezerwacja, a opłata za użytkownika jest naliczana dokładnie raz (w stosownych przypadkach).Pamiętaj, że jeśli próba
CreateBooking
zakończy się niepowodzeniem i to samo żądanie zostanie wysłane ponownie, w tym przypadku backend powinien ponowić próbę.
Wymagania dotyczące idempotentności mają zastosowanie do wszystkich metod, które zmieniają stan.