Découvrir les caractéristiques de la Capture des données de modification

Objectifs de formation

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

• Déterminer quels objets sont compatibles avec la capture des données de modification
• Répertorier les champs renvoyés dans l’en-tête d’événement de modification et citer les champs inclus dans le corps du message pour chaque opération
• Créer un nom de canal d’événement de modification
• Répertorier les autorisations nécessaires pour s’abonner aux événements de modification

Prise en charge d’objet

La Capture des données de modification peut générer des événements de modification pour tous les objets personnalisés définis dans votre organisation Salesforce et pour un sous-ensemble d’objets standard. Elle prend en charge les événements de modification des objets standard les plus populaires, notamment Account, Contact, Lead, User, Order, OrderItem, Product2, et d’autres encore. Pour obtenir la liste des objets qui prennent en charge les événements de modification, reportez-vous à la section StandardObjectNameChangeEvent dans l’article Référence d’objet pour Salesforce et la plate-forme Lightning.

Pour recevoir des notifications de modification d’enregistrement, sélectionnez les objets personnalisés et les objets standard pris en charge qui vous intéressent sur la page Capture des données de modification dans Configuration. Nous passerons en revue les étapes permettant de sélectionner des objets plus tard dans ce module.

Exemple d’événement de modification

Vous vous souvenez de Robert ? Son client, un service de conseil, a défini un objet personnalisé appelé Employee__c, qui fait partie d’une application RH personnalisée gérant les données des employés. Pour synchroniser les données des employés dans Salesforce avec le système RH externe, Robert a créé une application qui reçoit et intègre les événements de modification pour les enregistrements d’employés nouveaux et modifiés. 

Regardons un exemple de message d’événement reçu par son application. Il contient les données d’un nouvel enregistrement d’employé créé par un utilisateur dans Salesforce. Notez les valeurs des champs changeType et entityName.

{
  "schema": "-pszPCNGMHqUPU1ftkjxEA",
  "payload": {
    "ChangeEventHeader": {
      "commitNumber": 65824495947,
      "commitUser": "005RM000001vI4mYAE",
      "sequenceNumber": 1,
      "entityName": "Employee__c",
      "changeType": "CREATE",
      "changedFields": [],
      "changeOrigin": "com/salesforce/api/soap/47.0;client=SfdcInternalAPI/",
      "transactionKey": "0005163c-8d04-d729-39bd-b917b035a66c",
      "commitTimestamp": 1569436136000,
      "recordIds": [
        "a00RM0000004ICOYA2"
      ]
    },
    "First_Name__c": "Jane",
    "Tenure__c": 2.0,
    "Name": "e-100",
    "Last_Name__c": "Smith",
    "CreatedDate": "2019-09-25T18:28:55.000Z",
    "LastModifiedDate": "2019-09-25T18:28:55.000Z",
    "OwnerId": "005RM000001vI4mYAE",
    "CreatedById": "005RM000001vI4mYAE",
    "LastModifiedById": "005RM000001vI4mYAE",
  },
  "event": {
    "replayId": 1
  }
}

Le message d’exemple d’événement de modification contient les champs d’employé relatifs au prénom, au nom et à l’ancienneté, ainsi que des zones système telles que la date de création. Pour un nouvel enregistrement, le message d’événement exclut les champs non définis par l’utilisateur. Par exemple, si l’utilisateur ne renseigne pas le champ concernant l’ancienneté, il sera exclu du message d’événement. 

Le champ ChangeEventHeader comprend des champs d’en-tête contenant des informations sur l’événement. Quelques champs d’en-tête importants sont répertoriés ci-dessous.

entityName

Ce champ contient le nom de l’objet standard ou personnalisé pour cette modification d’enregistrement. Dans cet exemple, il s’agit d’Employee__c.

changeType

Ce champ contient l’opération à l’origine de la modification. Pour les événements de modification courants, ce champ peut avoir l’une des valeurs suivantes : 

• CREATE
• UPDATE
• DELETE
• UNDELETE

Dans notre exemple, l’événement de modification correspondait à une création d’enregistrement : la valeur est donc CREATE.

changedFields

Utilisez ce champ pour déterminer quels champs ont été modifiés lors d’une opération de mise à jour. Ce champ reste vide pour les autres opérations. Comme l’exemple d’événement de modification concerne un nouvel enregistrement, le champ est ici vide. Les noms de champs ainsi que LastModifiedDate sont inclus dans changedFields lorsque vous mettez à jour un ou plusieurs champs. Par exemple, si First_Name__c est modifié, la valeur du champ serait ["LastModifiedDate", "First_Name__c"].

changeOrigin

Utilisez ce champ pour découvrir la cause de ce changement. Si votre application d’intégration modifie un enregistrement en réponse à une modification d’enregistrement du même objet, cela peut donner lieu à un cycle infini de modifications. Pour empêcher cela, utilisez ce champ pour détecter si votre application est à l’origine de la modification. Si c’est le cas, vous pourrez faire en sorte que la modification ne soit plus réalisée à nouveau et éviterez potentiellement un cycle de modifications approfondi. Ce champ contient l’ID de l’API Salesforce et l’ID de l’API client qui ont effectué la modification, si ce dernier a été défini par le client. Si des modifications ont été effectuées par des applications API ou depuis Lightning Experience, ce champ est renseigné conformément à ces dernières. Dans le cas contraire, il est vide.

