La configuration d'un serveur de réservation de votre côté permet au Centre d'actions de créer des rendez-vous / réservations / réservations auprès de vous au nom de l'utilisateur.
Implémenter une interface API basée sur gRPC
Remarque: Tous les nouveaux partenaires doivent utiliser l'interface API REST plutôt que l'API gRPC.
Implémentez une interface API basée sur gRPC. Cela permet à Google d'envoyer des demandes de réservation. La surface de l'API est définie à l'aide de l'IDL basé sur le tampon de protocole de gRPC.
Nous demandons à nos nouveaux partenaires d'implémenter un ensemble recommandé d'API v2. Les partenaires peuvent sélectionner l'URL et le PORT qui conviennent le mieux à 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 nos partenaires actuels qui ont implémenté l'API v0, veuillez contacter le Centre d'actions pour en savoir plus.
Téléchargez la définition de service au format proto ci-dessous pour commencer à mettre en œuvre l'API.
Télécharger la définition de service
Ressources de l'API
Veuillez vous familiariser avec les types de ressources suivants qui seront utilisés dans cette implémentation:
- Slot (Emplacement) : emplacement d'inventaire.
- Réservation : rendez-vous pour 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
Lorsque vous créez 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 méthode doit être considérée comme un paiement sans connexion, car Actions Center n'a aucun moyen de rechercher le compte de l'utilisateur dans le système du partenaire. La réservation finale doit être présentée aux marchands du partenaire dans leur système, tout comme les réservations effectuées via le système de réservation du partenaire.
Implémentation de squelette en Java
Pour commencer, nous fournissons un serveur gRPC squelette en Java qui peut être compilé et installé. Vous pouvez le consulter dans la section Exemples > Implémentation de référence gRPC. Ce serveur dispose des méthodes gRPC bouchonnées qui sont nécessaires pour prendre en charge 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 de partenaire traite des requêtes gRPC : les erreurs inattendues provenant de données incorrectes et les 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.
Si des erreurs inattendues se produisent, elles doivent être renvoyées au client à l'aide de codes d'erreur gRPC canoniques. Entre autres exemples, nous ne tolérons pas que YouTube soit utilisé pour :
- INVALID_ARGUMENT est utilisé dans les RPC tels que CheckAvailability et CreateLease. Il doit être renvoyé si l'emplacement fourni contient des informations non valides.
- NOT_FOUND est utilisé dans les RPC tels que CreateBooking et ListBookings. Il 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.
Au contraire, les erreurs de logique métier doivent être capturées dans l'échec de la réservation 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 Mise à jour des réservations. Entre autres exemples, nous ne tolérons pas que YouTube soit utilisé pour :
- 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, et Google Reserve peut relancer les RPC si aucune réponse n'est reçue. Pour cette raison, tous les RPC qui modifient l'état (CreateBooking, UpdateBooking) doivent être idempotents. Les messages de requête pour ces RPC incluent des jetons d'idempotence permettant d'identifier la requête de manière unique et de permettre au partenaire de faire la distinction entre un RPC relancé (avec l'intention de créer une seule réservation) et deux réservations distinctes.
Entre autres exemples, nous ne tolérons pas que YouTube soit utilisé pour :
- Une réponse RPC CreateBooking réussie inclut la réservation créée et, dans certains cas, le paiement est traité dans le cadre du processus de réservation. Si exactement la même requête CreateBookingRequest est reçue une deuxième fois (y compris
idempotency_token), la même réponse CreateBookingResponse doit être renvoyée. Aucune deuxième réservation n'est créée, et l'utilisateur, le cas échéant, est facturé une seule fois. Notez que si une tentative CreateBooking échoue, le backend du partenaire doit réessayer si la même requête est renvoyée.
L'exigence d'idempotence s'applique à toutes les méthodes qui contiennent des jetons d'idempotence.
Sécurité et authentification des serveurs 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. Cela nécessite l'utilisation d'un certificat de serveur valide pour votre implémentation gRPC et l'acceptation d'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 serveur GRPC prévoient de diffuser une chaîne de certificats menant au certificat racine. Pour ce faire, le moyen le plus simple consiste à ajouter le ou les certificats intermédiaires fournis par l'hôte 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. Tant que le certificat est valide, son contenu n'est pas vérifié. 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 Google Internet Authority G2 (certificat CA) 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 du client de confiance. Vous pouvez choisir d'obtenir cet ensemble de racines de confiance auprès d'une autorité telle que Mozilla ou d'installer l'ensemble de racines actuellement recommandées par l'autorité Internet de Google G2. Dans les deux cas, vous devrez peut-être parfois mettre à jour manuellement les certificats racine.
Implémenter le protocole de vérification de l'état gRPC
Mettez en œuvre 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 de dénomination GRPC, le nom du service dans les appels de vérification de l'état est ext.maps.booking.partner.v2.BookingService pour l'API v2 ou ext.maps.booking.partner.v0.BookingService pour l'API v0. 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 en savoir plus sur les autres versions de l'API, consultez les pages suivantes : * API v3 * API v0