Skonfigurowanie serwera rezerwacji po Twojej stronie umożliwi Centrum działań tworzenie w Twoim imieniu spotkań, rezerwacji i zamówień w imieniu użytkownika.
Implementowanie interfejsu API opartego na gRPC
Uwaga: wszyscy nowi partnerzy powinni korzystać z interfejsu REST API zamiast gRPC API.
Zaimplementuj interfejs API oparty na gRPC. Dzięki temu Google może wysyłać prośby o rezerwację. Powierzchnia interfejsu API jest zdefiniowana za pomocą opartego na protokole protobuf języka IDL gRPC.
Prosimy nowych partnerów o wdrożenie zalecanego zestawu interfejsu API w wersji 2. Partnerzy mogą wybrać dowolny adres URL i PORT, które najlepiej pasują do ich infrastruktury.
W tej sekcji przedstawiamy zalecany zestaw interfejsów API w wersji 2. Dotyczy to partnerów, którzy nie wdrożyli interfejsu API w wersji 0. Obecni partnerzy, którzy wdrożyli interfejs API w wersji 0, mogą skontaktować się z Centrum działań, aby dowiedzieć się więcej.
Aby rozpocząć implementację interfejsu API, pobierz definicję usługi w formacie proto poniżej.
Zasoby interfejsu API
Zapoznaj się z tymi typami zasobów, które będą wykorzystywane w tym wdrożeniu:
- Miejsce: miejsce w zasobach reklamowych.
- Rezerwacja: rezerwacja terminu w asortymencie
Metody
Aby serwer gRPC działał prawidłowo, musisz zaimplementować te metody interfejsu API:
Te 5 metod definiuje wymagany zestaw wywołań RPC usługi BookingService:
// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
// Gets availability information for an appointment slot
rpc CheckAvailability(CheckAvailabilityRequest)
returns (CheckAvailabilityResponse) {}
// Creates a booking
rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}
// Updates an existing booking
rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}
// Gets status for an existing booking
rpc GetBookingStatus(GetBookingStatusRequest)
returns (GetBookingStatusResponse) {}
// Lists all upcoming bookings for a user
rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}
Proces: tworzenie rezerwacji
Podczas tworzenia rezerwacji Google wyśle do partnera imię, nazwisko, numer telefonu i adres e-mail użytkownika. Z punktu widzenia partnera należy to traktować jako płatność bez logowania, ponieważ Centrum działań nie ma możliwości wyszukania konta użytkownika w systemie partnera. Ostateczna rezerwacja powinna być wyświetlana sprzedawcom partnera w ich systemie tak samo jak rezerwacje pochodzące z systemu rezerwacji partnera.
Implementacja szkieletu w Javie
Na początek udostępniamy szkielet serwera gRPC w języku Java, który można skompilować i zainstalować. Znajdziesz ją w sekcji Przykłady > Implementacja referencyjna gRPC. Ten serwer ma zaślepione metody gRPC, które są potrzebne do obsługi integracji, w tym uwierzytelniania i usługi stanu.
Wymagania
Błąd gRPC i błąd logiki biznesowej
Podczas obsługi żądań gRPC przez backend partnera mogą wystąpić 2 rodzaje błędów: nieoczekiwane błędy wynikające z nieprawidłowych danych oraz błędy logiki biznesowej, które wskazują na niemożność utworzenia lub zaktualizowania rezerwacji (patrz Błąd rezerwacji), np. jeśli żądany przedział czasu jest niedostępny.
W przypadku wystąpienia nieoczekiwanych błędów należy zwrócić klientowi standardowe kody błędów gRPC. Wybrane przykłady:
- Błąd INVALID_ARGUMENT jest używany w wywołaniach RPC, takich jak CheckAvailability i CreateLease, i powinien być zwracany, jeśli podany przedział zawiera nieprawidłowe informacje.
- Kod NOT_FOUND jest używany w wywołaniach RPC, takich jak CreateBooking i ListBookings, i powinien być zwracany, jeśli podany identyfikator jest nieznany partnerowi.
W dokumentacji każdej metody znajdziesz kanoniczne kody błędów gRPC lub pełną listę kodów stanu.
Natomiast błędy logiki biznesowej powinny być rejestrowane w BookingFailure i zwracane w odpowiedzi RPC. Podczas tworzenia lub aktualizowania zasobu, czyli w trakcie obsługi wywołań RPC CreateBooking i UpdatingBooking, mogą wystąpić błędy logiki biznesowej. Wybrane przykłady:
- Wartość SLOT_UNAVAILABLE jest używana, jeśli żądany przedział czasu jest już niedostępny.
- Błąd PAYMENT_ERROR_CARD_TYPE_REJECTED jest używany, jeśli podany typ karty kredytowej nie jest akceptowany.
Idempotentność
Komunikacja w sieci nie zawsze jest niezawodna, dlatego Google Reserve może ponawiać wywołania RPC, jeśli nie otrzyma odpowiedzi. Z tego powodu wszystkie wywołania RPC, które zmieniają stan (CreateBooking, UpdateBooking), muszą być idempotentne. Wiadomości z prośbą o wywołanie tych RPC zawierają tokeny idempotentności, które jednoznacznie identyfikują żądanie i umożliwiają partnerowi odróżnienie ponowionego wywołania RPC (z zamiarem utworzenia jednej rezerwacji) od dwóch oddzielnych rezerwacji.
Wybrane przykłady:
- Odpowiedź RPC CreateBooking zawiera utworzoną rezerwację, a w niektórych przypadkach płatność jest przetwarzana w ramach procesu rezerwacji. Jeśli ten sam obiekt CreateBookingRequest
zostanie odebrany po raz drugi (w tym
idempotency_token), musi zostać zwrócony ten sam obiekt CreateBookingResponse. Nie zostanie utworzona druga rezerwacja, a użytkownik zostanie obciążony opłatą tylko raz (w odpowiednich przypadkach). Pamiętaj, że jeśli próba utworzenia rezerwacji się nie powiedzie, backend partnera powinien ponowić próbę, jeśli to samo żądanie zostanie wysłane ponownie.
Wymóg idempotentności dotyczy wszystkich metod, które zawierają tokeny idempotentności.
Zabezpieczenia i uwierzytelnianie serwera gRPC
Połączenia z Centrum działań do Twojego backendu muszą być zabezpieczone za pomocą protokołu SSL/TLS z wzajemnym uwierzytelnianiem klienta i serwera opartym na certyfikatach. Wymaga to użycia prawidłowego certyfikatu serwera w implementacji gRPC i zaakceptowania prawidłowego certyfikatu klienta.
Certyfikat serwera: serwer partnera musi mieć ważny certyfikat serwera powiązany z nazwą domeny serwera (patrz lista akceptowanych głównych urzędów certyfikacji). Implementacje serwera GRPC oczekują, że będą obsługiwać łańcuch certyfikatów prowadzący do certyfikatu głównego. Najłatwiej to zrobić, dołączając certyfikaty pośrednie udostępnione przez dostawcę hostingu partnera w formacie PEM do certyfikatu serwera (również w formacie PEM).
Certyfikat serwera jest weryfikowany w momencie nawiązywania połączenia, a certyfikaty podpisane samodzielnie nie są akceptowane. Rzeczywista treść certyfikatu nie jest sprawdzana, o ile jest on ważny. Poprawność certyfikatu możesz sprawdzić za pomocą tego polecenia:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Certyfikat klienta: aby uwierzytelnić nas (Google) u partnera, udostępniamy certyfikat klienta wydany przez Google Internet Authority G2 (certyfikat CA) o tych właściwościach:
| Pole | Wartość |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
Próby połączenia bez tego certyfikatu klienta powinny być odrzucane przez serwer partnera.
Aby zweryfikować certyfikat klienta, serwer korzysta z zestawu zaufanych certyfikatów głównych klienta. Ten zestaw zaufanych certyfikatów głównych możesz uzyskać od instytucji takiej jak Mozilla lub zainstalować zestaw certyfikatów głównych zalecany obecnie przez Google Internet Authority G2. W obu przypadkach może być konieczne ręczne aktualizowanie certyfikatów głównych.
Wdrażanie protokołu kontroli stanu gRPC
Zaimplementuj protokół kontroli stanu GRPC.
Ten protokół umożliwia Google monitorowanie stanu backendu implementacji gRPC. Specyfikacja usługi jest częścią dystrybucji gRPC. Zgodnie z konwencją nazewnictwa GRPC nazwa usługi w wywołaniach sprawdzających stan to ext.maps.booking.partner.v2.BookingService w przypadku interfejsu API w wersji 2 lub ext.maps.booking.partner.v0.BookingService w przypadku interfejsu API w wersji 0. Kontrola stanu powinna być przeprowadzana na tym samym adresie URL i porcie co inne punkty końcowe.
Inne wersje
Dokumentację innych wersji interfejsu API znajdziesz na tych stronach: * API w wersji 3 * API w wersji 0