Cette page a été traduite par l'API Cloud Translation.

Mise à jour en temps réel

Mises à jour en temps réel

Les mises à jour en temps réel sont principalement destinées à des mises à jour que vous ne pouvez pas prévoir, comme des fermetures d'urgence ou des métadonnées qui changent régulièrement (telles que les heures d'arrivée prévues). Si votre modification n'a pas besoin d'être appliquée immédiatement, vous pouvez utiliser l'ingestion de flux par lot. Les mises à jour en temps réel sont traitées en cinq minutes maximum.

Configuration de Google Cloud Platform

Configurer un projet GCP Un projet GCP est nécessaire pour accéder à l'API RTU.
- Accorder l'accès Éditeur à l'adresse food-support@google.com
- Communiquez le numéro de projet GCP à votre contact Google.Pour que les mises à jour en temps réel fonctionnent, votre projet GCP doit être associé à votre compte du centre d'actions.
- Activer l'API Maps Booking:
  - Dans GCP, accédez à API et Services > bibliothèque.
  - Recherchez "Google Maps Booking API". <ph type="x-smartling-placeholder">
    </ph>
  - Recherchez l'instance de bac à sable ("API Google Maps Booking (Dev)"), puis cliquez sur Activer.
  - Recherchez l'instance de production ("API Google Maps Booking", puis cliquez sur Activer). <ph type="x-smartling-placeholder">
    </ph>
    .
  - Créez un compte de service doté d'un rôle d'éditeur pour votre projet GCP. Pour en savoir plus, consultez Configurer un compte de service.
  - Veillez à importer des flux par lot dans l'environnement dans lequel vous travaillez sur des mises à jour en temps réel.
  - Pour l'authentification des API, nous vous recommandons d'installer la bibliothèque cliente Google dans le langage de votre choix. Utilisez "https://www.googleapis.com/auth/mapsbooking" comme champ d'application OAuth. Les exemples de code inclus ci-dessous utilisent ces bibliothèques. Sinon, vous devrez gérer manuellement les échanges de jetons, comme indiqué dans la section Utiliser OAuth 2.0 pour accéder aux API Google.

Configurer un compte de service

Vous avez besoin d'un compte de service pour envoyer des requêtes HTTPS authentifiées aux API Google, telles que l'API Realtime Updates.

Pour configurer un compte de service, procédez comme suit:

Accédez à la console Google Cloud Platform.
Votre compte dans le Centre Actions est également associé à un projet Google Cloud. Sélectionnez-le s'il ne l'est pas déjà.
Cliquez sur Comptes de service dans le menu de gauche.
Cliquez sur Créer un compte de service.
Saisissez un nom pour le compte de service, puis cliquez sur Créer.
Dans le champ Sélectionnez un rôle, sélectionnez Projet > éditeur.
Cliquez sur Continuer.
Facultatif: Ajoutez des utilisateurs pour leur accorder l'accès au compte de service, puis cliquez sur OK.
Cliquez sur Plus > Créez une clé pour le compte de service que vous venez de créer.
Sélectionnez le format JSON, puis cliquez sur Créer.
Une fois votre nouvelle paire de clés publique/privée générée, téléchargez-la sur votre ordinateur.

Travailler avec l'API

