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 aux mises à jour que vous ne pouvez pas prévoir, telles que les routes fermées en urgence ou les 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 prise en compte immédiatement, vous pouvez utiliser l'ingestion de flux par lots. 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 le droit d'accès en tant qu'éditeur à l'adresse food-support@google.com
- Indiquez à votre contact Google le numéro du projet GCP.Celui-ci 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 ("Google Maps Booking API (Dev)"), puis cliquez sur Activer.
  - Recherchez l'instance de production ("API Google Maps Booking"), puis cliquez sur Activer.
  - Créez un compte de service avec un rôle d'éditeur dans 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 les mises à jour en temps réel.
  - Pour l'authentification de l'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 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 Realtime Updates.

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

Accéder à la console Google Cloud Platform
Votre compte du Centre d'actions est également associé à un projet Google Cloud. Sélectionnez ce projet 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.
Attribuez un nom au compte de service, puis cliquez sur Créer.
Dans le champ Sélectionnez un rôle, choisissez 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 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" (Mettre à jour) et "Delete" (Supprimer). 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. Dans la mesure du possible, nous vous recommandons d'utiliser une approche basée sur le déclencheur pour envoyer des mises à jour via la fonctionnalité RTU (par exemple, lorsque des modifications de données dans votre système déclenchent une mise à jour en temps réel vers Google) plutôt qu'une approche basée sur la fréquence (par exemple, toutes les X minutes, une analyse de votre système pour détecter d'éventuelles modifications).

L'API Realtime Updates fonctionne à la fois dans les environnements de bac à sable et de production. L'environnement de bac à sable est utilisé pour tester les requêtes API et l'environnement de production pour mettre à jour le contenu visible par les utilisateurs de bout en bout.

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

Points de terminaison

L'API de mise à jour en temps réel expose deux points de terminaison pour gérer les requêtes entrantes de mise à 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

Vous trouverez le paramètre PARTNER_ID 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

En prenant 10000001 comme valeur de PARTNER_ID comme dans l'exemple de la capture d'écran ci-dessus, les URL complètes permettant d'envoyer des requêtes API en bac à sable et en production se présenteront dans les exemples ci-dessous.

Mise à jour du bac à sable

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

Suppression dans le bac à sable

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

Mise à jour de la production

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

Suppression 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 peuvent être obsolètes ou 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, qui indique 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 l'horodatage 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 correspond à l'heure à laquelle Google reçoit la requête. 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é. Vérifiez 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 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 faire passer en urgence l'heure d'arrivée prévue d'un service de livraison de 30 à 60 minutes à 60 à 90 minutes. Votre mise à jour doit contenir le fichier JSON de l'ensemble de l'entité de 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"
	}
}

La mise à jour en temps réel effectuée par HTTP POST se présente comme suit (le corps de la requête est plutôt lisible pour une meilleure 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 avec 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 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 de nouvelles entités, car cela pourrait entraîner des incohérences dans les données. Utilisez plutôt des flux groupés.

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

Il existe deux types de validations effectuées 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 {} signifie 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 la requête entière est rejetée (y compris toutes les entités de la charge utile). Par exemple, s'il manque un @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) dans 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 comptabilisées que dans le tableau de bord Création de rapports sur les mises à jour 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 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 ce problème, relancez l'appel à des intervalles exponentiellement plus grands jusqu'à ce qu'il aboutisse. Si vous épuisez régulièrement le 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 même 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