Suivez votre progression
Accueil Trailhead
Accueil Trailhead

Utiliser l'API Streaming

Objectifs de formation

Une fois cette unité terminée, vous pourrez :
  • Décrire les principaux avantages de la technologie push par rapport à la technologie pull
  • Créer une PushTopic et recevoir des notifications d’événement
  • Définition d’un événement de plate-forme et dériver son canal d’abonnement.
  • Diffuser un message avec la diffusion générique
  • Spécifier des options de rediffusion de diffusions durables

Événements de diffusion en continu

Pour conclure notre enquête sur les API de données Salesforce, examinons une API utilisée dans un cas tout à fait différent. L’API Streaming vous permet d’envoyer automatiquement (push) un flux de notifications depuis Salesforce vers des applications clientes en fonction de critères que vous définissez. En quoi l’envoi automatique de notifications diffère du paradigme pull utilisé par nos autres API, dans lesquelles l’application cliente demande ou extrait (pull) les données de Salesforce ? Examinons le problème du point de vue du capitaine d’un bateau.

Supposons que vous naviguez en haute mer et que vous souhaitez surveiller les dangers potentiels, les autres bateaux et les îles riches en trésors. Vous envoyez un marin en observation dans le nid de corbeaux. Remettez maintenant votre casquette de développeur. Supposons que vous écrivez une application en utilisant une API REST ou SOAP qui vérifie périodiquement si des comptes ont été mis à jour. Vous pouvez employer une solution similaire et surveiller activement en demandant en permanence les données des comptes pour vérifier si elles correspondent aux anciennes données.

Revenez maintenant sur votre bateau, mais cette fois avec un tout nouveau écran radar étincelant. Il n’est plus nécessaire d’envoyer un marin dans le nid de corbeaux, car dès qu’un objet intéressant approche, l’écran radar vous avertit.

L’API Streaming est votre radar. Elle permet de définir des événements et d’envoyer des notifications push à votre application cliente lorsque les événements se produisent. Il n’est pas nécessaire d’observer activement les changements de données, d’interroger en permanence Salesforce et d’exécuter inutilement des requêtes d’API.

L’API Streaming peut être utilisée comme radar pour détecter les changements de données et envoyer des notifications

Le suivi des changements de données dans Salesforce est particulièrement utile si les données de votre entreprise sont stockés dans un système extérieur à Salesforce. Vous pouvez utiliser l’API Streaming pour synchroniser votre source externe avec vos données Salesforce, avec les événements PushTopic et les événements Capture des données de modification. L’API Streaming vous permet également d’exécuter une logique de traitement dans un système externe en réponse aux changements apportés aux données dans Salesforce. Vous pouvez par exemple utiliser l’API Streaming pour notifier un centre logistique dès qu’une opportunité est mise à jour.

Remarque

Remarque

Pour plus d’informations sur la capture de données de modification, consultez le module Trailhead Fondamentaux de la capture des données de modification.

Par ailleurs, vous pouvez utiliser l’API Streaming pour diffuser des notifications personnalisées avec les événements de plate-forme et la diffusion générique. Par exemple, une application peut générer des notifications d'événement de plate-forme pour les commandes traitées par un service d’exécution des commandes. Ou une application peut écouter des événements génériques et afficher un message lorsqu’une période de maintenance système débute ou lorsqu’une nouvelle offre est disponible pour vos utilisateurs.

PushTopics

Une PushTopic est un sObject qui contient les critères des événements que vous souhaitez écouter, par exemple les changements de données d’un objet particulier. Vous définissez les critères sous la forme d’une requête SOQL dans la PushTopic et spécifiez les opérations sur les enregistrements à notifier (créer, mettre à jour, supprimer et annuler la suppression). En plus des critères d’événement, une PushTopic représente le canal auquel les applications clientes s’inscrivent.

Nous aborderons ce point en détail en créant notre propre PushTopic.

Objets pris en charge dans les requêtes PushTopic

Les requêtes PushTopic prennent en charge tous les objets personnalisés et certains des objets standard les plus répandus, tels que les comptes, contacts et opportunités. Pour une liste complète des objets standard pris en charge, consultez le guide du développeur de l’API Streaming répertorié dans la section Ressources.

PushTopics et notifications

