Implementacja serwera rezerwacji: interfejs API w wersji 2

Skonfigurowanie po swojej stronie serwera rezerwacji umożliwia Centrum działań tworzyć u Ciebie spotkania, rezerwacje lub rezerwacje w imieniu użytkownika.

Wdrażanie interfejsu API opartego na gRPC

Uwaga: wszyscy nowi partnerzy powinni używać interfejsu API REST zamiast gRPC API.

Zaimplementować interfejs API oparty na gRPC. Pozwoli to Google wysyłać prośby o rezerwację. Interfejs API jest zdefiniowana za pomocą protokołu gRPC opartego na IDL.

Prosimy naszych nowych partnerów o wdrożenie zalecanego zestawu interfejsów API w wersji 2. Partnerzy mogą wybierz URL i PORT, które najlepiej odpowiadają ich infrastrukturze.

W tej sekcji przedstawiamy zalecany zestaw interfejsów API w wersji 2. Dotyczy partnerów, którzy nie zaimplementowano interfejsu API w wersji 0. Dla naszych obecnych partnerów, którzy wdrożyli interfejs API v0, aby dowiedzieć się więcej, skontaktuj się z Centrum działań.

Pobierz poniżej definicję usługi w formacie proto, aby zacząć korzystać z wdrożenia interfejsu API.

Pobierz usługę definicja

Zasoby interfejsu API

Zapoznaj się z podanymi niżej typami zasobów, używane w tej implementacji:

  • Przedział: zasoby reklamowe. gniazdo
  • Rezerwacja: spotkanie dotyczące przedziału zasobów reklamowych

Metody

Podane niżej metody interfejsu API są wymagane, aby móc je zaimplementować po Twojej stronie Serwer gRPC:

Te 5 metod określa wymagany zestaw 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: boks

Podczas tworzenia rezerwacji Google wyśle partnerowi imię i nazwisko użytkownika, nazwisko, numer telefonu i adres e-mail. Należy to traktować jako z punktu widzenia partnera, ponieważ w Centrum działań nie ma aby wyszukać konto użytkownika w systemie partnera. Ostateczna rezerwacja powinny być wyświetlane w systemie sprzedawcom partnera, tak jak w przypadku rezerwacji. z systemu rezerwacji partnera.

Implementacja szkieletu w Javie

Na początek udostępniamy szkieletowy serwer gRPC w Javie, który można skompilować i zainstalowano. Sprawdź w Sample > Implementacja referencyjna gRPC . Ten serwer skrócił metody gRPC potrzebne do obsługi integrację, w tym uwierzytelnianie i usługę 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; błędów logicznych i logiki biznesowej, wskazywać brak możliwości utworzenia lub zaktualizowania rezerwacji (patrz Rezerwacja błąd), np. jeśli żądany przedział jest niedostępny.

Nieoczekiwane błędy (jeśli wystąpią) powinny zostać zwrócone do klienta za pomocą tagu kanoniczne kody błędów gRPC. Przykłady (lista nie jest pełna):

  • Błędna wartość jest używana w wywołaniach RPC, takich jak CheckAvailability i CreateLease, i powinien zostać zwrócony, jeśli podany przedział zawiera nieprawidłowe informacje.
  • NOT_FOUND jest używany w RPC, takich jak CreateBooking i ListBookings, i powinien zwracany, jeśli podany identyfikator jest nieznany partnerowi.

Zapoznaj się z dokumentacją poszczególnych metod, aby poznać ich kanoniczne kody błędów gRPC, lub zapoznaj się z pełnym listę kodów stanu.

Wręcz przeciwnie, błędy logiki biznesowej powinny być ujęte w sekcji Rezerwacje. Błąd oraz w odpowiedzi RPC. Podczas tworzenia mogą wystąpić błędy logiki biznesowej lub zaktualizowanie zasobu, tj. w ramach obsługi RPC CreateBooking oraz Aktualizuję rezerwację. Przykłady (lista nie jest pełna):

  • Jeśli żądany przedział nie jest już dostępny, używany jest SLOT_UNAVAILABLE.
  • Karta kredytowa PAYMENT_ERROR_CARD_TYPE_REJECTED jest używana, jeśli podany typ karty kredytowej to nie zaakceptowano.

