Définition et publication des événements de plate-forme

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

Définir un événement de plate-forme.
Expliquer comment publier des messages d’événement de plate-forme dans Apex
Utiliser une méthode Apex pour publier un événement.
Publier un événement à l’aide de clics dans un processus ou un flux
Publier un événement à l’aide de l’API REST en insérant un sObject.

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.

Définition et publication des événements de plate-forme

Maintenant que vous savez ce que sont les événements de plate-forme et comment les utiliser, passons aux choses sérieuses : définissez le vôtre ! Vous vous souvenez de l’agence Cloud News ? Nous allons créer une définition d’événement de plate-forme contenant les données des événements d'actualité.

Définissez un événement de plate-forme nommé Cloud News :

Dans Configuration, saisissez Événements de plate-forme dans la zone Recherche rapide, puis sélectionnez Événements de plate-forme.
Sur la page Événements de plate-forme, cliquez sur Nouvel événement de plate-forme.
Dans Étiquette, saisissez Cloud News.
Dans Étiquette au pluriel, saisissez Cloud News.
Dans Description, saisissez Grâce aux évènements Cloud News, vous avez l’actualité à portée de main.
Pour Comportement de publication, conservez la valeur par défaut de Publier après l’interaction.
Cliquez sur Enregistrer.
Dans la liste associée Champs personnalisés et relations, cliquez sur Nouveau.
Sélectionnez Texte, puis cliquez sur Suivant.
Dans Étiquette/Nom du champ, saisissez Lieu.
Dans Longueur, saisissez 100. Conservez les paramètres par défaut des autres champs et laissez le champ Description vide. Cliquez sur Enregistrer.
Suivez les étapes 7, 8 et 9 pour ajouter les deux champs suivants :

Nom/étiquette de champ	Type de champ
Urgent	Case à cocher
News Content	Zone de texte (longue)

Pour l’événement Cloud News que vous venez de définir, vous avez créé divers types de champs comme des champs de texte et une case à cocher. Les événements de plate-forme sont compatibles avec les types de champ suivants :

Case à cocher
Date
Date/heure
Numéro
Texte
Zone de texte (longue)

Rétention des événements et champ système ReplayId

Salesforce conserve les événements de plate-forme haut volume pendant 72 heures dans le bus d’événements. Les événements volume standard définis avant la version Spring ’19 sont stockés pendant 24 heures dans le bus d’événements.

Les événements nouvellement définis sont par défaut haut volume. Les événements volume standard sont les prédécesseurs des événements haut volume ; vous ne pouvez plus définir de tels événements.

Vous pouvez récupérer les événements stockés à partir du bus d’événements à l’aide de l’API Pub/Sub. Vous pouvez récupérer tous les événements stockés ou spécifier l’ID de relecture d’un événement comme référence pour la portion d'événements à renvoyer. Avec les déclencheurs Apex, vous pouvez reprendre un déclencheur suspendu et récupérer les premiers événements non traités qui ont été conservés. Nous reviendrons plus loin dans ce module sur la manière de gérer les abonnements aux déclencheurs Apex.

Bien que Salesforce conserve temporairement les messages d’événement, vous ne pouvez pas y accéder par SOQL ni SOSL. De même, vous ne pouvez pas utiliser les messages d’événement de l’interface utilisateur dans des rapports, des vues de liste et des recherches.

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

Suffixe de nom d’API

Quand vous créez un événement de plate-forme, le système ajoute le suffixe __e pour créer le nom d’API de l'événement. Par exemple, le nom d’API de l'événement Cloud News est Cloud_News__e. Utilisez le nom d’API quand vous désignez l’événement dans du code, par exemple dans Apex, dans l’API REST ou dans l’API Pub/Sub.

Événements de plate-forme et transactions

Les événements de plate-forme configurés avec le comportement de publication Publier après l’interaction sont de nature transactionnelle et peuvent être annulés. Par contre, ceux configurés avec le comportement de publication Publier immédiatement ne sont pas de nature transactionnelle et ne peuvent pas être annulés. Notez les différences suivantes entre les comportements.

Comportement de publication Publier après l’interaction

Un événement de plate-forme configuré avec le comportement Publier après l’interaction est publié uniquement après qu’une transaction a été validée. Choisissez cette option si les abonnés se servent de données validées par la transaction de publication. Dans ce type de cas de figure, un premier processus peut, par exemple, publier un message d’événement et créer un enregistrement de tâche. Ensuite, un second processus, abonné à l’événement, est déclenché et recherche alors l’enregistrement de tâche. Vous pouvez également opter pour ce comportement lorsque vous ne souhaitez pas que le message d’événement soit publié en cas d’échec de la transaction.

Comportement de publication Publier immédiatement