Une PushTopic permet de définir l’objet, les champs et les critères de réception des notifications d’événements qui vous intéressent. L’exemple ci-dessous montre une PushTopic définie et insérée dans un code Apex. Une fois cette PushTopic créée, vous pouvez vous abonner à ce canal PushTopic pour suivre les modifications apportées aux comptes qui ont pour ville de facturation San Francisco. Cette PushTopic spécifie les champs ID, Nom et Téléphone renvoyés dans chaque notification d’événement. Par défaut, des notifications sont envoyées pour les opérations créer, supprimer et annuler la suppression qui correspondent aux critères de la requête.
PushTopic pushTopic = new PushTopic();
pushTopic.Name = 'AccountUpdates';
pushTopic.Query = 'SELECT Id, Name, Phone FROM Account WHERE BillingCity=\'San Francisco\'';
pushTopic.ApiVersion = 37.0;
insert pushTopic;

Définissez au minimum le nom, la requête et la version d’API de la PushTopic. Vous pouvez utiliser les valeurs par défaut des autres propriétés. Par défaut, les champs de la liste de champs de l’instruction SELECT et de la clause WHERE déclenchent les notifications. Les notifications sont envoyées uniquement pour les enregistrements correspondant aux critères de la clause WHERE. Les notifications incluent les champs de la clause SELECT. Pour modifier quels champs déclenchent les notifications, définissez pushTopic.NotifyForFields sur l’une des valeurs ci-dessous.

Valeur NotifyForFields
Description
Tout
Des notifications sont générées pour toutes les modifications apportées aux champs des enregistrements, si les enregistrements évalués correspondent aux critères spécifiés dans la clause WHERE.
Referenced (par défaut)
Les modifications des champs référencés dans les clauses SELECT et WHERE sont évaluées. Des notifications sont générées uniquement pour les enregistrements évalués, s’ils correspondent aux critères spécifiés dans la clause WHERE.
Sélectionner
Les modifications des champs référencés dans la clause SELECT sont évaluées. Des notifications sont générées uniquement pour les enregistrements évalués, s’ils correspondent aux critères spécifiés dans la clause WHERE.

Les modifications des champs référencés dans la clause WHERE sont évaluées. Des notifications sont générées uniquement pour les enregistrements évalués, s’ils correspondent aux critères spécifiés dans la clause WHERE.
Pour définir explicitement des préférences de notification, définissez les propriétés ci-dessous sur true ou false. Par défaut, toutes les valeurs sont définies sur true.
pushTopic.NotifyForOperationCreate = true;
pushTopic.NotifyForOperationUpdate = true;
pushTopic.NotifyForOperationUndelete = true;
pushTopic.NotifyForOperationDelete = true;

Si vous créez un compte, une notification d’événement est générée. La notification est en JSON et contient les champs que nous avons spécifiés dans la requête PushTopic : Id, Name et Phone. La notification d’événement est semblable à la suivante.

{
  "clientId": "lxdl9o32njygi1gj47kgfaga4k",
  "data": {
    "event": {
      "createdDate": "2016-09-16T19:45:27.454Z",
      "replayId": 1,
      "type": "created"
    },
    "sobject": {
      "Phone": "(415) 555-1212",
      "Id": "001D000000KneakIAB",
      "Name": "Blackbeard"
    }
  },
  "channel": "/topic/AccountUpdates"
}

Le message de notification inclut le canal de la PushTopic, dont le format de nom est /topic/PushTopicName. Le canal est automatiquement créé lors de la création d’une PushTopic.

Requêtes PushTopic

Explorons la requête que nous venons de définir pour notre PushTopic. Les requêtes PushTopic sont des requêtes SOQL classiques. Si vous connaissez le langage SOQL, vous n’aurez pas besoin d’apprendre un nouveau format. Le format de requête est le suivant :
SELECT <comma-separated list of fields> FROM <Salesforce object> WHERE <filter criteria>

Pour garantir l’envoi des notifications au moment opportun, les exigences suivantes s’appliquent aux requêtes PushTopic.

  • La liste des champs de l’instruction SELECT doit inclure des Id.
  • Un seul objet par requête est autorisé.
  • L’objet doit être valide pour la version d’API spécifiée.
Certaines requêtes ne sont pas prises en charge, notamment les requêtes d’agrégation ou les semi-jointures.

Notifications personnalisées avec les événements de plate-forme

Utilisez les événements de plate-forme pour publier et vous abonner à des notifications personnalisées selon un schéma prédéfini. Contrairement à PushTopic et aux événements Capture de modification de données, les événements de plate-forme ne sont pas liés à des enregistrements Salesforce et ne sont pas publiés automatiquement par Salesforce. Dans leur cas, vous définissez le schéma d’un message d'événement de plate-forme en créant un événement de plate-forme et en lui ajoutant des champs. De plus, les clients publient des événements de plate-forme en utilisant des outils déclaratifs avec la plate-forme Lightning, Apex, ou des API.

