Abonnements aux 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

Remarque

Vous souhaitez apprendre en français ? Commencez le défi dans un Trailhead Playground en français et utilisez les traductions fournies entre crochets pour naviguer. Copiez et collez uniquement les valeurs en anglais, car les validations de défi reposent sur les données en anglais. Si vous ne réussissez pas le défi dans votre organisation en français, nous vous recommandons (1) de définir le paramètre régional sur les États-Unis, (2) de définir la langue sur l’anglais en suivant les instructions ici, puis (3) de cliquer à nouveau sur le bouton « Vérifier le défi ».

Consultez le badge Trailhead dans votre langue pour découvrir comment profiter de l’expérience Trailhead traduite.

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 Salesforce Platform, vous vous abonnez à des événements à l’aide de déclencheurs Apex, de processus, de flux et du composant Lightning empApi. Dans une application externe, vous vous abonnez à des événements à l’aide de l’API Pub/Sub.

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.

Dans le menu d’accès rapide ( ), cliquez sur Developer Console, puis sur File (Fichier) | New (Nouveau) | Apex Trigger (Déclencheur Apex).
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.

Avant d’exécuter cet exemple, créez une file d’attente avec une étiquette Distribution régionale. Pour savoir comment configurer une file d’attente, consultez Configuration des files d’attente dans l’aide Salesforce. Pour plus d’informations sur l’objet Group (Groupe), qui représente une file d’attente, consultez Groupe dans la référence d’objet pour Salesforce et la plate-forme Lightning.

Cet exemple affecte des requêtes à une file d’attente. Les files d’attente ne font pas partie des événements de plate-forme et vous n’avez pas besoin de vous en servir pour utiliser les événements de plate-forme. L’affectation de requêtes à une file d’attente permet de distribuer des requêtes à une équipe d’agents de support qui sont membres de la file d’attente.

// 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.

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

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 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 à ce que le résultat de l’exécution d'un déclencheur soit disponible immédiatement après la publication d'un événement.

Utilisateur système Processus automatisé

Comme les déclencheurs d’événement de plate-forme ne sont pas exécutés sous l’identité de l’utilisateur qui les exécute (l’utilisateur actif), mais sous celle de l’utilisateur système Automated Process (Processus automatisé), nous définissons explicitement le champ Owner ID (ID de propriétaire) dans notre exemple 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é. De même, l’instruction Apex UserInfo.getUserId() renvoie l’entité Processus automatisé.

Vous pouvez remplacer l’utilisateur actif d’un déclencheur d’événements de plate-forme afin que le déclencheur s’exécute sous cet utilisateur au lieu du processus automatisé. Configurez le déclencheur à l’aide de PlatformEventSubscriberConfig dans l’API de métadonnées ou l’API Tooling. Pour plus d’informations, consultez Configuration de l’utilisateur et de la taille du lot pour votre déclencheur d’événements de plate-forme dans le Guide pour développeurs d’événements de plate-forme.

Limitations des gouverneurs Apex

Comme les 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 de nombreuses limitations des déclencheurs d'objets personnalisés et standard. Par exemple, vous ne pouvez pas exécuter d'appels Apex synchrones à partir de déclencheurs.

Taille de lot d’un déclencheur

La taille de lot 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 modifier la taille de lot d’un déclencheur d’événements de plate-forme. Pour plus d’informations, consultez Configuration de l’utilisateur et de la taille du lot pour votre déclencheur d’événement de plate-forme dans le Guide pour développeurs 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.

La liste associée Abonnements répertorie également les flux et les processus qui sont abonnés à l’événement.
La liste associée Subscriptions (Abonnements) n’inclut pas les abonnés qui utilisent l’API Pub/Sub 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

En tant qu’administrateur système, vous pouvez reprendre 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.

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.

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.

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 démarrer un flux lors de la réception d’un message d’événement de plate-forme, créez un flux déclenché par un événement de plate-forme. Dans l’élément Démarrer, choisissez un événement de plate-forme dont les messages d’événement déclenchent l’exécution du flux.

Lors de la création du flux, vous pouvez utiliser les valeurs de champ du message d’événement de plate-forme en référençant la variable globale $Record.

Vous avez également la possibilité de souscrire à un événement de plate-forme avec les flux en utilisant un élément Pause. Au lieu de démarrer un flux lors de la réception d’un message d’événement de plate-forme, ce message d’événement provoque la reprise d’une interview de flux interrompue. Par exemple, voici un élément Pause qui interrompt le flux jusqu’à ce 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}. La variable d’enregistrement {!contact} stocke les valeurs d’un enregistrement de contact.

Configuration d’interruption dans Flow Builder

L’API Pub/Sub fournit une interface unique pour la publication et l’abonnement à des événements de plate-forme. Basée sur l’API gRPC et HTTP/2, l’API Pub/Sub publie et diffuse efficacement des messages d’événement binaires au format Apache Avro. gRPC est une infrastructure d’appel de procédure à distance (RPC) open source qui permet de connecter des appareils, des applications mobiles et des navigateurs à des services back-end. Pour en savoir plus, consultez la Documentation gRPC. Apache Avro est un système de sérialisation des données. Pour plus d’informations, reportez-vous à Apache Avro.

L’API Pub/Sub utilise un modèle d’abonnement pull dans lequel le client demande un certain nombre d’événements au serveur en fonction de sa capacité de traitement. Contrairement aux abonnements push, avec lesquels un client attend de recevoir automatiquement de nouveaux événements depuis le serveur, avec un abonnement pull, un client demande de manière proactive de recevoir des événements depuis le serveur. Ce contrôle de flux d’événements garantit que le client ne soit pas submergé par plus d’événements qu’il ne peut gérer en cas de pic de publication d’événements.

Voici quelques avantages offerts par l’API Pub/Sub :

Une seule API rassemble la publication, la souscription et la récupération de schéma d’événement.
Les résultats des opérations de publication sont définitifs (et non les résultats de mise en file d’attente intermédiaires).
Un contrôle de flux qui vous permet de spécifier le nombre d’événements à recevoir dans un appel d’abonnement en fonction de la vitesse de traitement des événements du client.
Un flux de données en temps réel et très performant qui utilise la compression via HTTP/2.
La prise en charge de 11 langages de programmation dans le client proposés par l’API gRPC, tels que Python, Java, Node et C++. Pour connaître tous les langages pris en charge, voir https://grpc.io/docs/languages/.

Un client de l’API Pub/Sub peut récupérer séparément le schéma, l’ID de relecture et la charge utile de l’événement reçu, puis décoder la charge utile. Par exemple, la charge utile de l’événement Cloud News reçu ressemble à ce message.

{
  "CreatedDate": 1652978695951,
  "CreatedById": "005SM000000146PYAQ",
  "Location__c": "San Francisco",
  "Urgent__c": true,
  "Ink_Percentage__c": "Large highway is closed due to asteroid collision."
}

Pour plus d’informations, consultez la documentation de l’API Pub/Sub.

Maintenant que vous avez vu comment utiliser les événements de plate-forme dans Salesforce Platform 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.

Ressources

Besoin d'aide ?

En savoir plus

Abonnements aux vénements de plate-forme

Objectifs de formation

Remarque

Configurer la journalisation de débogage

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

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

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

Besoin d'aide ?

En savoir plus

Abonnements aux vénements de plate-forme

Objectifs de formation

Remarque