Un événement de plate-forme configuré avec le comportement Publier immédiatement est publié lors de l’exécution de l’appel de publication. Choisissez cette option si vous souhaitez que le message d’événement soit publié dans tous les cas, que la transaction aboutisse ou non. Choisissez-la également si l’éditeur et les abonnés sont indépendants et si les abonnés ne se servent pas des données validées par l’éditeur. Ce comportement convient, par exemple, à un événement utilisé à des fins de consignation. Grâce à cette option, un abonné peut recevoir le message d’événement avant que les données ne soient validées par la transaction de publication.

Publier des événements

Si votre application se trouve sur la plate-forme Salesforce, vous pouvez publier des événements à l’aide d’une méthode Apex ou de l’outil déclaratif Flow Builder. Si votre application est une application externe, vous pouvez publier des événements à l’aide des API Salesforce, notamment l’API Pub/Sub et les API de données, comme l’API REST.

Publication des messages d'événements à l’aide Apex

Pour publier des messages d’événements, vous devez créer une instance de l’événement et la transmettre à la méthode EventBus.publish().

L’exemple ci-dessous crée un événement de type Cloud_News__e, le publie, puis vérifie si la publication a réussi ou si elle a été sujette à des erreurs. La méthode EventBus.publish() renvoie un objet Database.SaveResult qui contient le résultat de la publication. Si isSuccess () renvoie true, la demande de publication est mise en file d’attente dans Salesforce et le message d’événement est publié de manière asynchrone. Si isSuccess() renvoie false, l’opération de publication de l’événement a entraîné des erreurs, qui sont renvoyées dans l’objet Database.Error. Cette méthode ne renvoie pas d’exception si l’opération de publication échoue.

Vous pouvez exécuter l’extrait de code Apex dans la Developer Console.

Depuis le menu d’accès rapide ( ), sélectionnez Developer Console.
Cliquez sur Débogage | Ouvrir une fenêtre d’exécution anonyme.

Dans la nouvelle fenêtre, remplacez le contenu par l’extrait de code, puis cliquez sur Exécuter.

// Create an instance of the event and store it in the newsEvent variable
Cloud_News__e newsEvent = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=true,
           News_Content__c='Lake Road is closed due to mudslides.');
// Call method to publish events
Database.SaveResult sr = EventBus.publish(newsEvent);
// Inspect publishing result
if (sr.isSuccess()) {
    System.debug('Successfully published event.');
} else {
    for(Database.Error err : sr.getErrors()) {
        System.debug('Error returned: ' +
                     err.getStatusCode() +
                     ' - ' +
                     err.getMessage());
    }
}

Pour publier plusieurs événements lors du même appel, ajoutez vos événements à une liste d'événements et passez-la à la méthode EventBus.publish(). Le résultat de cette méthode est un tableau d'objets Database.SaveResult (un par événement publié). EventBus.publish() peut publier certains événements passés, même lorsque d'autres événements sont impubliables en raison d’erreurs. La méthode EventBus.publish() ne renvoie pas d’exception en cas d’échec d’une opération de publication. Elle est similaire à la méthode Apex Database.insert() appelée avec l'option de succès partiel.

// List to hold event objects to be published.
List<Cloud_News__e> newsEventList = new List<Cloud_News__e>();
// Create event objects.
Cloud_News__e newsEvent1 = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=true,
           News_Content__c='Lake Road is closed due to mudslides.');
Cloud_News__e newsEvent2 = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=false,
           News_Content__c='Small incident on Goat Lane causing traffic.');
// Add event objects to the list.
newsEventList.add(newsEvent1);
newsEventList.add(newsEvent2);
// Call method to publish events.
List<Database.SaveResult> results = EventBus.publish(newsEventList);
// Inspect publishing result for each event
for (Database.SaveResult sr : results) {
    if (sr.isSuccess()) {
        System.debug('Successfully published event.');
    } else {
        for(Database.Error err : sr.getErrors()) {
            System.debug('Error returned: ' +
                        err.getStatusCode() +
                        ' - ' +
                        err.getMessage());
        }
    }
}

Lorsque les ressources système deviennent disponibles, Salesforce publie les événements en file d’attente à partir de l’appel EventBus.publier() de manière asynchrone et les stocke dans le bus d’événements pendant une période de rétention spécifique. La plupart du temps, vous n’avez pas à vous soucier du résultat final de la publication des événements en file d’attente, car la publication finale réussit. Dans de rares cas, une erreur système interne peut se produire et entraîner l’échec de la publication asynchrone. Pour obtenir une confirmation du résultat final de la publication de l’événement, utilisez les rappels de publication Apex. Pour en savoir plus, consultez Obtention du résultat de la publication asynchrone d’événements de plate-forme avec les rappels de publication Apex dans le guide du développeur d’événements de plate-forme.