Le schéma par version d’un événement de plate-forme permet aux abonnés d’analyser les événements de manière déterministe. Chaque version du schéma correspond à un ID de schéma unique, qui est inclus dans le message de notification de l'événement.

Définition d’un événement de plate-forme.

Pour définir un événement de plate-forme dans l’interface utilisateur, dans Configuration, saisissez Événements de plate-forme dans la zone Recherche rapide, puis sélectionnez Événements de plate-forme. Ajouter des champs à un événement de plate-forme se fait de manière similaire à l’ajout de champs à un objet personnalisé. Certains types de champs ne sont pas pris en charge.

Le nom d’API d’un événement de plate-forme contient le suffixe __e. Par exemple, si vous créez un événement de plate-forme ayant pour étiquette Order Event, son nom d’API sera Order_Event__e.

Une fois l'événement de plate-forme défini, un nom de canal est attribué automatiquement. Le nom du canal dépend du nom d’API de l’événement, et son format est /event/Nom_Evenement. Par exemple, /event/Order_Event__e.

Publication des événements de plate-forme

Pour publier des événements de plate-forme, vous pouvez utiliser les outils déclaratifs ou de programmation suivants sur la plate-forme Lightning.

  • Le Générateur de processus via l’action Création d'un enregistrement
  • Un flux via un élément Créer des enregistrements
  • La méthode Apex EventBus.publish()
  • La ressource de l’API REST sobjects
  • L’appel create() de l’API SOAP

Pour plus de détails, consultez la documentation des événement de plate-forme dans la section Ressources.

Abonnement à des événements de plate-forme

L’API Streaming offre un mécanisme d’abonnement pour plusieurs types d'événements, notamment les événements de plate-forme. En plus de l’API Streaming, vous pouvez vous abonner à des événements de plate-forme en utilisant Lightning Platform.

  • Le Générateur de processus en utilisant un processus qui se lance lorsqu’un événement de plate-forme se produit
  • Un Flux qui attend qu’un événement de plate-forme se produise
  • Un déclencheur Apex
  • L'API Streaming avec la bibliothèque de messagerie CometD
  • Le composant Lightning empApi

Cet exemple présente un message d'événement de plate-forme pour un événement de commande.

{
  "data": {
    "schema": "dffQ2QLzDNHqwB8_sHMxdA",
    "payload": {
      "CreatedDate": "2018-08-22T12:11:40.517Z",
      "CreatedById": "005D0000001cSZs",
      "Order_Number__c": "12345",
      "Has_Shipped__c": true
    },
    "event": {
      "replayId": 1
    }
  },
  "channel": "/event/Order_Event__e"
}

Pour plus de détails, consultez la documentation des événement de plate-forme dans la section Ressources.

Notifications personnalisées avec la diffusion générique

Avant de vous laissez naviguer seul(e), prenons quelques minutes examiner pour la diffusion générique. L’API Streaming prend en charge l’envoi de notifications avec une charge de travail générique, qui ne sont pas liées à des changements de données Salesforce.
Utilisez la notification générique pour envoyer et recevoir des notifications personnalisées avec des contenus de votre choix, sans schéma prédéfini. La diffusion générique vous permet de publier des notifications vers un ensemble d’utilisateurs sélectionnés. Pour utiliser la diffusion générique, les éléments suivants sont nécessaires :
  • Un canal de diffusion en continu qui définit le canal
  • Un ou plusieurs clients inscrits au canal
  • La ressource Streaming Channel Push pour suivre et invoquer des événements dans le canal
Vous pouvez créer un canal de diffusion en continu pour la diffusion générique via l’application Streaming Channels dans l’interface utilisateur ou via l’API. Un canal de diffusion en continu est représenté par le sObject StreamingChannel. Par conséquent, vous pouvez le créer via Apex, l’API REST ou l’API SOAP. Le format de nom du canal pour la diffusion en continu générique est /u/ChannelName. Par exemple, cet extrait de code Apex crée un canal nommé Broadcast.
StreamingChannel ch = new StreamingChannel();
ch.Name = '/u/Broadcast';
insert ch;

Alternativement, si le canal de diffusion n’existe pas, vous pouvez demander à Salesforce de le créer dynamiquement. Pour activer les canaux de diffusion dynamiques dans votre organisation, dans Configuration, saisissez Interface utilisateur dans la zone Recherche rapide, puis sélectionnez Interface utilisateur. Dans la page Interface utilisateur, sélectionnez l’option Activer la création dynamique de canaux de diffusion.

Vous pouvez vous abonner au canal en utilisant un client CometD (dans la section Ressources, un lien pointe vers un exemple de procédure dans le guide Streaming API Developer Guide).

