La configurazione di un server di prenotazione sul tuo sistema consentirà al Centro azioni di creare appuntamenti / prenotazioni / prenotazioni con te per conto dell'utente.
Implementare un'interfaccia API basata su gRPC
Nota: tutti i nuovi partner devono utilizzare l'interfaccia dell'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 viene definita utilizzando l'IDL basato su protobuf di gRPC.
Chiediamo ai nostri nuovi partner di implementare un set consigliato di API v2. I partner possono selezionare l'URL e la PORTA più adatti alla loro infrastruttura.
Questa sezione introduce un set consigliato di API v2. Si applica ai partner che non hanno implementato l'API v0. Per i nostri attuali partner 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 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: un'area dell'inventario
- Prenotazione: nomina per uno spazio pubblicitario
Metodi
I seguenti metodi API sono obbligatori per l'implementazione sul tuo lato per il server gRPC:
Questi cinque metodi definiscono l'insieme 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: creare una prenotazione
Quando crei una prenotazione, Google invia al partner nome, cognome, numero di telefono e indirizzo email dell'utente. Questo dovrebbe essere considerato come un pagamento senza registrazione dal punto di vista del partner 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, proprio come le prenotazioni per il sistema di prenotazione del partner.
Implementazione di scheletri in Java
Per iniziare, forniamo uno schema di server gRPC in Java che può essere compilato e installato. Scoprilo nella sezione Samples > gRPC Reference Implementation (Esempi di implementazione di riferimento gRPC). Questo server ha eliminato i metodi gRPC necessari per supportare l'integrazione, inclusi autenticazione e servizio di integrità.
Requisiti
Errore gRPC ed errore della logica di business
Quando il backend di un partner gestisce le richieste gRPC, possono verificarsi due tipi di errori: errori imprevisti dovuti a dati errati e errori della 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 riscontrati, devono essere restituiti al client utilizzando i codici di errore canonici gRPC. Tra gli esempi vi sono, a titolo esemplificativo:
- INVALID_ARGUMENT è utilizzato in RPC come CheckAvailability e CreateLease e deve essere restituito se lo slot fornito contiene informazioni non valide.
- NOT_FOUND viene utilizzato in RPC come CreateBooking e ListBookings e dovrebbe essere restituito se l'identificatore fornito non è noto al partner.
Consulta il riferimento di ciascun metodo per i relativi codici di errore canonici gRPC o consulta l'elenco completo dei codici di stato.
Al contrario, gli errori della logica di business devono essere acquisiti in Errore di prenotazione e restituiti nella risposta RPC. Potrebbero verificarsi errori di logica di business durante la creazione o l'aggiornamento di una risorsa, ad esempio durante la gestione di RPC CreateBooking e UpdatesBooking. Tra gli esempi vi sono, a titolo esemplificativo:
- 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 viene accettato.
Idempotenza
La comunicazione sulla rete non è sempre affidabile e Google Reserve potrebbe ritentare le RPC se non viene ricevuta alcuna risposta. Per questo motivo, tutte le RPC con mutazione di stato (CreateBooking, UpdateBooking) devono essere idempotenti. I messaggi di richiesta per queste RPC includono token di idempotenza per identificare in modo univoco la richiesta e consentire al partner di distinguere tra una RPC oggetto di un nuovo tentativo (con l'intento di creare una singola prenotazione) e due prenotazioni separate.
Tra gli esempi vi sono, a titolo esemplificativo:
- Una risposta RPC
CreateBooking
efficace include la prenotazione creata e, in alcuni casi, il pagamento viene
elaborato nell'ambito del flusso di prenotazione. Se la stessa CreateBookingRequest
viene ricevuta una seconda volta (incluso
idempotency_token), deve essere restituita la stessa CreateBookingResponse. Non viene creata una seconda prenotazione e l'utente, se applicabile, viene addebitato esattamente una volta. Tieni presente che se un tentativo di CreateBooking non va a buon fine, il backend del partner dovrebbe riprovare se la stessa richiesta viene inviata di nuovo.
Il requisito di idempotenza si applica a tutti i metodi che contengono token di idempotenza.
Sicurezza e autenticazione di server gRPC
Le chiamate dal Centro azioni al backend devono essere protette tramite SSL/TLS con autenticazione client/server reciproca basata su certificati. Ciò richiede l'utilizzo di un certificato server valido per l'implementazione gRPC e l'accettazione di un certificato client valido.
Certificato del server: il server partner deve essere dotato di un certificato server valido associato al nome di dominio del server (consulta questo elenco di CA radice accettate). Le implementazioni dei server GRPC prevedono di pubblicare una catena di certificati che porta al certificato radice. Il modo più semplice per raggiungere questo obiettivo è aggiungere al certificato del server (anche in formato PEM) i certificati intermedi forniti dall'host web del partner 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 finché il certificato è valido. Puoi verificare la validità del certificato utilizzando il seguente comando:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Certificato client: per autenticarci (in qualità di Google) con 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 radice client attendibili. Puoi scegliere di ottenere questo insieme di certificati radice attendibili da un'autorità come Mozilla o installare il set di certificati radice attualmente consigliato da Google Internet Authority G2. In entrambi i casi, potrebbe essere necessario aggiornare manualmente i certificati radice a volte.
Implementa il protocollo per il controllo di integrità gRPC
Implementa il protocollo per il 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 di 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à dovrebbe essere eseguito sullo stesso URL e sulla stessa PORTA degli altri endpoint.
Altre versioni
Per la documentazione relativa ad altre versioni dell'API, consulta le seguenti pagine: * API v3 * API v0