Wdrożenie serwera rezerwacji: interfejs API w wersji 2

Skonfigurowanie serwera rezerwacji po Twojej stronie pozwoli Centrum działań tworzyć spotkania, rezerwacje lub rezerwacje w Twoim imieniu.

Zaimplementuj interfejs API oparty na gRPC

Uwaga: wszyscy nowi partnerzy powinni używać interfejsu REST API, a nie interfejsu gRPC API.

Wdrożyć interfejs API oparty na protokole gRPC. Dzięki temu Google może wysyłać prośby o rezerwację. Interfejs API jest zdefiniowany za pomocą interfejsu IDL opartego na protokole gRPC.

Naszych nowych partnerów prosimy o wdrażanie zalecanego zestawu interfejsu API w wersji 2. Partnerzy mogą wybrać adres URL i port, które najlepiej pasują do ich infrastruktury.

Ta sekcja przedstawia zalecany zestaw interfejsu API w wersji 2. Dotyczy to partnerów, którzy nie wdrożą interfejsu API w wersji 0. Aby dowiedzieć się więcej o partnerach, którzy wdrożą interfejs API w wersji 0, skontaktuj się z Centrum działań.

Aby rozpocząć implementację interfejsu API, pobierz poniżej definicję usługi w formacie proto.

Pobieranie definicji usługi

Zasoby interfejsu API

Zapoznaj się z tymi typami zasobów, które będą wykorzystywane w ramach tej implementacji:

Metody

Na serwerze gRPC musisz wdrożyć te metody interfejsu API:

Te 5 metod definiuje wymagany zestaw wywołań RPC 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

Ilustracja 1. Tworzenie rezerwacji na podstawie przedziału

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 proces płatności gościa, ponieważ Centrum działań nie ma możliwości sprawdzenia 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 szczątkowa w Javie

Aby ułatwić Ci rozpoczęcie pracy, udostępniamy szkielet serwera gRPC w języku Java, który można skompilować i zainstalować. Znajdziesz go w sekcji Przykłady > Implementacja referencyjna gRPC. Ten serwer ma zaimplementowane metody gRPC, które są potrzebne do obsługi integracji, w tym uwierzytelniania i usługi zdrowia.

Wymagania

Błąd gRPC i błąd logiki biznesowej

Gdy backend partnera obsługuje żądania gRPC, mogą wystąpić 2 typy błędów: nieoczekiwane błędy wynikające z nieprawidłowych danych oraz błędy logiki biznesowej wskazujące na niemożność utworzenia lub zaktualizowania rezerwacji (patrz Błąd rezerwacji), np. gdy żądany slot jest niedostępny.

Nieoczekiwane błędy, jeśli wystąpią, powinny zostać zwrócone do klienta za pomocą kanonicznej wersji kodów 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 slot zawiera nieprawidłowe informacje.
  • Wartość NOT_FOUND jest używana w RPC, takich jak CreateBooking i ListBookings, i powinna być zwracana, jeśli podany identyfikator jest nieznany dla partnera.

Informacje o kanonicznym kodzie błędu gRPC znajdziesz w opisie danej metody lub na pełnej liście kodów stanu.

Wręcz przeciwnie, błędy logiki biznesowej powinny być rejestrowane w BookingFailure i zwracane w odpowiedzi RPC. Błędy logiki biznesowej mogą wystąpić podczas tworzenia lub aktualizowania zasobu, np. podczas obsługi wywołań RPC CreateBooking i UpdatingBooking. Wybrane przykłady:

  • Wartość SLOT_UNAVAILABLE jest używana, jeśli żądany slot jest już niedostępny.
  • Wartość 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 Reserve może ponownie wysłać RPC, jeśli nie otrzyma odpowiedzi. Z tego powodu wszystkie wywołania RPC, które zmieniają stan (CreateBooking, UpdateBooking), muszą być idempotentne. Wiadomości żądania w przypadku tych RPC zawierają tokeny idempotentności, które umożliwiają jednoznaczną identyfikację żądania i rozróżnienie przez partnera powtórnego wywołania RPC (z zamiarem utworzenia pojedynczej rezerwacji) od 2 oddzielnych rezerwacji.

Wybrane przykłady:

  • Odpowiedź na wywołanie CreateBooking RPC zawiera utworzoną rezerwację. W niektórych przypadkach płatność jest przetwarzana w ramach procesu rezerwacji. Jeśli dokładnie to samo żądanie CreateBookingRequest otrzymane zostanie po raz drugi (w tym idempotency_token), należy zwrócić tę samą odpowiedź CreateBookingResponse. Druga rezerwacja nie zostanie utworzona, a użytkownik, w odpowiednich przypadkach, zostanie obciążony opłatą tylko raz. Pamiętaj, że jeśli próba utworzenia rezerwacji się nie powiedzie, backend partnera powinien spróbować ponownie, 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

Wywołania z Centrum działań do Twojego backendu muszą być zabezpieczone za pomocą protokołu SSL/TLS z użyciem wzajemnego uwierzytelniania klienta/serwera opartego na certyfikatach. Wymaga to użycia prawidłowego certyfikatu serwera dla 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ą łańcucha certyfikatów, który prowadzi do certyfikatu głównego. Najłatwiej to zrobić, dołączając certyfikaty pośrednie dostarczone przez dostawcę usług hostingowych partnera w formacie PEM do certyfikatu serwera (również w formacie PEM).

Certyfikat serwera jest weryfikowany w momencie nawiązywania połączenia. Nie są akceptowane certyfikaty podpisane samodzielnie. Dopóki certyfikat jest ważny, nie sprawdzamy treści certyfikatu. Aby sprawdzić ważność certyfikatu, użyj tego polecenia:

echo "" | openssl s_client  -connect YOUR_URL:YOUR_PORT  -showcerts -CApath /etc/ssl/certs

Certyfikat klienta: aby uwierzytelnić nas (Google) przed partnerem, przesyłamy certyfikat klienta wydany przez urząd certyfikacji Google Internet Authority G2 (certyfikat CA) z tymi właściwościami:

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. Możesz pobrać ten zestaw zaufanych źródeł z autorytetu, takiego jak Mozilla, lub zainstalować zbiór źródeł zalecany obecnie przez Google Internet Authority G2. W obu przypadkach czasami konieczne może być ręczne aktualizowanie certyfikatów głównych.

Wdrażanie protokołu kontroli stanu gRPC

Wdrożyć 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 kontroli stanu 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. Sprawdzanie stanu powinno być wykonywane pod tym samym adresem URL i na tym samym PORT-cie co inne punkty końcowe.

Inne wersje

Dokumentację innych wersji interfejsu API znajdziesz na tych stronach: * API v3 * API v0