Suivez votre progression
Accueil Trailhead
Accueil Trailhead

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énements de plate-forme.
  • 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.

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 :

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

Remarque

Remarque

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 des clients API CometD. 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 enregistrements d'événement, vous ne pouvez pas y accéder par SOQL ni SOSL. De même, vous ne pouvez pas utiliser les enregistrements d'événements de l’interface utilisateur dans des rapports, des vues de liste et des recherches. Vous ne pouvez récupérer d'anciens événements qu’en souscrivant à CometD et en utilisant une option ReplayID. Nous verrons dans la prochaine unité comment souscrire à des événements.

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.

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 et dans l’API Enterprise.

É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 d’outils déclaratifs comme le Générateur de processus ou le Flow Builder. Si votre application est une application externe, vous pouvez publier des événements à l'aide des API Salesforce.

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 requête de publication est mise en file d’attente dans Salesforce pour cet événement de plate-forme haut volume. Il est possible que le message d’événement ne soit pas publié immédiatement. 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.

  1. Depuis le menu d’accès rapide ( Menu d'accès rapide), sélectionnez Developer Console.
  2. Cliquez sur Débogage | Ouvrir une fenêtre d’exécution anonyme.
  3. 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());
        }
    }
}
Remarque

Remarque

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 un processus ou un flux.

Cette capture d'écran présente un exemple d'action Création d'un enregistrement dans le Générateur de processus, qui a pour effet de publier un message d'événement Cloud News. Pour résumer, choisissez le Type d'enregistrement correspondant à l'événement de plate-forme que vous voulez publier (Cloud News), puis définissez les valeurs de l'événement.

L'action Créer un enregistrement du Générateur de processus est réglée sur le type d'enregistrement Cloud News. Les champs de l'événement Cloud News sont renseignés.


De la même manière, vous pouvez publier un message d'événement de plate-forme avec un flux. 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 publiez des événements en créant des enregistrements de l’événement de la même façon que vous insérez des sObjects. Vous pouvez utiliser les API Salesforce pour créer des enregistrements d'événement de plate-forme, comme SOAP, REST ou l’API de transfert en masse.

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 :

/services/data/v45.0/sobjects/Cloud_News__e/

Corps d’une requête POST :

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

Une fois que l’enregistrement d'événement de plate-forme est créé, vous recevez une réponse REST semblable à ce qui suit. Les en-têtes ont été supprimés pour alléger le contenu.

HTTP/1.1 201 Created
{
   "id" : "e00xx000000000B",
   "success" : true,
   "errors" : [ ],
   "warnings" : [ ]
}

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 Workbench en suivant les étapes ci-dessous.

  1. Connectez-vous à votre organisation Trailhead DE.
  2. Ouvrez un nouvel onglet et accédez à Workbench à l’adresse https://workbench.developerforce.com/login.php
  3. Pour Environnement, sélectionnez Production.
  4. Pour la version d'API, sélectionnez le nombre le plus élevé.
  5. Sélectionnez J'accepte les conditions d'utilisation.
  6. Cliquez sur Se connecter avec Salesforce.
  7. Sur l'écran suivant, cliquez sur Autoriser.
  8. Dans le menu supérieur, sélectionnez utilitaires | Explorateur REST.
  9. Cliquez sur POST.
  10. Remplacez l’URI par :
    /services/data/v45.0/sobjects/Cloud_News__e
  11. Pour le corps de la requête, ajoutez le contenu suivant au format JSON.
    {
       "Location__c" : "Mountain City",
       "Urgent__c" : true,
       "News_Content__c" : "Lake Road is closed due to mudslides."
    }
  12. Cliquez sur Exécuter. 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" : [ ],
      "warnings" : [ ]
    }

Vous pouvez également publier un événement à l’aide de l’API SOAP, via l’appel create(), ou de l’API de transfert en masse en utilisant une tâche par lot.

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