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

Mise à jour en temps réel

Mises à jour en temps réel

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

Configurer Google Cloud Platform

Configurez un projet GCP. Un projet GCP est nécessaire pour accéder à l'API RTU.
- Accorder l'accès à l'éditeur à food-support@google.com
- Communiquez le numéro du projet GCP à votre point de contact Google.Pour que les mises à jour en temps réel fonctionnent, votre projet GCP doit être associé à votre compte Actions Center.
- Activez l'API Maps Booking :
  - Dans GCP, accédez à API et services > Bibliothèque.
  - Recherchez "API Google Maps Booking".
  - Recherchez l'instance Sandbox ("API Google Maps Booking (dev)") et cliquez sur Activer.
  - Recherchez l'instance de production ("API Google Maps Booking") et cliquez sur Activer.
  - Créez un compte de service avec un rôle d'éditeur pour votre projet GCP. Pour en savoir plus, consultez Configurer un compte de service.
  - Veillez à importer les flux par lot dans l'environnement dans lequel vous travaillez sur les mises à jour en temps réel.
  - Pour l'authentification de l'API, nous vous recommandons d'installer la bibliothèque cliente Google dans la langue 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 les échanges de jetons manuellement, comme décrit dans 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, comme l'API Real-time Updates.

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

Accédez à la console Google Cloud Platform.
Votre compte sur le Centre d'actions est également associé à un projet Google Cloud. Sélectionnez ce projet s'il n'est pas déjà sélectionné.
Cliquez sur Comptes de service dans le menu de gauche.
Cliquez sur Créer un compte de service.
Saisissez le nom du 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éer une clé pour le compte de service que vous venez de créer.
Sélectionnez JSON comme format, puis cliquez sur Créer.
Une fois la 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 prend en charge deux types d'opérations : "Update" (Mettre à jour) et "Delete" (Supprimer). Il n'est pas possible d'ajouter des entités à l'aide de 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. Si possible, nous vous recommandons d'utiliser une approche basée sur les déclencheurs pour envoyer des mises à jour via RTU (c'est-à-dire qu'un changement de données dans votre système déclenche une mise à jour en temps réel sur Google) plutôt qu'une approche basée sur la fréquence (c'est-à-dire que votre système est analysé toutes les X minutes pour détecter les changements).

L'API Real-Time Updates fonctionne 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 permet de mettre à jour le contenu visible par les utilisateurs de la fonctionnalité de commande de bout en bout.

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

Points de terminaison

L'API de mises à jour en temps réel expose deux points de terminaison pour gérer les requêtes entrantes de mises à jour d'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 se trouve dans Actions Center, sur la page Compte et utilisateurs, comme indiqué dans la capture d'écran ci-dessous.

ID de partenaire sur le portail des partenaires

En prenant 10000001 comme valeur de PARTNER_ID, comme dans la capture d'écran ci-dessus, les URL complètes pour envoyer des requêtes d'API dans le bac à sable et en production ressembleront aux exemples ci-dessous.

Mise à jour du bac à sable

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

DELETE du bac à sable

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

Informations sur la production

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

Production DELETE

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 dans 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 quotidiennes contiennent également les modifications envoyées via l'API de mises à jour en temps réel. 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 contenant une liste d'enregistrements. Chaque enregistrement correspond à une entité en cours de mise à jour. Il se compose du champ proto_record et de generation_timestamp indiquant l'heure de la mise à jour de l'entité :

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

ServiceData PROTO : traduction au format proto ou JSON de l'entité ServiceData que vous mettez à jour.
UPDATE_TIMESTAMP : Veillez à inclure le code temporel de la génération de l'entité dans vos systèmes de backend. Si ce champ n'est pas inclus, il sera défini sur l'heure à laquelle Google reçoit la demande. Lorsque vous mettez à jour une entité à l'aide d'une requête batchPush, le champ generation_timestamp est utilisé pour le contrôle des versions des entités. Consultez le format attendu des 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 vides pour réduire la taille.
Une requête batchPush peut contenir jusqu'à 1 000 mises à jour.

Exemples

Modifier une ETA

Imaginons que vous deviez modifier de toute urgence le délai de livraison d'un service de livraison de 30 à 60 minutes à 60 à 90 minutes. Votre mise à jour doit contenir le code JSON pour l'intégralité 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"
	}
}

Voici votre mise à jour en temps réel par HTTP POST (les corps de requête sont joliment imprimés pour faciliter la lecture) :

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 en 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 contenant l'identifiant de l'entité que vous souhaitez supprimer.

Remarque : Assurez-vous que vos flux de données quotidiennes contiennent également les modifications envoyées via l'API de mise à jour en temps réel. Sinon, l'ingestion par lot quotidienne é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 des entités, car cela peut entraîner des incohérences de données. Utilisez plutôt des flux par lot.

Validation et codes de réponse de l'API

Deux types de validations sont effectuées sur les appels de l'API Real-Time Updates :

Au niveau de la requête : ces validations vérifient que la charge utile respecte 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 réussi 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'ensemble de la requête est rejeté (y compris toutes les entités de la charge utile). Par exemple, si un proto_record est manquant dans un @type, 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 signalées que dans le tableau de bord Rapports sur les utilisateurs récents du Centre d'actions.

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

Quotas d'API

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

Mises à jour en temps réel des délais de traitement

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

Suivi des conversions

Mise à jour en temps réel Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.