Idempotentność

Komunikacja przez sieć nie zawsze jest niezawodna, a Google Reserve może ponawianie wywołań RPC, jeśli nie otrzymano żadnej odpowiedzi. Z tego powodu wszystkie RPC, które mutują, stan (CreateBooking, UpdateBooking) musi być idempotentny. Poproś o wiadomości dla: obejmują tokeny idempotentności, które pozwalają jednoznacznie partnera, aby rozróżnić ponawiany RPC (z zamiarem utworzenia pojedynczą rezerwację) i 2 osobne rezerwacje.

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

  • Zakończone powodzeniem RPC CreateBooking odpowiedź obejmuje utworzoną rezerwację, a w niektórych przypadkach płatność jest przetwarzane w ramach procesu rezerwacji. Jeśli to samo żądanie CreateBookingRequest otrzymano drugi raz (łącznie z idempotency_token), a następnie taki sam Wartość CreateBookingResponse musi zostać zwrócona. nie zostanie utworzona druga rezerwacja, użytkownik jest obciążany płatnością dokładnie raz. 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.

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

Zabezpieczenia i uwierzytelnianie serwera gRPC

Połączenia z Centrum działań dotyczące Twojego backendu muszą być zabezpieczone za pomocą protokołu SSL/TLS oparte na certyfikacie wzajemne uwierzytelnianie klient-serwer. Wymaga to parametru użycie ważnego certyfikatu serwera w implementacji gRPC i akceptowanie ważny certyfikat klienta.

Certyfikat serwera: serwer partnera musi mieć prawidłowy atrybut certyfikat serwera powiązany z nazwą domeny serwera (zapoznaj się z tym listę akceptowanych głównych urzędów certyfikacji). Implementacje serwera GRPC spodziewają się obsługi łańcucha certyfikatów prowadzącego do certyfikat główny. Najłatwiej to zrobić, dołączając do certyfikatów pośrednich dostarczanych przez dostawcę hostingu witryn partnera w formacie PEM certyfikat serwera (również w formacie PEM).

Certyfikat serwera jest weryfikowany w momencie połączenia i podpisany samodzielnie certyfikaty nie są akceptowane. Rzeczywista treść certyfikatu nie jest sprawdzana jako dopóki certyfikat jest ważny. Ważność 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 (jako Google) u partnera, udostępniamy certyfikat klienta wystawiony przez Google Internet Authority G2 (CA ) za pomocą tych właściwości:

Pole Wartość
CN mapsbooking.businesslink-3.net
SAN DNS:mapsbooking.businesslink-3.net

Próby nawiązania połączenia bez tego certyfikatu klienta powinny być odrzucane przez serwera partnera.

Do weryfikowania certyfikatu klienta serwer używa zbioru zaufanego klienta certyfikatów głównych. Ten zbiór zaufanych certyfikatów głównych możesz uzyskać z organizacji takich jak Mozilla lub zainstaluj zestaw katalogów głównych zalecanych obecnie przez internet Google Urząd G2. W obu może być jednak konieczne ręczne aktualizowanie certyfikatów głównych.

Wdrażanie protokołu kontroli stanu gRPC

Wdróż kontrolę stanu GRPC Protokół. Ten protokół umożliwia Google monitorowanie stanu backendu Twojego gRPC implementacji. Usługa specyfikacja jest częścią dystrybucji GRPC. Zgodnie z konwencją nazewnictwa GRPC nazwa usługi w wywołaniach kontroli stanu jest ext.maps.booking.partner.v2.BookingService w przypadku interfejsu API w wersji 2 lub ext.maps.booking.partner.v0.BookingService dla interfejsu API w wersji 0. Kontrola stanu powinna są uruchamiane z użyciem tego samego adresu URL i portu PORT co inne punkty końcowe.

Inne wersje

Dokumentację innych wersji interfejsu API znajdziesz na tych stronach: * Interfejs API w wersji 3 * Interfejs API w wersji 0