L'inventaire de votre système varie tout au long de la journée en raison de nouvelles réservations, d'annulations et des modifications des horaires de vos marchands. L'API de mise à jour en temps réel permet d'informer Google de ces changements concernant la disponibilité de l'inventaire. Vous pouvez également utiliser les mises à jour de l'API en temps réel pour informer Google des modifications apportées aux réservations existantes.
Flux et mises à jour de l'API en temps réel
Les mises à jour de l'API en temps réel permettent d'informer Google de modifications apportées à la disponibilité et aux réservations de l'inventaire en temps réel. En plus des mises à jour de l'API en temps réel, envoyez quotidiennement des flux disponibilité complets pour vous assurer que Google dispose des informations les plus précises et les plus récentes sur la disponibilité dans votre système. Les flux complets vous fournissent un instantané de la disponibilité actuelle de l'inventaire dans votre système.
Bien que les mises à jour de l'API puissent être utilisées pour mettre à jour les informations fournies par les flux (par exemple, les informations sur les marchands et les services), elles ne sont généralement utilisées que pour mettre à jour la disponibilité.
API de mise à jour en temps réel requises
| API de mise à jour en temps réel | ||
|---|---|---|
| BookingNotification | Obligatoire | Envoyez des mises à jour en temps réel de BookingNotification chaque fois que la réservation est modifiée (par exemple, en cas de modification ou d'annulation). |
| Availability Replace – Mises à jour en temps réel | Obligatoire sous certaines conditions[1] | Envoyez des mises à jour en temps réel de remplacement par lot ou par remplacement pour mettre à jour la disponibilité de l'inventaire. La propagation et la prise en compte des modifications peuvent prendre quelques minutes. |
| Merchant – Mises à jour en temps réel | Facultative | Envoyez des mises à jour en temps réel Merchant si vous souhaitez modifier les informations du marchand en temps réel. La propagation et la prise en compte des modifications peuvent prendre plusieurs heures. |
| Service – Mises à jour en temps réel | Facultative | Envoyez des mises à jour en temps réel de service si vous souhaitez modifier les informations de service en temps réel. Un cas d'utilisation courant est le suivant : si les prix des services fluctuent considérablement au cours de la journée, il est recommandé d'implémenter les mises à jour en temps réel des services pour éviter les échecs de commandes en raison d'incohérences de prix. La propagation et la prise en compte des modifications peuvent prendre plusieurs heures. |
API Availability Replace – Mises à jour en temps réel
Utilisez l'API Availability Replace pour fournir des mises à jour de disponibilité dans les cas d'utilisation suivants:
- Un utilisateur réserve une réservation sur votre système. Le créneau de disponibilité n'est donc plus disponible.
- Un marchand modifie sa disponibilité dans votre système.
- Un utilisateur réserve une réservation via Google. Le créneau de disponibilité n'est donc plus disponible.
- Une réservation effectuée via Google est annulée de votre côté, par exemple, directement par le marchand. Vous devez mettre à jour la réservation ainsi que la disponibilité, car le créneau d'origine est à nouveau disponible.
- Un appel
BatchAvailabilityLookupau serveur de réservation renvoie un inventaire qui ne correspond pas à l'inventaire réel.
Pour en savoir plus, consultez les ressources suivantes :
- Tutoriel : Structurer les mises à jour en temps réel
- Exemple de client Java pour les mises à jour en temps réel à l'aide d'appels RESTful
- Page de référence associée à l'API Inventory Update
Booking Notification API RTU
L'API Booking Notification informe Google des mises à jour des réservations existantes. Lorsque vous envoyez une mise à jour concernant les annulations, envoyez uniquement les informations essentielles de la requête avec le paramètre de requête updateMask. Voici un exemple :
Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status
Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}
Accéder à l'API
Créer un compte de service
Utilisez l'onglet Identifiants de la console Google APIs pour créer un compte de service. Stockez la clé privée au format JSON dans un endroit sûr. Lorsque vous créez le compte, vous avez la possibilité de définir le rôle sur "Propriétaire".
Authentifier les API Maps Booking
Après avoir créé un compte de service, authentifiez les API suivantes :
- API Google Maps Booking
- API Google Maps Booking (développeurs)
Pour obtenir des instructions détaillées sur la procédure à suivre, consultez le tutoriel S'authentifier avec l'API Maps Booking.
Utiliser des appels RESTful ou télécharger la bibliothèque cliente
Nous vous recommandons d'effectuer des appels RESTful directement vers l'API Maps Booking avec des charges utiles JSON. Pour en savoir plus, consultez la documentation de l'API REST.
Vous pouvez également utiliser des bibliothèques clientes pour vous connecter à l'API.
| Langue | Télécharger le lien |
|---|---|
| Java | Bibliothèque client Java. Pour en savoir plus, consultez les instructions sur le client Java. |
Vous pouvez télécharger des bibliothèques d'assistance supplémentaires qui gèrent l'autorisation et d'autres aspects des appels aux API Google. Si nécessaire, consultez ces exemples.
Récupérer le document de découverte
Pour certaines bibliothèques clientes, telles que Ruby, il est nécessaire de récupérer le document de découverte de l'API, qui décrit ses méthodes et ses paramètres.
Utilisez la commande suivante pour récupérer le document de découverte:
curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'
Pour en savoir plus sur l'accès à l'API depuis Ruby, consultez les liens suivants : Client API Ruby et Bibliothèque d'authentification Ruby.
Effectuer des appels autorisés à l'API
Lorsque vous appelez l'API, consultez la section Préparer un appel d'API autorisé pour autoriser votre compte de service avec votre clé privée et le champ d'application OAuth suivant : https://www.googleapis.com/auth/mapsbooking.
Quotas d'API
Les quotas des mises à jour de l'API sont de 1 500 requêtes toutes les 60 secondes, soit 25 requêtes par seconde en moyenne. Lorsqu'un quota est dépassé (ce qui peut se produire lorsque vous n'avez pas ajouté le bon numéro de projet Google Cloud sur le portail des partenaires), Google répond avec le message d'erreur suivant:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
Pour gérer cela, relancez l'appel à des intervalles exponentiellement plus grands jusqu'à ce que l'appel aboutisse. Si vous épuisez régulièrement le quota avec ReplaceServiceAvailability, passez à BatchReplaceServiceAvailabily pour réduire le nombre d'appels d'API. Cette méthode vous permet de mettre à jour plusieurs services via un seul appel d'API.
Points de terminaison bac à sable et production
Vous pouvez appeler des environnements de bac à sable et de production via l'API. Assurez-vous d'avoir activé les deux API dans votre projet Google Cloud. Ces deux API utilisent le même champ d'application, mais leurs points de terminaison sont différents.
Point de terminaison production : https://mapsbooking.googleapis.com/
Point de terminaison bac à sable : https://partnerdev-mapsbooking.googleapis.com/
Voici un exemple de modification du point de terminaison en Java :
// This block of code is for OAuth and is the same for prod and sandbox.
GoogleCredential
.fromStream(new FileInputStream(...))
.createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))
// This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
new GoogleMapsBookingAPI.Builder(...)
.setApplicationName(...)
.setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
.build()