La configurazione di un server di prenotazione da parte tua consentirà ad Actions Center di creare appuntamenti/prenotazioni con te per conto dell'utente.
Implementa un'interfaccia API basata su gRPC
Nota: tutti i nuovi partner devono utilizzare l'interfaccia API REST anziché l'API gRPC.
Implementa un'interfaccia API basata su gRPC. Ciò consente a Google di inviare richieste di prenotazione. La superficie API è definita utilizzando l'IDL basato su protobuf di gRPC.
Chiediamo ai nostri nuovi partner di implementare un insieme consigliato di API v2. I partner possono selezionare l'URL e la porta più adatti alla loro infrastruttura.
Questa sezione introduce un insieme consigliato di API v2. Si applica ai partner che non hanno implementato l'API v0. I nostri partner attuali che hanno implementato l'API v0 possono contattare il Centro azioni per saperne di più.
Scarica la definizione del servizio in formato proto di seguito per iniziare con l'implementazione dell'API.
Scarica la definizione del servizio
Risorse API
Acquisisci familiarità con i seguenti tipi di risorse che verranno utilizzati in questa implementazione:
- Slot: uno slot dell'inventario
- Prenotazione: appuntamento per uno spazio dell'inventario
Metodi
I seguenti metodi API sono obbligatori per l'implementazione sul tuo lato per il server gRPC:
Questi 5 metodi definiscono il set richiesto di 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) {}
}
Flusso: crea una prenotazione
Quando crei una prenotazione, Google invia al partner il nome, il cognome, il numero di telefono e l'indirizzo email dell'utente. Dal punto di vista del partner, questo deve essere considerato un pagamento come ospite, in quanto il Centro azioni non ha modo di cercare l'account dell'utente nel sistema del partner. La prenotazione finale deve essere mostrata ai commercianti del partner nel loro sistema proprio come le prenotazioni che provengono dal sistema di prenotazione del partner.
Implementazione dello scheletro in Java
Per iniziare, forniamo un server gRPC scheletrico in Java che può essere compilato e installato. Consulta la sezione Esempi > Implementazione di riferimento gRPC. Questo server ha implementato metodi gRPC necessari per supportare l'integrazione, inclusi l'autenticazione e il servizio di monitoraggio dell'integrità.
Requisiti
Errore gRPC ed errore della logica di business
Quando un backend partner gestisce le richieste gRPC, possono verificarsi due tipi di errori: errori imprevisti derivanti da dati errati ed errori di logica di business che indicano l'impossibilità di creare o aggiornare una prenotazione (vedi Errore di prenotazione), ad esempio se lo slot richiesto non è disponibile.
Gli errori imprevisti, se rilevati, devono essere restituiti al client utilizzando i codici di errore gRPC canonici. Di seguito sono riportati alcuni esempi:
- INVALID_ARGUMENT viene utilizzato nelle RPC come CheckAvailability e CreateLease e deve essere restituito se lo slot fornito contiene informazioni non valide.
- NOT_FOUND viene utilizzato nelle RPC come CreateBooking e ListBookings e deve essere restituito se l'identificatore fornito non è noto al partner.
Consulta il riferimento di ogni metodo per i relativi codici di errore gRPC canonici o l'elenco completo dei codici di stato.
Al contrario, gli errori di logica di business devono essere acquisiti in Booking Failure e restituiti nella risposta RPC. È possibile riscontrare errori della logica di business durante la creazione o l'aggiornamento di una risorsa, ad esempio nella gestione delle RPC CreateBooking e UpdateBooking. Di seguito sono riportati alcuni esempi:
- SLOT_UNAVAILABLE viene utilizzato se lo slot richiesto non è più disponibile.
- PAYMENT_ERROR_CARD_TYPE_REJECTED viene utilizzato se il tipo di carta di credito fornito non è accettato.
Idempotenza
La comunicazione sulla rete non è sempre affidabile e Google Reserve potrebbe riprovare le RPC se non viene ricevuta alcuna risposta. Per questo motivo, tutte le RPC che modificano lo stato (CreateBooking, UpdateBooking) devono essere idempotenti. I messaggi di richiesta per questi RPC includono token di idempotenza per identificare in modo univoco la richiesta e consentire al partner di distinguere tra un RPC ripetuto (con l'intenzione di creare una singola prenotazione) e due prenotazioni separate.
Di seguito sono riportati alcuni esempi:
- Una risposta RPC
CreateBooking
andata a buon fine include la prenotazione creata e, in alcuni casi, il pagamento viene
elaborato nell'ambito del flusso di prenotazione. Se la stessa identica CreateBookingRequest
viene ricevuta una seconda volta (incluso
idempotency_token), deve essere restituita la stessa CreateBookingResponse. Non viene creata una seconda prenotazione e all'utente, se applicabile, viene addebitato l'importo esattamente una volta. Tieni presente che se un tentativo di CreateBooking non va a buon fine, il backend del partner deve riprovare se viene inviata di nuovo la stessa richiesta.
Il requisito di idempotenza si applica a tutti i metodi che contengono token di idempotenza.
Sicurezza e autenticazione del server gRPC
Le chiamate dal Centro azioni al tuo backend devono essere protette utilizzando SSL/TLS con autenticazione reciproca client/server basata su certificati. Ciò richiede l'utilizzo di un certificato server valido per l'implementazione di gRPC e l'accettazione di un certificato client valido.
Certificato server:il server partner deve essere dotato di un certificato server valido associato al nome di dominio del server (consulta questo elenco delle CA radice accettate). Le implementazioni del server GRPC prevedono di pubblicare una catena di certificati che porta al certificato radice. Il modo più semplice per farlo è aggiungere i certificati intermedi forniti dall'host web del partner in formato PEM al certificato del server (anch'esso in formato PEM).
Il certificato del server viene verificato al momento della connessione e i certificati autofirmati non vengono accettati. Il contenuto effettivo del certificato non viene controllato finché il certificato è valido. Puoi controllare la validità del certificato tramite il seguente comando:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Certificato client:per autenticarci (come Google) presso il partner, forniamo un certificato client emesso da Google Internet Authority G2 (certificato CA) con le seguenti proprietà:
| Campo | Valore |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
I tentativi di connessione senza questo certificato client devono essere rifiutati dal server partner.
Per convalidare il certificato client, il server si basa su un insieme di certificati root client attendibili. Puoi scegliere di ottenere questo insieme di radici attendibili da un'autorità come Mozilla o installare l'insieme di radici attualmente consigliato da Google Internet Authority G2. In entrambi i casi, a volte potresti dover aggiornare manualmente i certificati root.
Implementa il protocollo di controllo di integrità gRPC
Implementa il protocollo di controllo di integrità GRPC.
Questo protocollo consente a Google di monitorare lo stato del backend dell'implementazione gRPC. La specifica
del servizio
fa parte della distribuzione GRPC. Seguendo la convenzione di denominazione GRPC, il nome
del servizio nelle chiamate di controllo dell'integrità è
ext.maps.booking.partner.v2.BookingService per l'API v2 o
ext.maps.booking.partner.v0.BookingService per l'API v0. Il controllo di integrità deve
essere eseguito sullo stesso URL e sulla stessa porta degli altri endpoint.
Altre versioni
Per la documentazione di altre versioni dell'API, consulta le seguenti pagine: * API v3 * API v0