L'API Real-time Updates accepte deux types d'opérations: Update et Delete. Il n'est pas possible d'ajouter des entités via l'API de mise à jour en temps réel. Les mises à jour en temps réel peuvent être regroupées si vous incluez plusieurs mises à jour dans une même requête API. Vous pouvez regrouper jusqu'à 1 000 mises à jour dans un seul appel d'API. Nous vous recommandons d'utiliser une approche basée sur des déclencheurs pour envoyer des mises à jour via des mises à jour en temps réel (par exemple, lorsqu'une modification des données de votre système déclenche une mise à jour en temps réel pour Google) plutôt qu'une approche basée sur la fréquence (par exemple, toutes les X minutes pour rechercher des modifications dans votre système) si possible.

L'API Realtime Updates fonctionne à la fois dans les environnements de bac à sable et de production. L'environnement bac à sable permet de tester les requêtes API et l'environnement de production pour mettre à jour le contenu visible par les utilisateurs finaux des commandes.

Bac à sable – partnerdev-mapsbooking.googleapis.com
Production – mapsbooking.googleapis.com

Points de terminaison

L'API des mises à jour en temps réel expose deux points de terminaison pour gérer les demandes entrantes de mise à jour de l'inventaire:

MISE À JOUR - /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
SUPPRIMER – /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete

Le paramètre PARTNER_ID est disponible dans le Centre d'actions, sur la page Compte et utilisateurs, comme illustré dans la capture d'écran ci-dessous.

ID du partenaire sur le portail des partenaires

Prenons l'exemple de la valeur 10000001 de PARTNER_ID sur la capture d'écran ci-dessus. Dans les exemples ci-dessous, les URL complètes utilisées pour envoyer des requêtes API dans l'environnement de bac à sable et de production se présenteront.

Mise à jour du bac à sable

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

Suppression dans un bac à sable

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

Mise à jour de production

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

Suppression de l'élément de production

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

Mettre à jour des entités

Pour mettre à jour des entités de votre inventaire, utilisez le point de terminaison update dans une requête HTTP POST. Chaque requête POST doit inclure le paramètre 10000001 ainsi qu'une charge utile JSON contenant l'entité que vous souhaitez mettre à jour.

Remarque:Assurez-vous que vos flux de données quotidiens contiennent également les modifications envoyées via l'API Realtime Updates. Sinon, vos données risquent d'être obsolètes.

Mettre à jour la charge utile de la requête

Le corps de la requête est un objet JSON avec une liste d'enregistrements. Chaque enregistrement correspond à une entité en cours de mise à jour. Il se compose du champ proto_record et du champ generation_timestamp indiquant l'heure de mise à jour de l'entité:

  {
    "records": [
      {
        "proto_record":"ServiceData PROTO",
        "generation_timestamp":"UPDATE_TIMESTAMP"
      }
    ]
  }

ServiceData PROTO: traduction proto ou JSON de l'entité ServiceData que vous mettez à jour.
UPDATE_TIMESTAMP: veillez à inclure le code temporel correspondant au moment où l'entité a été générée dans vos systèmes backend. Si ce champ n'est pas inclus, il sera défini sur l'heure à laquelle Google reçoit la demande. Lors de la mise à jour d'une entité via une requête batchPush, le champ generation_timestamp est utilisé pour la gestion des versions d'entité. Consultez le format attendu pour les valeurs temporelles dans le schéma d'inventaire relationnel.

La taille du corps de la charge utile ne doit pas dépasser 5 Mo.
Supprimez les espaces blancs pour réduire la taille.
Une requête batchPush peut contenir jusqu'à 1 000 mises à jour.

Exemples

Mettre à jour une heure d'arrivée prévue

Supposons que vous ayez besoin de modifier en urgence l'heure d'arrivée prévue d'un service de livraison, qui passe de 30 à 60 minutes à 60 à 90 minutes. Votre mise à jour doit contenir le fichier JSON pour l'ensemble de l'entité Service.

Prenons l'exemple d'une entité de service qui se présente comme suit:

{
	"service": {
		"service_id": "service/entity002",
		"service_type": "DELIVERY",
		"parent_entity_id": "entity002",
		"lead_time": {
			"min_lead_time_duration": "600s",
			"max_lead_time_duration": "1800s"
		},
		"action_link_id": "delivery_link/entity002"
	}
}

Les mises à jour en temps réel par HTTP POST sont les suivantes (les corps de requête sont imprimés pour plus de lisibilité):

POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
  "records": [{
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "service" : {
        "service_id" : "23456/delivery",
        "service_type" : "DELIVERY",
        "parent_entity_id" : "23456",
        "disabled" : "false",
        "action_link_id": "delivery_link/entity002",
        "lead_time" : {
          "min_lead_time_duration" : {
            "seconds": "3600"
          },
          "max_lead_time_duration" : {
            "seconds": "5400"
          }
        }
      }
    },
    "generation_timestamp": "2023-09-13T17:11:10.750Z"
  }]
}

