Suivez votre progression
Accueil Trailhead
Accueil Trailhead

Souscription à des événements de plate-forme

Objectifs de formation

Une fois cette unité terminée, vous pourrez :
  • Expliquer comment souscrire à des messages d'événements de plate-forme.
  • Vous abonner à un événement à partir de la plate-forme et d’applications externes
  • Tester des événements de plate-forme dans une méthode de test Apex
  • Souscription à des événements de plate-forme via CometD.

Souscription à des événements de plate-forme

Maintenant que vous avez vu comment publier des événements de plate-forme, comment pouvez-vous y souscrire et être informé des dernières actualités ou de l'expédition d'un colis ? Sur la plate-forme Salesforce, Apex déclenche des évènements, traite des données et les fait circuler. Le composant Lightning empApi et les applications Visualforce reçoivent des notifications d’événements via CometD. Dans une application externe, vous souscrivez aussi aux événements à l'aide de CometD.

Souscrire à des notifications d'événements de plate-forme avec des déclencheurs Apex

Vous avez sans doute déjà utilisé des déclencheurs Apex pour effectuer des opérations sur des événements de la base de données. Avec les événements de plate-forme, le processus est similaire. Il suffit d'écrire un déclencheur Apex après insertion sur l’objet d'événement pour souscrire aux événements entrants. Les déclencheurs fournissent un mécanisme de souscription automatique dans Apex. Vous n’avez pas besoin de créer ou d'écouter explicitement un canal. Les déclencheurs reçoivent des notifications d’événement provenant de sources variées, qu’elles soient publiées via Apex ou une API.

Les événements de plate-forme ne sont compatibles qu’avec les déclencheurs après insertion. L’événement de déclencheur après insertion correspond au moment qui suit la publication d’un événement de plate-forme. Le déclencheur après insertion entre en action après la publication d'un message d'événement.

Pour créer un déclencheur d'événement de plate-forme, utilisez la Developer Console.

  1. Cliquez sur l’icône Configuration, sélectionnez Developer Console et cliquez sur Fichier | Nouveau | Déclencheur Apex.
  2. Donnez-lui un nom, choisissez l’événement du sObject et cliquez sur Soumettre.

La Developer Console ajoute automatiquement l’événement after insert dans le modèle de déclencheur. Vous pouvez également créer un déclencheur à partir de la page de définition de l'événement dans Configuration, dans la liste associée Déclencheurs, mais vous devrez préciser le mot-clé after insert.

L’exemple suivant présente un déclencheur pour l’événement Cloud News. Il fait une itération à travers chaque événement et vérifie si l’actualité est urgente sur la base du champ Urgent__c. Si l’actualité est urgente, le déclencheur crée une requête à envoyer un journaliste et ajoute la localisation de l’événement au sujet de la requête.

// Trigger for listening to Cloud_News events.
trigger CloudNewsTrigger on Cloud_News__e (after insert) {
    // List to hold all cases to be created.
    List<Case> cases = new List<Case>();
    // Get queue Id for case owner
    Group queue = [SELECT Id FROM Group WHERE Name='Regional Dispatch' AND Type='Queue'];
    // Iterate through each notification.
    for (Cloud_News__e event : Trigger.New) {
        if (event.Urgent__c == true) {
            // Create Case to dispatch new team.
            Case cs = new Case();
            cs.Priority = 'High';
            cs.Subject = 'News team dispatch to ' +
                event.Location__c;
            cs.OwnerId = queue.Id;
            cases.add(cs);
        }
   }
    // Insert all cases corresponding to events received.
    insert cases;
}

Configurer la journalisation de débogage

Contrairement aux déclencheurs portant sur des objets standard ou personnalisés, les déclencheurs portant sur des événements de plate-forme ne s’exécutent pas dans la transaction Apex qui a publié l’événement. Le déclencheur exécute son propre processus sous l'entité Processus automatisé, qui est un utilisateur système. Par conséquent, les journaux de débogage correspondant à l’exécution du déclencheur sont créés par l’entité Processus automatisé et ne sont pas disponibles dans la Developer Console. Pour recueillir les journaux des déclencheurs des événements de plate-forme, ajoutez un marqueur de suivi pour l’entité Processus automatisé dans Configuration.

  1. Dans Configuration, saisissez Journaux de débogage dans la zone Recherche rapide, puis cliquez sur Journaux de débogage.
  2. Cliquez sur Nouveau.
  3. Sélectionnez Processus automatisé comme Type d'entité suivie.
  4. Sélectionnez la date de début et la date d'expiration des journaux que vous voulez recueillir.
  5. Dans Niveau de débogage, saisissez * et cliquez sur Rechercher.
  6. Sélectionnez un niveau de débogage prédéfini comme SFDC_DevConsole, ou cliquez sur Nouveau pour créer le vôtre.
  7. Cliquez sur Enregistrer.
