La configurazione di un server di prenotazione da parte tua consentirà ad Actions Center di creare appuntamenti/prenotazioni per tuo conto 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. In questo modo Google può inviare richieste di prenotazione. L'interfaccia API viene 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 la versione 0 dell'API. Per i nostri partner attuali che hanno implementato l'API v0, contatta 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 di inventario
- Prenotazione: appuntamento per uno spazio per l'inventario
Metodi
I seguenti metodi API sono obbligatori da implementare per il server gRPC:
Questi 5 metodi definiscono l'insieme richiesto di RPC di 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 viene creata 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, questa operazione deve essere considerata come un pagamento senza registrazione, poiché 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, così come le prenotazioni che provengono dal sistema di prenotazione del partner.
Implementazione di uno scheletro in Java
Per iniziare, forniamo un server gRPC scheletro in Java che può essere compilato e installato. Dai un'occhiata alla sezione Samples > gRPC Reference Implementation. Questo server ha sostituito i metodi gRPC necessari per supportare l'integrazione, tra cui l'autenticazione e il servizio di assistenza.
Requisiti
Errore gRPC ed errore di 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 aziendale che indicano l'impossibilità di creare o aggiornare una prenotazione (vedi Errore di prenotazione), ad esempio se lo spazio richiesto non è disponibile.
Gli errori imprevisti, se rilevati, devono essere restituiti al client utilizzando codici di errore gRPC canonici. Di seguito sono riportati alcuni esempi:
- INVALID_ARGUMENT viene utilizzato in 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 è sconosciuto al partner.
Consulta il riferimento di ciascun metodo per i relativi codici di errore gRPC canonici o consulta l'elenco completo dei codici di stato.
Al contrario, gli errori di logica di business devono essere rilevati in Booking Failure e restituito nella risposta RPC. È possibile che si verifichino errori di logica di business durante la creazione o l'aggiornamento di una risorsa, ad esempio nella gestione delle RPC CreateBooking e UpdatingBooking. 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.
Identità
La comunicazione sulla rete non è sempre affidabile e Google Reserve potrebbe ritentare le chiamate RPC se non riceve risposta. Per questo motivo, tutte le chiamate RPC che modificano lo stato (CreateBooking, UpdateBooking) devono essere idempotenti. I messaggi di richiesta per queste RPC includono token di idempotency per identificare in modo univoco la richiesta e consentire al partner di distinguere tra una RPC ripetuta (con l'intento di creare una singola prenotazione) e due prenotazioni distinte.
Di seguito sono riportati alcuni esempi:
- Una risposta RPC CreateBooking riuscita include la prenotazione creata e, in alcuni casi, il pagamento viene elaborato nell'ambito del flusso di prenotazione. Se lo stesso CreateBookingRequest viene ricevuto una seconda volta (incluso
idempotency_token), deve essere restituito lo stesso CreateBookingResponse. Non viene creata una seconda prenotazione e all'utente, se applicabile, viene addebitato esattamente un importo. Tieni presente che se un tentativo di creazione di una prenotazione non va a buon fine, il backend del partner deve riprovare se la stessa richiesta viene inviata di nuovo.
Il requisito di iridempibilità si applica a tutti i metodi che contengono token di iridempibilità.
Sicurezza e autenticazione del server gRPC
Le chiamate dal Centro azioni al tuo backend devono essere protette utilizzando SSL/TLS con autenticazione client/server reciproca basata su certificato. Ciò richiede l'uso di un certificato server valido per l'implementazione di gRPC e l'accettazione di un certificato client valido.
Certificato del server: il server partner deve essere dotato di un certificato del server valido associato al nome di dominio del server (consulta questo elenco di CA radice accettate). Le implementazioni del server GRPC si aspettano di fornire una catena di certificati che porti al certificato principale. Il modo più semplice per farlo è aggiungendo i certificati intermedi forniti dall'host web del partner in formato PEM al certificato del server (anche in formato PEM).
Il certificato del server viene verificato al momento della connessione e i certificati autofirmati non sono accettati. I contenuti effettivi del certificato non vengono controllati se il certificato è valido. Puoi verificare la validità del tuo 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) al partner, forniamo un certificato client emesso dall'autorità di internet di Google 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 radice client attendibili. Puoi scegliere di ottenere questo insieme di chiavi radice attendibili da un'autorità come Mozilla o installare l'insieme di chiavi radice attualmente consigliato dall'autorità di internet di Google G2. In entrambi i casi, a volte potrebbe essere necessario aggiornare manualmente i certificati principali.
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 di backend dell'implementazione gRPC. La specifica del servizio fa parte della distribuzione GRPC. In base alla 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