Distribution en mode push

Dans ce document, nous vous expliquons en quoi consiste le service Pubsubnotificationsettings et comment le configurer pour être informé de divers événements. Pour en savoir plus sur la technologie utilisée, consultez les articles Qu'est-ce que Pub/Sub ? et Présentation des abonnements.

Ce document porte essentiellement sur les commandes, car elles représentent un exemple de cas d'utilisation courant et concret. C'est également le seul pris en charge actuellement.

Jusqu'à présent, vous deviez appeler le service toutes les deux ou trois minutes pour récupérer vos commandes. C'est ce que l'on appelle le mode "pull", qui consiste à appeler Google pour "retirer" vos commandes.

Le service Pubsubnotificationsettings vous permet de recevoir des notifications vous informant qu'une commande a été créée. On appelle cela le mode "push" : Google vous envoie des notifications push concernant des événements, comme des commandes, qui se produisent de son côté.

Pour orderPendingShipment, le système envoie une notification pour chaque commande qui passe à l'état pendingShipment. Si la réception n'est pas confirmée, la notification est renvoyée en fonction des paramètres définis dans Cloud Pub/Sub.

Configurer les notifications

Pour recevoir des notifications, vous devez disposer d'un serveur pouvant recevoir des appels HTTP. Les notifications sont envoyées à votre serveur sous forme de requêtes HTTP POST provenant de Google. Votre serveur Web doit être configuré pour recevoir l'ID de commande d'un service Google. Vous devez ensuite appeler Orders API pour récupérer concrètement la commande.

Le schéma ci-dessous vous donne un aperçu du nouveau workflow.

  1. Le système Cloud Pub/Sub indique à votre serveur qu'une commande a été créée.
  2. Le serveur reçoit le message.
  3. Votre serveur appelle Orders API pour obtenir les informations sur la commande.
  4. Orders API renvoie ces informations.
  5. Votre système de gestion des commandes traite la commande et renvoie une confirmation à Cloud Pub/Sub.

Pour configurer les notifications push, appelez la méthode Pubsubnotificationsettings.update (en indiquant les événements pour lesquels vous souhaitez recevoir des notifications dans registeredEvents) pour obtenir un nom de sujet cloudTopicName.

Dans le cas de orderPendingShipment, cela signifie que, lorsque vos commandes passent à l'état pendingShipment, un message comportant les détails de l'événement est publié dans le sujet Cloud Pub/Sub.

Abonnez-vous ensuite au sujet cloudTopicName et inscrivez votre URL en tant que point de terminaison push.

Cloud Pub/Sub enverra alors des notifications à cette URL chaque fois qu'une commande sera passée.

Pour le moment, orderPendingShipment (commandes à l'état pendingShipment) est le seul type de message disponible, mais d'autres sont prévus.

Le schéma ci-dessous illustre les différentes étapes du processus.

  1. Vous inscrivez les événements pour lesquels vous souhaitez recevoir des notifications Cloud Pub/Sub.
  2. La méthode Pubsubnotificationsettings.update de Content API reçoit la requête et vous renvoie un nom de sujet cloudTopicName.
  3. Vous créez un abonnement au sujet et inscrivez l'URL à Cloud Pub/Sub en tant que point de terminaison push.
  4. Cloud Pub/Sub accepte votre abonnement et associe le nom de sujet cloudTopicName à votre URL. Lorsque des messages sont publiés dans ce sujet cloudTopicName (des notifications de commande, par exemple), ils sont envoyés au point de terminaison push (votre URL).

S'inscrire à des événements

Pour obtenir la liste complète des événements registeredEvents acceptés, reportez-vous à la documentation sur Pubsubnotificationsettings. Cette documentation prend l'exemple de orderPendingShipment, qui active l'envoi de notifications lorsqu'une commande est reçue et atteint l'état pendingShipment.

Requête

Pour en savoir plus, consultez la page sur Pubsubnotificationsettings.update.

PUT https://www.googleapis.com/content/v2.1/merchantId/pubsubnotificationsettings

{
   "registeredEvents":[
      "orderPendingShipment"
   ]
}

Réponse

{
 "kind": "content#pubsubNotificationSettings",
 "cloudTopicName": "projects/681163075750/topics/id_51579e90-b60c-48fb-87e1-122a88f46eb3",
 "registeredEvents": [
  "orderPendingShipment"
 ]
}

S'abonner à Cloud Pub/Sub

Pour vous abonner à Cloud Pub/Sub, utilisez le nom du sujet (cloudTopicName) obtenu à partir de l'appel de Pubsubnotificationsettings.update et de l'URL de votre serveur. Par ailleurs, vous devez utiliser les mêmes identifiants que pour Content API. Pour plus d'informations, consultez la page Gérer les sujets et les abonnements.

Une fois que vous êtes abonné, vous devriez commencer à recevoir des notifications du système. Pour en vérifier le bon fonctionnement, nous vous recommandons de créer une commande test à l'aide de Orders.createtestorder.

Recevoir des messages en mode push

Pour plus d'informations sur la configuration des abonnements push, consultez l'article Utiliser des abonnements en mode push.

Le message utilise la méthode HTTP POST.

POST https://www.example.com/my-push-endpoint

Une requête push Cloud Pub/Sub ressemble à l'exemple ci-dessous. Notez que le champ message.data est encodé en base64.

{
   "message":{
      "data":"eyAKICAgIm1lcmN...AgIH0KfQo=",
      "messageId":"136969346945"
   },
   "subscription":"projects/myproject/subscriptions/mysubscription"
}

Il s'agit du format du champ de données décodées dans le message ci-dessus.

{
   "merchantId":"123456789",
   "resource":{
      "resourceType":"ORDER",
      "resourceId":"TEST-1234-56-7890"
   },
   "event":{
      "eventType":"ORDER_PENDING_SHIPMENT"
   }
}

Dans ce message, resourceType vous indique le type du message, resourceId contient le numéro de commande et eventType correspond au type d'événement utilisé lorsque vous avez appelé le service. orderPendingShipment est le seul eventType disponible pour le moment.

Champ Description
MerchantId Votre référence marchand.
resourceType Le type du message.
resourceId Le numéro de la commande.
eventType Le type de l'événement.

Votre point de terminaison push doit traiter les messages entrants et renvoyer un code d'état HTTP pour indiquer le succès ou l'échec. Une réponse indiquant un succès équivaut à une confirmation que le message a été reçu. Les codes d'état interprétés comme des accusés de réception de messages par le système Cloud Pub/Sub sont les suivants : 200, 201, 202, 204 et 102. Par exemple : 204 No Content.

Cloud Pub/Sub n'envoie pas d'accusé de réception négatif pour les abonnements push. Si votre webhook n'affiche pas de code de succès, Cloud Pub/Sub tente à nouveau de distribuer le message jusqu'à son expiration (à l'issue de la durée de conservation définie pour les messages de l'abonnement). Le délai correspond de fait à la période pendant laquelle le point de terminaison doit répondre à la requête push.

Obtenir les paramètres de notification Cloud Pub/Sub

Pour en savoir plus, consultez la page sur Pubsubnotificationsettings.get.

GET https://www.googleapis.com/content/v2.1/merchantId/pubsubnotificationsettings

{
  "kind": "content#pubsubNotificationSettings",
  "cloudTopicName": "projects/681163075750/topics/id_51579e90-b60c-48fb-87e1-122a88f46eb3",
  "registeredEvents": [
    "orderPendingShipment"
  ]
}