Configurer un serveur de réservation de votre côté permettra au centre d'actions de créer des rendez-vous/réservations auprès de votre établissement au nom de l'utilisateur.
Implémenter une interface API basée sur gRPC
Remarque: Tous les nouveaux partenaires doivent utiliser l'interface de l'API REST plutôt que l'API gRPC.
Implémentez une interface API basée sur gRPC. Google pourra alors envoyer des demandes de réservation. La surface de l'API est définie à l'aide de l'IDL basé sur protobuf de gRPC.
Nous demandons à nos nouveaux partenaires de mettre en œuvre un ensemble recommandé de l'API v2. Les partenaires peuvent sélectionner l'URL et le port les plus adaptés à leur infrastructure.
Cette section présente un ensemble recommandé d'API v2. Elle s'applique aux partenaires qui n'ont pas implémenté l'API v0. Pour en savoir plus sur nos partenaires actuels qui ont implémenté la version 0 de l'API, veuillez contacter le Centre d'actions.
Téléchargez la définition du service au format proto ci-dessous pour commencer à implémenter l'API.
Télécharger la définition du service
Ressources de l'API
Veuillez vous familiariser avec les types de ressources suivants qui seront utilisés dans cette implémentation:
- Slot: créneau d'inventaire
- Réservation : rendez-vous pris dans un créneau d'inventaire
Méthodes
Les méthodes d'API suivantes doivent être implémentées de votre côté pour le serveur gRPC:
Ces cinq méthodes définissent l'ensemble requis de 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) {}
}
Flux : créer une réservation
Lors de la création d'une réservation, Google envoie au partenaire le nom, le prénom, le numéro de téléphone et l'adresse e-mail de l'utilisateur. Du point de vue du partenaire, cette opération doit être traitée comme un paiement sans connexion, car le Centre des actions ne peut pas accéder au compte de l'utilisateur dans le système du partenaire. La réservation finale doit s'afficher dans le système des marchands du partenaire, comme les réservations provenant de son système de réservation.
Implémentation de squelettes en Java
Pour commencer, nous fournissons un squelette de serveur gRPC en Java qui peut être compilé et installé. Consultez-le dans la section Samples > gRPC Reference Implementation (Exemples > Implémentation de référence gRPC). Ce serveur a remplacé les méthodes gRPC nécessaires à l'intégration, y compris l'authentification et le service de santé.
Conditions requises
Erreur gRPC et erreur de logique métier
Deux types d'erreurs peuvent se produire lorsqu'un backend partenaire gère des requêtes gRPC : des erreurs inattendues provenant de données incorrectes et des erreurs de logique métier indiquant l'impossibilité de créer ou de mettre à jour une réservation (voir Échec de la réservation), par exemple si le créneau demandé n'est pas disponible.
Les erreurs inattendues, le cas échéant, doivent être renvoyées au client à l'aide de codes d'erreur gRPC canoniques. Cela inclut, sans s'y limiter, les signaux suivants :
- INVALID_ARGUMENT est utilisé dans les RPC telles que CheckAvailability et CreateLease, et doit être renvoyé si l'emplacement fourni contient des informations non valides.
- NOT_FOUND est utilisé dans les RPC telles que CreateBooking et ListBookings, et doit être renvoyé si le partenaire ne reconnaît pas l'identifiant fourni.
Consultez la documentation de référence de chaque méthode pour connaître ses codes d'erreur gRPC canoniques ou la liste complète des codes d'état.
À l'inverse, les erreurs de logique métier doivent être capturées dans BookingFailure et renvoyées dans la réponse RPC. Des erreurs de logique métier peuvent se produire lors de la création ou de la mise à jour d'une ressource, c'est-à-dire lors de la gestion des RPC CreateBooking et UpdatingBooking. Cela inclut, sans s'y limiter, les signaux suivants :
- SLOT_UNAVAILABLE est utilisé si le créneau demandé n'est plus disponible.
- PAYMENT_ERROR_CARD_TYPE_REJECTED est utilisé si le type de carte de crédit fourni n'est pas accepté.
Idempotence
La communication sur le réseau n'est pas toujours fiable. Google Reserve peut retenter les requêtes RPC si aucune réponse n'est reçue. Par conséquent, toutes les RPC qui modifient l'état (CreateBooking, UpdateBooking) doivent être idempotentes. Les messages de requête pour ces RPC incluent des jetons d'idempotence pour identifier de manière unique la requête et permettre au partenaire de faire la distinction entre un RPC réessayé (dont l'intention est de créer une seule réservation) et deux réservations distinctes.
Cela inclut, sans s'y limiter, les signaux suivants :
- Une réponse RPC CreateBooking positive inclut la réservation créée. Dans certains cas, le paiement est traité pendant le processus de réservation. Si exactement la même requête CreateBookingRequest est reçue une deuxième fois (y compris
idempotency_token), c'est la même réponse CreateBookingResponse qui doit alors être renvoyée. Une deuxième réservation n'est pas créée, et l'utilisateur n'est facturé qu'une seule fois (le cas échéant). Notez que si une tentative de création de réservation échoue, le backend du partenaire doit retenter si la même requête est renvoyée.
La condition d'idempotence s'applique à toutes les méthodes contenant des jetons d'idempotence.
Sécurité et authentification du serveur gRPC
Les appels du Centre d'actions vers votre backend doivent être sécurisés à l'aide de SSL/TLS avec une authentification client/serveur mutuelle basée sur des certificats. Pour ce faire, vous devez utiliser un certificat de serveur valide pour votre implémentation gRPC et accepter un certificat client valide.
Certificat de serveur:le serveur partenaire doit être équipé d'un certificat de serveur valide associé au nom de domaine du serveur (consultez cette liste des autorités de certification racine acceptées). Les implémentations de serveurs GRPC s'attendent à diffuser une chaîne de certificats qui mène au certificat racine. Le moyen le plus simple d'y parvenir consiste à ajouter le ou les certificats intermédiaires fournis par l'hébergeur Web du partenaire au format PEM au certificat du serveur (également au format PEM).
Le certificat du serveur est validé au moment de la connexion, et les certificats autosignés ne sont pas acceptés. Le contenu du certificat n'est pas vérifié tant que le certificat est valide. Vous pouvez vérifier la validité de votre certificat à l'aide de la commande suivante:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Certificat client:afin de nous authentifier (en tant que Google) auprès du partenaire, nous fournissons un certificat client émis par l'autorité Internet Google G2 (certificat d'autorité de certification) avec les propriétés suivantes:
| Champ | Valeur |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
Les tentatives de connexion sans ce certificat client doivent être refusées par le serveur partenaire.
Pour valider le certificat client, le serveur s'appuie sur un ensemble de certificats racine client approuvés. Vous pouvez choisir d'obtenir cet ensemble de racines approuvées auprès d'une autorité telle que Mozilla ou d'installer l'ensemble de racines actuellement recommandé par la Google Internet Authority G2. Dans les deux cas, vous devrez peut-être mettre à jour manuellement les certificats racine de temps en temps.
Implémenter le protocole de vérification d'état gRPC
Implémentez le protocole de vérification de l'état gRPC.
Ce protocole permet à Google de surveiller l'état du backend de votre implémentation gRPC. La spécification de service fait partie de la distribution GRPC. Conformément à la convention d'attribution de noms GRPC, le nom du service dans les appels de vérification de l'état est ext.maps.booking.partner.v2.BookingService pour la version 2 de l'API ou ext.maps.booking.partner.v0.BookingService pour la version 0 de l'API. La vérification de l'état doit s'exécuter sur la même URL et le même port que les autres points de terminaison.
Autres versions
Pour obtenir la documentation des autres versions de l'API, consultez les pages suivantes : * API v3 * API v0