Remarque

Remarque

Les journaux de débogage des tests Apex sont une exception. Ils consignent les déclencheurs d'événements dans le même journal d’exécution de test.

À savoir sur les déclencheurs d’événements de plate-forme

Ordre de traitement des événements
Un déclencheur traite les notifications d’événements de plate-forme successivement, dans l’ordre dans lequel elles sont reçues. L'ordre des événements est basé sur l’ID de relecture de l’événement. Un déclencheur Apex peut recevoir un lot d’événements simultanément. L’ordre des événements est préservé au sein de chaque lot. Les événements d’un lot peuvent provenir d’une ou plusieurs sources de publication.

Exécution de déclencheur asynchrone
Un déclencheur d’événement de plate-forme exécute son propre processus de manière asynchrone et ne fait pas partie de la transaction qui a publié l’événement. Par conséquent, il peut y avoir un délai entre la publication d'un événement et le moment où le déclencheur le traite. Ne vous attendez pas à obtenir le résultat de l’exécution du déclencheur immédiatement après la publication de l’événement.

Utilisateur système Processus automatisé
Comme les déclencheurs d’événements de plate-forme ne sont pas exécutés sous l’utilisateur qui les exécute (l’utilisateur actif), mais sous l’utilisateur système Processus automatisé, nous définissons explicitement le champ ID de propriétaire dans notre exemple de déclencheur CloudNewsTrigger. Nous avons utilisé l’identifiant d’un exemple de file d'attente d’utilisateur appelée Distribution régionale pour notre exemple de déclencheur. Si vous créez un enregistrement Salesforce dont le déclencheur contient un champ OwnerId, comme une requête ou une opportunité, définissez explicitement l’ID de propriétaire. Pour les requêtes et les pistes, vous pouvez également utiliser des règles d'attribution pour définir le propriétaire.

De plus, les champs système des enregistrements créés ou mis à jour dans le déclencheur d’événements, comme CreatedById et LastModifiedById, référencent l’entité Processus automatisé et non l’utilisateur actif. De même, l’instruction Apex UserInfo.getUserId() renvoie l’entité Processus automatisé.

Limitations des gouverneurs Apex
À l’instar des déclencheurs d’objets standard ou personnalisés, les déclencheurs d’événements de plate-forme sont soumis aux limitations des gouverneurs Apex.

Limitations des déclencheurs Apex
Les déclencheurs des événements de plate-forme partagent un grand nombre de limitations avec les déclencheurs d’objets personnalisés et standard. Par exemple, vous ne pouvez pas effectuer des appels Apex synchrones à partir des déclencheurs.

Taille de lot d’un déclencheur
La taille de lot maximale dans un déclencheur d’événements de plate-forme s’élève à 2 000 messages d’événement, ce qui est supérieur à la taille de lot d’un déclencheur d’objets Salesforce qui, elle, est de 200. La taille de lot correspond à la taille de la liste Trigger.New. Vous pouvez contrôler la taille de lot d’un déclencheur d’événements de plate-forme et récupérer des exceptions limites et non capturées en définissant un point de contrôle. Pour en savoir plus, reportez-vous à la page Traitement de messages d’événement de plate-forme en petits lots dans les déclencheurs Apex dans le Guide du développeur d’événements de plate-forme.

Vous pouvez consulter l'état de tous les déclencheurs d’événements sur la page Détails de définition d'événement de plate-forme, dans Configuration. Sous Souscriptions, chaque déclencheur actif est indiqué avec ses informations d’exécution et son état. Les informations incluent l’ID de relecture des derniers événements publiés et traités. L’état indique si le déclencheur est en cours d’exécution ou s'il est déconnecté de la souscription en raison d’erreurs irrécupérables ou d'autorisations insuffisantes. L'état d’erreur n’est atteint que lorsque le nombre maximal de tentatives autorisées pour le déclencheur a été dépassé. La capture d'écran montre la liste associée de souscriptions sur la page de détails de l'événement Cloud News.

Remarque

Remarque

  • La liste associée Abonnements répertorie également les flux et les processus qui sont abonnés à l’événement. 
  • La liste associée Abonnements n’inclut pas les abonnés qui utilisent CometD ou le composant Lightning empApi. Nous reviendrons plus loin dans cette unité sur les autres types d’abonnés. 
  • Pour les événements de plate-forme haut volume, la valeur de l’ID de dernier publié n’est pas disponible et est toujours affichée comme Non disponible.

Gestion des abonnés au déclencheur Apex d’un événement

Reprenez un abonnement suspendu là où il s’était arrêté, en commençant par le premier message d’événement disponible dans le bus d’événements. Si vous souhaitez contourner des messages d’événement qui provoquent des erreurs ou qui ne sont plus nécessaires, vous pouvez reprendre l’abonnement par la fin, en commençant par les nouveaux messages d’événement.