La plate-forme Salesforce alloue un nombre limité d’événements pouvant être définis dans votre organisation et d’événements que vous pouvez publier en une heure. Pour les événements configurés avec le comportement Publier après l’interaction, chaque exécution de méthode est comptabilisée comme une instruction DML par rapport à la limite d’instructions DML Apex. Vous pouvez vérifier la limite d’utilisation à l’aide de la méthode Apex Limits.getDMLStatements(). Pour les événements configurés avec le comportement Publier immédiatement, chaque exécution de méthode est comptabilisée dans une limite distincte de publication d’événements de 150 appels EventBus.publish(). Vous pouvez vérifier la limite d’utilisation à l’aide de la méthode Apex Limits.getPublishImmediateDML(). Pour en savoir plus, consultez la section Ressources.

Publication des messages d'événements à l’aide de Clicks

Pour publier des messages d’événements sans code, utilisez la fonctionnalité de création d’enregistrements dans Flow Builder. Configurez un élément Création d’enregistrement pour créer une instance de l’événement de plate-forme (Cloud_News__e), puis définissez les valeurs de l’événement. Pour définir la valeur d’un champ booléen comme Urgent__c, utilisez {!$GlobalConstant.True}.

Publication des messages d'événements à l’aide des API Salesforce

Les applications externes utilisent une API pour publier des messages d'événements de plate-forme. Vous pouvez publier des événements à l’aide de l’API Pub/Sub ou d’API de données, telles que l’API SOAP, l’API REST ou l’API de transfert en masse.

Lorsque vous utilisez des API de données, vous publiez des événements de la même manière que vous insérez des éléments sObjects. Comme avec Apex, le message d’événement est publié de manière asynchrone. Lorsque vous publiez un événement et obtenez un statut de réussite true, la demande de publication est mise en file d’attente dans Salesforce.

Par exemple, dans le cas de l’événement Cloud News, vous pouvez publier des notifications en insérant des enregistrements Cloud_News__e. L’exemple ci-dessous crée un événement de type Cloud_News__e dans l’API REST.

Terminal REST sObject :

Corps d’une requête POST :

Une fois que le message d’événement de plate-forme est créé, vous recevez une réponse REST semblable à ce qui suit.

Vous pouvez utiliser n’importe quel outil d’API REST ou application client HTTP pour faire des appels API REST. Vous pouvez par exemple utiliser Postman en suivant les étapes ci-dessous. Si vous n’avez pas encore utilisé Postman, consultez le projet Prise en main rapide : Connexion de Postman à Salesforce pour vous lancer et copier la collection d’API Salesforce. Pour en savoir plus sur Postman, référez-vous à la section Ressources.

Connectez votre organisation DE à Postman.

Connectez-vous à votre organisation Trailhead DE.
Ouvrez l’application Postman, sélectionnez un espace de travail et accédez à votre copie de la collection d’API Salesforce.
Dans l’onglet Autorisation, faites défiler l’écran vers le bas et cliquez sur Obtenir un nouveau jeton d’accès.
Cliquez sur Autoriser.
Dans la boîte de dialogue Gérer les jetons d’accès, copiez l’URL d’instance dans votre presse-papiers.
Cliquez sur Utiliser le jeton.
Dans l’onglet Variables, dans la ligne _endpoint, dans la colonne VALEUR ACTUELLE, collez l’URL de l’instance que vous venez de copier, puis cliquez sur Enregistrer. Vous devrez peut-être fermer le volet de documentation pour voir le bouton Enregistrer.
Vérifiez que votre connexion fonctionne.

Dans Collections, sélectionnez votre copie de la collection d’API Salesforce.
Sélectionnez REST pour étendre les API REST.
Sélectionnez GET Limits, puis cliquez sur Envoyer.
Dans la fenêtre de réponse, le champ Statut doit afficher Statut : 200 OK. Si ce n’est pas le cas, répétez les étapes pour obtenir un nouveau jeton.

Effectuez un appel d’API REST pour publier des notifications d’événements.

Dans votre copie de la collection d’API Salesforce, cliquez sur REST.
Cliquez sur SObjectpour l’étendre.
Cliquez sur POST SObject Create.
Dans l’onglet Params (Paramètres), sous Path Variables (Variables de chemin), pour SOBJECT_API_NAME, saisissez Cloud_News__e.

Dans l’onglet Body (Corps), collez le corps JSON suivant.

{
   "Location__c" : "Mountain City",
   "Urgent__c" : true,
   "News_Content__c" : "Lake Road is closed due to mudslides."
}

Cliquez sur Envoyer. La réponse renvoyée par Salesforce après la publication de l’événement est semblable à ce qui suit.

{
  "id" : "e00xx0000000001AAA",
  "success" : true,
  "errors" : [
       {
            "statusCode": "OPERATION ENQUEUED",
            "message": "08ffc869-b9f8-4cff-a4ba-8dff9b3dd6cb",
            "fields": []
       }
   ]
}

Maintenant que vous savez comment définir et publier des événements, voyons comment y souscrire !

Ressources

Besoin d'aide ?

En savoir plus