Par exemple, si une application dont la valeur clientID est GetCloudy crée l’enregistrement d’employé via l’API SOAP, la valeur du champ changeOrigin est com/salesforce/api/soap/47.0;client=GetCloudy. Dans notre exemple, la valeur est com/salesforce/api/soap/47.0;client=SfdcInternalAPI/, ce qui signifie que la modification de l'enregistrement a été effectuée via l'interface utilisateur de Salesforce.

Champs d’en-tête liés à la transaction

Les champs d’en-tête suivants contiennent des informations sur la transaction de la modification en cours : 

• transactionKey
• sequenceNumber

Les champs de transaction vous permettent de conserver une copie précise des données de votre organisation dans un autre système. Le champ transactionKey identifie de manière unique la transaction à laquelle la modification appartient. Le champ sequenceNumber identifie l’ordre de la modification dans une transaction. Ce numéro de séquence est utile pour les opérations comportant plusieurs étapes, telles que la conversion des pistes ou la création d’enregistrements associés dans un déclencheur Apex après insertion. Si la capture des données de modification n’est pas activée pour tous les objets impliqués dans une transaction, les numéros de séquence ne se suivront pas. Nous vous recommandons de répliquer toutes les modifications d’une transaction dans une seule validation dans votre système. 

Si vous choisissez de ne pas utiliser de processus de réplication fondé sur les transactions, il est possible, si votre abonnement s’arrête, que vos données répliquées ne soient pas complètes. Par exemple, si votre abonnement s’arrête au milieu d’un flux d’événements pour une transaction, seule une partie des modifications de la transaction sera répliquée dans votre système.

Champ d’ID de lecture d’événement

La dernière partie du message d’événement comporte un champ appelé replayId. Ce champ contient un identifiant pour le message d’événement que vous pouvez utiliser pour lire les événements antérieurs pendant un maximum de 3 jours. Ce module n’aborde pas la lecture d’événements. Pour en savoir plus, consultez la section Ressources.

Champs inclus dans le corps d’un message d’événement

Les champs que Salesforce inclut dans un message d’événement que reçoit un client CometD dépendent de l’opération effectuée et du type d’abonné. Par exemple, pour un nouvel enregistrement, un message d’événement reçu dans un client CometD inclut tous les champs d’enregistrement et les champs système non vides. Cependant, dans un déclencheur Apex ou un client d’API Pub/Sub, le message d’événement inclut tous les champs d’enregistrement, qu’ils soient vides ou non, et les champs système. Pour plus d’informations, consultez la section Champs de corps de texte d’événements de modification du Guide du développeur de la Capture des données de modification.

Ordre des champs du message d’événement

Le respect de l’ordre des champs dans le message d’événement JSON n’est pas garanti. L’ordre suit le schéma Apache Avro sous-jacent, un système de sérialisation des données sur lequel reposent les événements de modification. Lorsqu’un événement est développé au format JSON, l’ordre des champs peut ne pas correspondre au schéma, selon le client utilisé pour recevoir l’événement.

Événements de modification fusionnés

Pour plus d’efficacité, les événements de modification d’une transaction sont parfois fusionnés en un seul événement si la même modification s’est produite dans plusieurs enregistrements du même type d’objet, dans la même seconde. Lorsque les événements de modification sont fusionnés, Salesforce envoie un événement de modification pour tous les enregistrements concernés. Le champ recordIds contient les ID de tous les enregistrements ayant subi la même modification. Pour en savoir plus, consultez la section Événements de modification fusionnés du Guide du développeur de la capture des données de modification.

Enrichissement des événements de modification avec des champs supplémentaires

Sélectionnez des champs pour enrichir les événements de modification fournis aux abonnés CometD. Les champs sélectionnés sont inclus dans les messages d’événement de modification même lorsqu’ils sont inchangés. Par exemple, procédez à un tel enrichissement lorsque votre application a besoin d’un champ d’ID externe pour faire correspondre les enregistrements dans un système externe. Ou incluez toujours un champ qui fournit des informations importantes sur l’enregistrement modifié. Pour plus d’informations, consultez la rubrique Enrichissement des événements de modification avec des champs supplémentaires dans le guide du développeur sur la capture des données de modification et le projet Trailhead Création d’un canal personnalisé et enrichissement des événements de modification.

Autres types d’événements : événements d’intervalle et événements de débordement

D’autres types d’événements de modification sont générés pour gérer des situations spéciales. Salesforce génère des événements d’intervalle lorsque des événements de modification ne peuvent pas être générés ou pour informer les abonnés des erreurs. Salesforce génère des événements de débordement lorsque le volume de modifications est important. Les événements d’intervalle et de débordement ne contiennent pas de données d’enregistrement. Les événements d’intervalle incluent l’ID de l’enregistrement, vous permettant de récupérer ses données. Pour plus d’informations, consultez Événements d’intervalle, Événements de débordement et Étapes de réplication globale dans le Guide du développeur sur la capture des données de modification.

