Mises à jour via l'API en temps réel

Votre inventaire varie tout au long de la journée à mesure que de nouvelles réservations ou annulations sont effectuées. Vos marchands sont également susceptibles d'apporter des modifications aux horaires de leurs services. Le mécanisme de mise à jour de l'API en temps réel permet d'informer Google de tout changement apporté à la disponibilité de votre inventaire. Vous pouvez également l'utiliser pour notifier Google de modifications apportées aux réservations existantes.

Les mises à jour en temps réel ne sont pas nécessaires si tous vos marchands utilisent la fonctionnalité de liste d'attente.

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 incrémentielles de la disponibilité et des réservations de l'inventaire, à mesure qu'elles sont enregistrées en temps réel. En plus des mises à jour en temps réel de l'API, envoyez quotidiennement des flux disponibilité complets afin de vous assurer que Google dispose des données de disponibilité les plus précises possible, comme présentes dans votre système. Les flux complets correspondent à un instantané de l'état actuel de la disponibilité de l'inventaire dans votre système.

Bien que les mises à jour de l'API puissent être utilisées pour transmettre des données actualisées des flux, telles que des informations sur les marchands et les services, elles ne sont généralement utilisées que pour mettre à jour les données de 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 qu'une modification est apportée à la réservation (un changement ou une annulation, par exemple).
Availability Replace – Mises à jour en temps réel Obligatoire sous certaines conditions[1] Envoyez des remplacements groupés ou des remplacements uniques pour la mise à jour de la disponibilité de l'inventaire. La propagation et la prise en compte des modifications peuvent prendre plusieurs minutes.
Merchant – Mises à jour en temps réel Facultatif Envoyez des mises à jour en temps réel Merchant si vous souhaitez modifier en temps réel les données concernant un marchand. La propagation et la prise en compte des modifications peuvent prendre plusieurs heures.
Service – Mises à jour en temps réel Facultatif Envoyez des mises à jour en temps réel Service si vous souhaitez modifier en temps réel les données concernant un service. Un cas d'utilisation courant est le suivant : si les prix des services varient considérablement au cours de la journée, il est recommandé de mettre en œuvre des mises à jour du service pour éviter des échecs de commandes en raison d'une incohérence au niveau des prix. La propagation et la prise en compte des modifications peuvent prendre plusieurs heures.

API Availability Replace – Mises à jour en temps réel

Dans les cas suivants, utilisez l'API Availability Replace pour fournir des mises à jour sur la disponibilité:

  • Un utilisateur effectue une réservation sur votre système. Le créneau n'est donc plus disponible.
  • Un marchand modifie sa disponibilité dans votre système.
  • Un utilisateur effectue une réservation via Google. Le créneau 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 fois la réservation et la disponibilité, car le créneau d'origine est de nouveau disponible.
  • Un appel BatchAvailabilityLookup au serveur de réservation renvoie un inventaire qui ne correspond pas à l'inventaire réel.

Pour en savoir plus, consultez les ressources suivantes :

API Booking Notification – Mises à jour en temps réel

L'API Booking Notification informe Google de mises à jour apportées à des réservations existantes. Lorsque vous envoyez une mise à jour concernant des annulations, envoyez seulement les informations essentielles dans la requête via le paramètre de requêteupdateMask. 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 Credentials (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 "Owner" (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'envoyer des appels RESTful directement à l'API Maps Booking à l'aide de charges utiles au format JSON. Pour en savoir plus, consultez la documentation sur 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.

Des bibliothèques d'assistance supplémentaires peuvent être téléchargées pour gérer les autorisations 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, cliquez sur 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 mises à jour de l'API ont un quota 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 dans votre Partner Portal), 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 qu'il réussisse. 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 effectuer des appels vers l'environnement 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()