Pour générer des événements, transmettez une requête POST à la ressource REST ci-dessous. Remplacez XX.0 par la version de l’API et Streaming Channel ID par l’ID de votre canal.

/services/data/vXX.0/sobjects/StreamingChannel/Streaming Channel ID/push
Remarque

Remarque

Pour obtenir votre ID de canal, exécutez une requête SOQL dans StreamingChannel, telle que : SELECT Id, Name FROM StreamingChannel

Exemple de corps de requête REST.

{
  "pushEvents": [
      {
          "payload": "Broadcast message to all subscribers",
          "userIds": []
      }
   ]
}
Remarque

Remarque

Au lieu de réaliser une diffusion auprès de l’ensemble des abonnés, vous pouvez spécifier une liste d’utilisateurs abonnés auxquels envoyer les notifications en utilisant le champ facultatif userIds. Vous pouvez également utiliser la méthode GET de la ressource API REST Streaming Channel Push pour obtenir la liste des abonnés au canal actifs.

La notification d’événement que reçoit le client abonné est semblable à la suivante.

{
  "clientId": "1p145y6g3x3nmnlodd7v9nhi4k",
  "data": {
    "payload": "Broadcast message to all subscribers",
    "event": {
      "createdDate": "2016-09-16T20:43:39.392Z",
      "replayId": 1
    }
  },
  "channel": "/u/Broadcast"
}

Notez que cette notification d’événement contient le champ replayId

Grâce aux notifications d’événement, vous pouvez vous engager en toute confiance sur les hautes mers à la recherche de cette île au trésor !

Récupération de notifications antérieures à l’aide de la diffusion durable

Jusqu’à présent, vous avez découvert les différents types d'événements. Que se passe-t-il si un enregistrement Salesforce est créé ou qu’une notification personnalisée est générée avant qu’un client ne soit abonné à un canal d'événement ou pendant qu’un client est déconnecté ? Avant l’API version 37.0, le client manquait la notification correspondante. Depuis l’API version 37.0, Salesforce stocke les événements PushTopic, les événements génériques ainsi que les événements de plate-forme volume standard pendant 24 heures, et les événements haut volume pendant 72 heures. Vous pouvez récupérer les messages d’événement à tout moment pendant ces périodes. Excellent !

À compter de l’API version 37.0, chaque message de notification d’événement contient un champ appelé replayId. L’API Streaming renvoie en différé les notifications d’événements envoyées en utilisant le champ replayId.

Chaque message d’événement se voit attribuer un identifiant opaque enregistré dans le champ ReplayId. La valeur du champ ReplayId est renseignée par le système lorsque l’événement est distribué aux abonnés, et renvoie à la position de l’événement dans le flux des événements. Les valeurs de ReplayID d'événements consécutifs ne sont pas nécessairement contiguës. Par exemple, l'événement qui suivra un événement avec une ID de 999 peut avoir une ID de 1025. Un abonné peut stocker une ReplayID et l’utiliser au réabonnement pour récupérer les événements qui sont dans la fenêtre de rétention. Par exemple, un abonné peut récupérer les événements manqués suite à un échec de connexion. Les abonnés ne doivent pas calculer de nouvelles ReplayID à partir d’une ReplayID enregistrée pour accéder à d’autres évènements du flux.

Tableau 1. Options de lecture
Option de lecture
Description
Utilisation
ReplayID
L’abonné reçoit tous les événements stockés après l’événement spécifié par la valeur replayId et les nouveaux événements.
Prenez connaissance des événements manqués après un certain message d’événement, par exemple, après un échec de connexion. Pour vous abonner avec un ID de lecture spécifique, enregistrez l’ID de lecture du message d’événement après lequel vous souhaitez extraire les événements stockés. Utilisez ensuite cet ID de lecture lorsque vous vous réabonnez.
-1
L’abonné reçoit les nouveaux événements publiés après qu’il s’est abonné.
Nous recommandons aux clients de s’abonner avec l’option -1 afin de recevoir les nouveaux messages d’événement. Si les clients ont besoin d’obtenir des messages d’événement antérieurs, ils peuvent utiliser n’importe quelle autre option de lecture.
-2
L’abonné reçoit tous les événements, y compris les événements passés contenus dans la période de rétention et les nouveaux événements.
Prenez connaissance des événements manqués et récupérez tous les événements stockés, par exemple, après un échec de connexion. Utilisez cette option avec parcimonie. S’abonner avec l’option -2 lorsqu’un grand nombre de messages d’événement sont stockés peut ralentir les performances.

Le diagramme ci-dessous montre comment les consommateurs d’événements lisent un flux d’événements en utilisant diverses options d’affichage.

Événements de diffusion en continu avec des options de lecture