Mettre à jour plusieurs entités

Pour mettre à jour plusieurs entités de restaurant dans un seul appel d'API, incluez plusieurs enregistrements dans le champ proto_record du corps de la requête.

POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
  "records": [{
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "service" : {
        "service_id" : "23456/delivery",
        "service_type" : "DELIVERY",
        "parent_entity_id" : "23456",
        "disabled" : "false",
        "action_link_id": "delivery_link/entity002",
        "lead_time" : {
          "min_lead_time_duration" : {
            "seconds": "1800"
          },
          "max_lead_time_duration" : {
            "seconds": "3600"
          }
        }
      }
    },
    "generation_timestamp": "2023-09-13T17:11:10.750Z"
  },
  {
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "fee" : {
        "fee_id" : "12345/delivery_fee",
        "fee_type" : "DELIVERY",
        "fixed_amount" : {
          "currency_code" : "USD",
          "units" : "10",
          "nanos" : "0"
        },
        "service_ids": ["service/entity002"]
      }
    },
    "generation_timestamp" : "2023-09-13T17:11:10.750Z"
  }]
}

Supprimer des entités

Pour supprimer des entités de votre inventaire, utilisez le point de terminaison DELETE dans une requête HTTP POST. Chaque requête POST doit inclure le paramètre PARTNER_ID ainsi que la charge utile JSON qui contient l'identifiant de l'entité que vous souhaitez supprimer.

Remarque:Assurez-vous que vos flux de données quotidiens contiennent également toute modification soumise via l'API Realtime Update. Sinon, l'ingestion quotidienne par lot écrasera vos modifications en temps réel.

POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
  "records": [{
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "service" : {
        "service_id" : "23456/delivery"
      }
    },
    "delete_time": "2023-09-13T17:11:10.750Z"
  },
  {
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "fee" : {
        "fee_id" : "12345/delivery_fee"
     }
  },
  "delete_time" : "2023-09-13T17:11:10.750Z"
  }]
}

Ajouter des entités

N'utilisez pas les mises à jour en temps réel pour ajouter de nouvelles entités, car cela peut entraîner des incohérences dans les données. Utilisez plutôt des flux par lot.

Validation et Codes de réponse de l'API

Il existe deux types de validations sur les appels d'API de mise à jour en temps réel:

Au niveau de la requête : ces validations vérifient que la charge utile suit le schéma, et que chaque proto_record contient des champs id et type. Ces vérifications sont synchrones et les résultats sont renvoyés dans le corps de la réponse de l'API. Un code de réponse 200 et un corps JSON vide {} signifient que ces validations ont été effectuées et que les entités de cette requête ont été mises en file d'attente pour traitement. Un code de réponse autre que 200 signifie qu'une ou plusieurs de ces validations ont échoué et que l'intégralité de la requête est rejetée (y compris toutes les entités de la charge utile). Par exemple, s'il manque un élément @type dans proto_record, la réponse d'erreur suivante est renvoyée:

  {
      "error": {
        "code": 400,
    "message": "Record:{...}",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." 
      }
    ]
  }

Au niveau de l'entité: chaque entité (proto_record) de la charge utile est validée par rapport au schéma. Les problèmes rencontrés lors de cette phase de validation ne sont pas signalés dans la réponse de l'API. Elles ne sont consignées que dans le tableau de bord Création de rapports en temps réel du centre d'actions.

Remarque:Un code de réponse 200 ne signifie pas que toutes les entités ont bien été ingérées.

Quotas d'API

Les mises à jour d'API en temps réel disposent d'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é, 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 votre quota, envisagez d'inclure davantage d'entités dans une même requête API. Vous pouvez inclure jusqu'à 1 000 entités dans un appel d'API.

Informations en temps réel sur les délais de traitement

Une entité mise à jour en temps réel est traitée en cinq minutes.

Suivi des conversions