Abonnement à un canal d’événement

Maintenant que vous savez à quoi ressemble un message d’événement de modification, voyons comment recevoir les événements de modification. Salesforce propose plusieurs façons de s’abonner à un canal d’événement de modification. Pour les applications externes à Salesforce, vous pouvez utiliser l’API Streaming, ou des outils et des bibliothèques fondés sur CometD, une bibliothèque open source qui simule la technologie push. L’API Streaming fournit un mécanisme d’abonnement basé sur CometD. 

Pour traiter les modifications de données de manière asynchrone sur la plate-forme Lightning, écrivez un déclencheur Apex pour l’événement de modification. Nous reviendrons sur les déclencheurs Apex relatifs aux événements de modification plus loin dans ce module.

Pour recevoir des notifications instantanées sur les modifications de données Salesforce dans une application exécutée sur la plate-forme Lightning, vous pouvez utiliser le composant lightning:empApi.

Vous indiquez quels événements votre application souhaite obtenir en l’abonnant à un canal. Votre application de diffusion en continu reçoit des événements en temps réel chaque fois qu’une modification a lieu dans Salesforce. 

Si vous souhaitez créer votre propre application à l’aide de l’API Streaming, consultez le guide pour les développeurs sur l’API Streaming. Le guide comprend des exemples de code pour s’abonner à l’aide de CometD. Pour créer une application de plate-forme Lightning à l’aide de empApi, consultez la documentation relative aux composants Web lightning-emp-api ou lightning:empApi Aura Component.   

Canaux d’abonnement

Un canal d’abonnement est un flux d’événements de modification qui correspondent à une ou plusieurs entités. Vous pouvez vous abonner au canal pour recevoir des notifications d’événements de modification relatives aux opérations de création, de mise à jour, de suppression et de restauration d’enregistrements. La capture des données de modification fournit des canaux standard prédéfinis et vous pouvez créer vos propres canaux personnalisés. 

Canaux standard

Le canal standard ChangeEvents contient, dans un flux unique auquel vous pouvez vous abonner, les événements de modification d’une ou plusieurs entités sélectionnées. Si vous prévoyez que plusieurs entités seront sujettes à des événements de modification, utilisez le canal standard ChangeEvents. Pour recevoir des événements de modification sur le canal ChangeEvents, sélectionnez les entités sur lesquelles doit porter la capture des données de modification. Vous apprendrez à sélectionner une entité impliquant des événements de modification un peu plus tard, dans l’unité suivante.

Si vous prévoyez qu’une seule entité sera sujette à des événements de modification, utilisez des canaux à entité unique. Ces derniers vous permettent de vous abonner aux événements de modification concernant un objet personnalisé ou standard précis.

Ce tableau vous montre comment spécifier le canal d’abonnement correspondant aux enregistrements pour lesquels vous souhaitez capturer les modifications.

Canaux personnalisés

Créez un canal personnalisé si vous avez plusieurs abonnés et que chacun reçoit des événements de modification émanant d’un ensemble différent d’entités. Vous pouvez également utiliser un canal personnalisé avec l’enrichissement d’événement pour isoler l’envoi de champs enrichis dans les événements de modification sur un canal spécifique. Les canaux personnalisés regroupent et isolent les événements de modification pour chaque abonné afin que ceux-ci ne reçoivent que les types d’événements dont ils ont besoin. Il est possible d’utiliser la capture des données de modification avec des entités données lorsque vous créez un canal personnalisé les incluant. Un canal personnalisé a le format suivant :

/data/YourChannelName__chn

Par exemple, si le nom de votre canal est SalesEvents, le canal d’abonnement est :

/data/SalesEvents__chn

Pour plus d’informations, reportez-vous à la section Utilisation des canaux personnalisés pour composer des flux de notifications de capture des données de modification du Guide du développeur de la Capture des données de modification.

Autorisations pour recevoir des événements de modification

La Capture des données de modification ignore les paramètres de partage et envoie des événements de modification pour tous les enregistrements d’un objet Salesforce. Pour recevoir des événements de modification dans un canal, l’utilisateur abonné doit disposer d’une ou plusieurs autorisations en fonction des entités associées aux événements de modification. Pour en savoir plus, consultez la section Autorisations requises pour les événements de modification du Guide du développeur de la capture des données de modification.

Sécurité au niveau du champ

La Capture des données de modification respecte les paramètres de sécurité au niveau du champ de votre organisation. Les événements fournis ne contiennent que les champs qu’un utilisateur abonné est autorisé à afficher. 

Dans l’unité suivante, vous apprendrez à utiliser un exemple d’outil open source, EMP Connector, pour vous abonner à un canal et recevoir des événements.

Ressources

• Guide du développeur de la Capture des données de modification
• Bibliothèque de composants Lightning : Composant Web lightning-emp-api
• Bibliothèque de composants Lightning : composant lightning:empApi
  
• Streaming API Developer Guide
• Site externe : CometD
• Site externe : Apache Avro