Pour gérer un abonnement au déclencheur, dans la liste associée Abonnements, cliquez sur Gérer à côté du déclencheur Apex.

Dans la page de détails de l’abonnement, choisissez l’action appropriée.
  • Pour suspendre un abonnement en cours, cliquez sur Suspendre.

  • Pour reprendre un abonnement suspendu, en commençant par le premier message d’événement disponible dans le bus d’événements, cliquez sur Reprendre.
  • Pour reprendre un abonnement suspendu, en commençant par les nouveaux messages d’événement, cliquez sur Reprendre par la fin.


Vous ne pouvez pas gérer les abonnements des flux et processus à partir de la liste associée Abonnements.

Remarque

Remarque

Lorsque vous enregistrez un déclencheur, l’abonnement au déclencheur reprend automatiquement. Pour plus d’informations, consultez la page Affichage et gestion des abonnés à un événement sur la page de détail de l’événement de plate-forme dans le Guide du développeur d’événements de plate-forme.

Test des déclencheurs d'événements de plate-forme

Vérifiez que votre déclencheur d'événement de plate-forme fonctionne correctement en ajoutant un test Apex. Avant de pouvoir empaqueter et déployer du code Apex (déclencheurs inclus) en production, celui-ci doit subir des tests. Pour publier des événements de plate-forme dans un test Apex, encadrez les déclarations de publication entre des énoncés Test.startTest et Test.stopTest.

// Create test events
Test.startTest();
// Publish events
Test.stopTest();
// Perform validation here

Dans un contexte de test, l'appel de la méthode de publication est mis en file d'attente jusqu'à l'opération de publication. L'énoncé Test.stopTest() entraîne la publication de l'événement. Après Test.stopTest(), procédez à vos validations.

Voici un exemple de classe de test pour notre événement Cloud_News et son déclencheur associé. La publication de l'événement provoque le lancement du déclencheur associé. Après Test.stopTest(), le test vérifie que la publication a réussi en inspectant la valeur renvoyée par isSuccess() dans Database.SaveResult. Le test interroge également le cas créé par le déclencheur. S'il trouve l'enregistrement du cas, le déclencheur s'est bien exécuté et le test est réussi.

@isTest
public class PlatformEventTest {
    @isTest static void test1() {
        // Create test event instance
        Cloud_News__e newsEvent = new Cloud_News__e(
            Location__c='Mountain City',
            Urgent__c=true,
            News_Content__c='Test message.');
        Test.startTest();
        // Call method to publish events
        Database.SaveResult sr = EventBus.publish(newsEvent);
        Test.stopTest();
        // Perform validation here
        // Verify that the publish was successful
        System.assertEquals(true, sr.isSuccess());
        // Check that the case that the trigger created is present.
        List<Case> cases = [SELECT Id FROM Case];
        // Validate that this case was found.
        // There is only one test case in test context.
        System.assertEquals(1, cases.size());
    }
}

Abonnement à des notifications d’événements de plate-forme avec un déclencheur Lightning

Les applications Lightning peuvent utiliser le composant Aura ou Lightning Web empApi pour s’abonner aux événements de l’application.

Abonnement dans un composant Lightning Web

Pour utiliser les méthodes empApi dans votre composant Lightning Web, importez-les à partir du module lightning/empApi en écrivant le code suivant.

import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled }
    from 'lightning/empApi';

Appelez ensuite les méthodes importées dans votre code JavaScript.

Pour consulter un exemple d’utilisation du module lightning/empApi et obtenir la référence complète, reportez-vous à la documentation de lightning-emp-api dans la Bibliothèque de composants Lightning.

Abonnement dans un composant Aura

Pour utiliser les méthodes empApi dans votre composant Aura, ajoutez le composant lightning:empApi à votre composant personnalisé et donnez-lui l’attribut aura:id.

<lightning:empApi aura:id="empApi"/>

Ajoutez ensuite des fonctions pour appeler les méthodes de composant dans le contrôleur côté client.

Pour consulter un exemple d’utilisation du composant lightning:empApi et obtenir la référence complète, reportez-vous à la documentation de lightning:empApi dans la Bibliothèque de composants Lightning.

Souscrire à des notifications d'événements de plate-forme en utilisant seulement la souris

Pour s'abonner à des messages d’événements sans utiliser de code, créez un processus qui commence lorsqu’un événement de plate-forme est reçu.

Cette capture d’écran montre qu’un processus démarre quand un événement Cloud News est reçu. À ce moment-là, le processus recherche un enregistrement de contact dont la ville correspond à la localisation de la notification de l’événement.

Écran des critères de correspondance du Générateur de processus

