Implementacja serwera rezerwacji: interfejs API w wersji 2

Skonfigurowanie serwera rezerwacji po swojej stronie umożliwi Centrum działań tworzenie spotkań, rezerwacji i rezerwacji w imieniu użytkownika.

Implementowanie interfejsu API opartego na gRPC

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

Zaimplementować interfejs API na podstawie gRPC. Pozwoli to Google wysyłać prośby o rezerwację. Powierzchnia interfejsu API jest określana za pomocą IDL protokołu gRPC.

Prosimy naszych nowych partnerów o wdrożenie zalecanego zestawu interfejsów API w wersji 2. Partnerzy mogą wybrać ten adres URL i PORT, który najlepiej pasuje do ich infrastruktury.

W tej sekcji omawiamy zalecany zestaw interfejsów API w wersji 2. Dotyczy to partnerów, którzy nie wdrożyli jeszcze interfejsu API w wersji 0. Aktualni partnerzy, którzy wdrożyli interfejs API w wersji 0, powinni skontaktować się z Centrum działań, aby dowiedzieć się więcej.

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

Pobierz definicję 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 wymagane są następujące metody interfejsu API:

Tych 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

Rysunek 1. Tworzenie rezerwacji z przedziału

Podczas tworzenia rezerwacji Google wysyła partnerowi imię i nazwisko, nazwisko, numer telefonu i adres e-mail użytkownika. Z perspektywy partnera powinno to być traktowane jako gość, ponieważ Centrum działań nie ma możliwości sprawdzenia konta użytkownika w systemie partnera. Ostateczna rezerwacja powinna być wyświetlana w systemie sprzedawcom partnera tak samo jak rezerwacja przyszła do systemu rezerwacji partnera.

Implementacja szkieletu w Javie

Na początek udostępniamy szkieletowy serwer gRPC w Javie, który można skompilować i zainstalować. Możesz to sprawdzić w sekcji Przykłady > Implementacja referencyjna gRPC. Ten serwer wycofał metody gRPC, które są niezbędne do obsługi integracji, w tym metody uwierzytelniania i kontroli stanu.

Wymagania

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

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

Nieoczekiwane błędy powinny zostać zwrócone do klienta za pomocą kanonicznych kodów błędów gRPC. Przykłady (lista nie jest pełna):

  • Wartość Część IARC jest używana w wywołaniach RPC, takich jak CheckAvailability i CreateLease i należy ją zwracać, jeśli podany przedział zawiera nieprawidłowe informacje.
  • Wartość NOT_FOUND jest używana w wywołaniach RPC, takich jak CreateBooking i ListBookings. Należy ją zwrócić, jeśli podany identyfikator jest nieznany partnerowi.

W opisie poszczególnych metod znajdziesz ich kanoniczne kody błędów gRPC lub pełna lista kodów stanu.

W przeciwnym razie błędy w logice biznesowej powinny być rejestrowane w polu Błąd rezerwacji i zwracane w odpowiedzi RPC. Podczas tworzenia lub aktualizowania zasobu mogą wystąpić błędy w logice biznesowej, np. przy obsłudze RPC CreateBooking i Aktualizowanie rezerwacji. Przykłady (lista nie jest pełna):

  • Jeśli żądany przedział nie jest już dostępny, używana jest wartość SLOT_UNAVAILABLE.
  • Jeśli podany rodzaj karty kredytowej nie jest akceptowany, używany jest PAYMENT_ERROR_CARD_TYPE_REJECTED.

Idempotentność

Komunikacja przez sieć nie zawsze jest niezawodna, a jeśli nie otrzymano odpowiedzi, Google Reserve może ponowić próbę wykonania RPC. Z tego powodu wszystkie RPC, które zmieniają stan (CreateBooking, UpdateBooking), muszą być idempotentne. Komunikaty żądań dla tych RPC zawierają tokeny idempotentności, które pozwalają partnerowi odróżnić żądanie RPC (z zamiarem utworzenia pojedynczej rezerwacji) i 2 osobne rezerwacje.

Przykłady (lista nie jest pełna):

  • Udana odpowiedź RPC CreateBooking obejmuje utworzoną rezerwację, a w niektórych przypadkach płatność jest przetwarzana w ramach procesu rezerwacji. Jeśli ta sama wartość CreateBookingRequest zostanie otrzymana drugi raz (z uwzględnieniem atrybutu idempotency_token), musi zostać zwrócona ta sama wartość CreateBookingResponse. Nie jest tworzona druga rezerwacja, a użytkownik zostaje obciążony dokładnie raz (w odpowiednich przypadkach). Jeśli próba utworzenia rezerwacji nie powiedzie się, backend partnera powinien ponowić próbę, gdy to samo żądanie zostanie wysłane ponownie.

Wymagania dotyczące idempotentności mają zastosowanie do wszystkich metod, które zawierają tokeny idempotentności.

Zabezpieczenia i uwierzytelnianie serwera gRPC

Połączenia z Centrum działań do backendu muszą być zabezpieczone protokołem SSL/TLS z opartym na certyfikacie wzajemnym uwierzytelnianiem klienta/serwera. Wymaga to użycia prawidłowego certyfikatu serwera do implementacji gRPC oraz akceptowania prawidłowego certyfikatu klienta.

Certyfikat serwera: serwer partnera musi być wyposażony w ważny certyfikat serwera powiązany z nazwą domeny serwera (zapoznaj się z tą listą zaakceptowanych głównych urzędów certyfikacji). Implementacje serwerów GRPC powinny obsługiwać łańcuch certyfikatów prowadzący do certyfikatu głównego. Najłatwiejszym sposobem, aby to zrobić, jest dołączenie do certyfikatu serwera (również w formacie PEM) certyfikatów pośrednich dostarczonych przez dostawcę hostingu witryn partnera w formacie PEM.

Certyfikat serwera jest weryfikowany podczas połączenia, a samodzielnie podpisane certyfikaty nie są akceptowane. Zawartość certyfikatu nie jest sprawdzana, o ile jest on ważny. Aby sprawdzić poprawność certyfikatu, użyj tego polecenia:

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

Certyfikat klienta: aby uwierzytelnić nas (jako Google) u partnera, dostarczamy certyfikat klienta wydany przez urząd 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.

Do weryfikowania certyfikatu klienta serwer używa zestawu zaufanych certyfikatów głównych klienta. Możesz uzyskać taki zestaw zaufanych certyfikatów głównych od instytucji takiej jak Mozilla lub zainstalować zestaw certyfikatów aktualnie zalecanych przez urząd internetowy Google G2. W obu przypadkach może być konieczna ręczna aktualizacja certyfikatów głównych.

Wdrażanie protokołu kontroli stanu gRPC

Zaimplementuj protokoł kontroli stanu GRPC. Ten protokół umożliwia Google monitorowanie stanu backendu implementacji gRPC. Specyfikacja usługi wchodzi w skład rozkładu GRPC. Zgodnie z konwencją nazewnictwa GRPC nazwa usługi w wywołaniach kontroli stanu to ext.maps.booking.partner.v2.BookingService dla interfejsu API v2 lub ext.maps.booking.partner.v0.BookingService dla interfejsu API v0. Kontrola stanu powinna być przeprowadzana z tym samym adresem URL i portem co inne punkty końcowe.

Inne wersje

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