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

Mise à jour en temps réel

Mises à jour en temps réel

Les notifications 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 régulièrement (comme les temps de trajet estimés). Si vous n'avez pas besoin que votre modification soit reflétée immédiatement, vous pouvez utiliser l'ingestion de flux par lot. Les mises à jour en temps réel sont traitées en moins de cinq minutes.

Configuration de Google Cloud Platform

Configurez un projet GCP. Un projet GCP est nécessaire pour accéder à l'API RTU.
- Accorder l'accès éditeur food-support@google.com
- Indiquez à votre contact Google le numéro de projet GCP.Votre projet GCP doit être associé à votre compte Actions Center pour que les mises à jour en temps réel fonctionnent.
- Activez l'API Maps Booking:
  - Dans GCP, accédez à API et services > Bibliothèque.
  - Recherchez "API Google Maps Booking".
  - Recherchez l'instance de bac à sable ("API Google Maps Booking (développeurs)"), puis cliquez sur Activer.
  - Recherchez l'instance de production ("API Google Maps Booking") et cliquez sur Activer.
  - Créez un compte de service avec le rôle d'éditeur pour votre projet GCP. Pour en savoir plus, consultez la section Configuration du compte de service.
  - Assurez-vous d'importer des 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 ci-dessous utilisent ces bibliothèques. Sinon, vous devrez gérer manuellement les échanges de jetons, comme décrit dans la section Utiliser le protocole 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 de mises à jour en temps réel.

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

Accédez à la console Google Cloud Platform.
Un projet Google Cloud est également associé à votre compte dans le Centre d'actions. 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.
Nommez le compte de service, puis cliquez sur Créer.
Dans Sélectionnez un rôle, choisissez Project > Editor (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 le format JSON, 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 de mises à jour en temps réel accepte deux types d'opérations : "Update" (Mettre à jour) et "Delete" (Supprimer). L'ajout de nouvelles entités via l'API de mise à jour en temps réel n'est pas accepté. Vous pouvez regrouper les mises à jour en temps réel si vous incluez plusieurs mises à jour dans une seule requête API. Vous pouvez effectuer jusqu'à 1 000 mises à jour par lot dans un même appel d'API. Nous vous recommandons d'utiliser une approche basée sur des déclencheurs pour envoyer des mises à jour via RTU (c'est-à-dire qu'en cas de modification des données dans votre système, une mise à jour en temps réel est envoyée à Google) plutôt qu'une approche basée sur la fréquence (c'est-à-dire que toutes les X minutes, votre système est analysé pour détecter les modifications).

L'API de mises à jour en temps réel fonctionne à la fois dans les environnements de bac à sable et de production. L'environnement bac à sable permet de tester les requêtes API, tandis que l'environnement de production permet de mettre à jour le contenu visible par les utilisateurs d'Ordering End-to-End.

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 illustré dans la capture d'écran ci-dessous.

Prenons 10000001 comme valeur de PARTNER_ID, comme indiqué dans la capture d'écran ci-dessus. Les URL complètes pour envoyer des requêtes d'API dans l'environnement de préproduction 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

SUPPRIMER le 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 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 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é mise à jour. Elle se compose du champ proto_record et du generation_timestamp indiquant l'heure de la 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 de l'entité 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. Lorsque vous mettez à jour une entité via une requête batchPush, le champ generation_timestamp est utilisé pour le contrôle des versions des entités. Consultez le format attendu pour les valeurs temporelles dans le schéma d'inventaire relationnel.

Le 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

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

Imaginons que vous deviez modifier de toute urgence l'heure d'arrivée estimée d'un service de livraison de 30 à 60 minutes à 60 à 90 minutes. Votre mise à jour doit contenir le code JSON de l'entité "Service" dans son intégralité.

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"
	}
}

Vos mises à jour en temps réel par HTTP POST sont les suivantes (les corps de requête sont mis en forme 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 contenant l'identifiant de l'entité que vous souhaitez supprimer.

Remarque:Assurez-vous que vos flux de données quotidiens 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 pourrait entraîner des incohérences dans les données. Utilisez plutôt des flux par lot.

Codes de validation et de réponse de l'API

Deux types de validations sont effectuées sur les appels d'API de mise à jour en temps réel:

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 ne comporte pas de @type, le message d'erreur suivant est renvoyé:

  {
      "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 à cette phase de validation ne sont pas signalés dans la réponse de l'API. Elles ne sont indiquées que dans le tableau de bord RTU Reporting (Rapports sur les temps de réponse moyens) 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 seule requête API. Vous pouvez inclure jusqu'à 1 000 entités dans un même appel d'API.

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

Une entité mise à jour via une 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.