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. 

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

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.

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.

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.

1. Depuis le 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());
        }
    }
}

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. 

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

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 messages d’événement de plate-forme, comme SOAP, REST ou l’API de transfert en masse. 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.

1. Connectez-vous à votre organisation Trailhead DE.
2. Ouvrez l’application Postman, sélectionnez un espace de travail et accédez à votre copie de la collection d’API Salesforce.
3. Dans l’onglet Autorisation, faites défiler l’écran vers le bas et cliquez sur Obtenir un nouveau jeton d’accès.
4. Cliquez sur Autoriser.
5. Dans la boîte de dialogue Gérer les jetons d’accès, copiez l’URL d’instance dans votre presse-papiers.
6. Cliquez sur Utiliser le jeton.
7. 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.
8. Vérifiez que votre connexion fonctionne.
   1. Dans Collections, sélectionnez votre copie de la collection d’API Salesforce.
   2. Sélectionnez REST pour étendre les API REST.
   3. Sélectionnez GET Limits, puis cliquez sur Envoyer.
   4. 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.

1. Dans votre copie de la collection d’API Salesforce, cliquez sur REST.
2. Cliquez sur SObjectpour l’étendre.
3. Cliquez sur POST SObject Create.
4. Dans l’onglet Params (Paramètres), sous Path Variables (Variables de chemin), pour SOBJECT_API_NAME, saisissez Cloud_News__e.
5. 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."
   }

6. 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": []
          }
      ]
   }

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. Vous avez aussi la possibilité d’utiliser l’API Pub/Sub pour publier des messages d’événement, ce qui est pratique si vous utilisez également l’API Pub/Sub pour vous abonner aux messages d’événement. Pour plus d’informations, consultez la documentation de l’API Pub/Sub.

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

• Streaming API Developer Guide : Message Durability
• Platform Events Developer Guide : Platform Event Allocations
• Guide du développeur Apex : Execution Governors and Limits
• Aide Salesforce : Flux
• Trailhead : Prise en main rapide : Connecter Postman à Salesforce
• Aide externe : Centre de formation de Postman
• Documentation de l’API Pub/Sub
• REST API Developer Guide
• SOAP API Developer Guide
• Bulk API Developer Guide