De la même manière, vous pouvez souscrire à un événement de plate-forme avec les flux en utilisant un élément Pause. Au lieu de commencer un flux quand un événement de plate-forme se produit, un flux démarré précédemment est mis en attente jusqu’à la réception d’un message d’événement de plate-forme et reprend à ce moment-là. Par exemple, voici un élément Interrompre qui attend que Salesforce reçoive un message d’événement Cloud News. Le flux ne reprendra que si le lieu de l’événement correspond à {!contact.MailingCity}. {!contact} est une variable d’enregistrement présente dans le flux qui stocke les valeurs d’un enregistrement de contact.

Configuration d’interruption dans Flow Builder

Souscrire à des notifications d'événements de plate-forme avec CometD

Les applications externes souscrivent à des événements de plate-forme avec CometD et effectuent des sondages longs. Le composant Lightning empApi et les pages Visualforce, qui s’exécutent sur la plate-forme, peuvent également utiliser CometD et sont considérés comme des clients CometD. CometD est un bus de routage d'événements évolutif et basé sur HTTP qui utilise un modèle de technologie push AJAX appelé Comet. C'est une implémentation du protocole Bayeux. Le sondage long, également appelé programmation Comet, permet d'émuler un push d'informations depuis un serveur à destination d'un client. Comme dans le cas d'un sondage classique, le client se connecte au serveur et lui demande des informations. Toutefois, au lieu d'envoyer une réponse vide si les informations ne sont pas disponibles, le serveur retient la requête et attend qu'elles le soient (autrement dit, qu'un événement se produise).

Salesforce fournit une librairie Java, EMP Connector, qui implémente tous les détails de la connexion à CometD et de l'écoute d'un canal. Vous pouvez utiliser EMP Connector pour souscrire facilement à des événements de plate-forme. EMP Connector dissimule les aspects complexes de l'abonnement à des événements. Pour plus d'informations sur EMP Connector, consultez l'exemple de client Java dans le guide Streaming API Developer Guide.

Le processus de souscription à des notifications d'événements de plate-forme via CometD est similaire à la souscription à des événements PushTopic ou à des événements génériques. La seule différence réside dans le nom du canal. Le nom du canal d’un événement de plate-forme est sensible à la casse et a le format suivant.

/event/<EventName>__e

Par exemple, si vous avez un événement de plate-forme nommé Cloud News, fournissez ce nom de canal au moment de la souscription.

/event/Cloud_News__e

Spécifiez la version de l'API à la fin de l'URL CometD, comme suit.

// Connect to the CometD endpoint
    cometd.configure({
               url: 'https://<Salesforce_URL>/cometd/48.0/',
               requestHeaders: { Authorization: 'OAuth <Session_ID>'}
    });

Messages d'événements de plate-forme au format JSON

Le message d'un événement de plate-forme délivré est semblable à l'exemple suivant d'événement Cloud News.

{
  "data": {
    "schema": "_2DBiqh-utQNAjUH78FdbQ",
    "payload": {
      "CreatedDate": "2017-04-27T16:50:40Z",
      "CreatedById": "005D0000001cSZs",
      "Location__c": "San Francisco",
      "Urgent__c": true,
      "News_Content__c": "Large highway is closed due to asteroid collision."
    },
    "event": {
      "replayId": 2
    }
  },
  "channel": "/event/Cloud_News__e"
}

Le champ de schéma du message d'événement contient l'ID du schéma d'événement de plate-forme (dans cet exemple, il s'agit de "schema": "_2DBiqh-utQNAjUH78FdbQ"). Les versions du schéma sont gérées : quand le schéma change, l'ID de schéma change également.

Pour déterminer si le schéma d'un événement a changé, récupérez le schéma via l'API REST. Utilisez l'ID de schéma en effectuant une requête GET sur cette ressource API REST : /vXX.X/event/eventSchema/Schema_ID. Vous avez aussi la possibilité de récupérer le schéma d'événement en fournissant le nom de l'événement à ce terminal : /vXX.X/sobjects/Platform_Event_Name__e/eventSchema. Pour plus d’informations, reportez-vous au guide du développeur d’API REST.

Remarque

Remarque

Contrairement aux événements PushTopic et génériques, les événements de plate-forme ne prennent pas en charge les souscriptions filtrées. Par exemple, la souscription à /event/Cloud_News__e?Location__c='San Francisco' pour appliquer un filtrage par localisation n'est pas prise en charge.

Maintenant que vous avez vu comment utiliser les événements de plate-forme dans Salesforce et dans des applications externes, les possibilités sont infinies ! Utilisez les événements de plate-forme pour tous types d'applications et d'intégrations : traitement de transactions commerciales, opérations de service client proactives. Avec les événements de plate-forme, vous pouvez adopter un modèle de programmation orienté événement et profiter de tous les avantages d'une architecture logicielle basée sur les événements.