Aprender las características de Captura de datos de cambio
Objetivos de aprendizaje
Después de completar esta unidad, podrá:
- Determinar qué objetos están disponibles para Captura de datos de cambio.
- Enumerar los campos que se devuelven en el encabezado del evento de cambio y describir qué campos se incluyen en el cuerpo de cada operación.
- Crear un nombre de canal de evento de cambio.
- Enumerar los permisos necesarios para suscribirse a eventos de cambio.
Compatibilidad con objetos
Captura de datos de cambio puede generar eventos de cambio para todos los objetos personalizados definidos en su organización de Salesforce y un subconjunto de objetos estándar. Admite eventos de cambio para los objetos estándar más populares, incluyendo Account, Contact, Lead, User, Order, OrderItem, Product2 y otros. Para obtener una lista de objetos compatibles con los eventos de cambio, consulte StandardObjectNameChangeEvent en las Referencias de objetos para Salesforce y Lightning Platform.
Para recibir notificaciones sobre cambios en registros, seleccione los objetos personalizados y los objetos estándar compatibles en los que esté interesado en la página Captura de datos de cambio en Configuración. Realizamos los pasos para la selección de objetos más adelante en este módulo.
Un ejemplo de evento de cambio
¿Recuerda a Robert? Su cliente de consultoría definió un objeto personalizado denominado Employee__c que forma parte de una aplicación de RRHH personalizada que gestiona datos de empleados. Para sincronizar los datos de empleados en Salesforce con el sistema de RRHH externo, Robert creó una aplicación que recibe e integra eventos de cambio de registros de empleados nuevos y cambiados.
Observemos un ejemplo de un mensaje de evento que recibe su aplicación. Contiene los datos del registro de un nuevo empleado que un usuario creó en Salesforce. Observe los valores de los campos changeType y 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
}
}
El mensaje de ejemplo del evento de cambio contiene los campos de empleado nombre, apellidos y tenencia, además de campos del sistema como la fecha de creación. Para un nuevo registro, el mensaje de evento excluye los campos que un usuario no estableció. Por ejemplo, si el usuario no rellena el campo de tenencia, se excluiría del mensaje del evento.
El campo ChangeEventHeader incluye campos de encabezado que contienen información sobre el evento. Algunos de los campos de encabezado de nota se enumeran a continuación.
entityName
Este campo contiene el nombre del objeto estándar o personalizado para este cambio de registro. En nuestro ejemplo, es Employee__c.
changeType
Este campo contiene la operación que provocó el cambio. Para eventos de cambio comunes, este campo puede tener uno de los siguientes valores.
CREATEUPDATEDELETEUNDELETE
En nuestro ejemplo, el evento de cambio era para la creación de un registro, de modo que el valor es CREATE.
changedFields
Utilice este campo para determinar qué cambios se cambiaron en una operación de actualización. Este campo está vacío para otras operaciones. Debido a que el ejemplo de evento de cambio es para un nuevo registro, este campo está vacío. Si actualiza uno o más campos, los nombres de campos, junto con LastModifiedDate, están incluidos en changedFields. Para el ejemplo, si se cambia First_Name__c, el valor de campo sería ["LastModifiedDate", "First_Name__c"].
changeOrigin
Utilice este campo para averiguar qué causó el cambio. Si su aplicación de integración cambia un registro en respuesta a un cambio de registro del mismo objeto, puede entrar en un ciclo infinito de cambios. Para evitar eso, utilice este campo para detectar si su aplicación inició el cambio, y, si es así, no procese el campo de nuevo y así evitar potencialmente un ciclo de cambios en profundidad. Este campo contiene la Id. del cliente de la API y de la API de Salesforce que inició el cambio, si lo estableció el cliente. Este campo se rellena para cambios realizados por aplicaciones de API desde Lightning Experience y de lo contrario está vacío.
Por ejemplo, si una aplicación con clientID GetCloudy crea el registro Empleado a través de la API de SOAP, el valor del campo changeOrigin es com/salesforce/api/soap/47.0;client=GetCloudy. En nuestro ejemplo, el valor es com/salesforce/api/soap/47.0;client=SfdcInternalAPI/, lo que significa que el cambio del registro se realizó a través de la interfaz de usuario de Salesforce.
Campos de encabezado relacionados con transacciones
Los siguientes campos de encabezado contienen información sobre la transacción del cambio actual.
transactionKeysequenceNumber
Utilice los campos de transacción para mantener una réplica precisa de los datos de su organización en otro sistema. El campo transactionKey identifica de manera exclusiva la transacción de la que forma parte el cambio. El campo sequenceNumber identifica la secuencia del cambio dentro de una transacción. El número de secuencia resulta útil para operaciones que incluyen pasos múltiples, como una conversión de prospecto o la creación de registros relacionados tras una inserción de desencadenador de Apex. Si no están activados todos los objetos involucrados en una transacción para Captura de datos de cambio, habrá una brecha en los números de secuencia. Recomendamos que replique todos los cambios en una transacción como un único envío en su sistema.
Si selecciona no utilizar el proceso de replicación basado en transacciones, sus datos replicados podrían no estar completos si finaliza su suscripción. Por ejemplo, si su suscripción finaliza en mitad de una transmisión de eventos para una transacción, solo parte de los cambios de la transacción se replican en su sistema.
Campo identificador de reproducción de eventos
La última parte del mensaje del evento con tiene un campo denominado replayId. Este campo contiene un identificador para el mensaje del evento que puede utilizar para reproducir los eventos pasados en los últimos 3 días. No trataremos la reproducción de eventos en este módulo. Para obtener más información, consulte la sección Recursos.
Campos incluidos en el cuerpo de un mensaje de evento
Los campos que Salesforce incluye en un mensaje de evento que recibe un cliente de CometD dependen de la operación realizada y el tipo de suscriptor. Por ejemplo, para un registro nuevo, un mensaje de evento recibido en un cliente de CometD incluye todos los campos de registro que no estén vacíos y los campos del sistema. Sin embargo, en un desencadenador de Apex o en un cliente del modelo de publicación y suscripción de la API, el mensaje de evento incluye todos los campos del registro, vacíos o no, y los campos del sistema. Para obtener más información, consulte Campos del cuerpo del evento de cambio en la Guía del desarrollador de captura de datos de cambio.
Orden de los campos en el mensaje de evento
No se garantiza el orden de los campos en el mensaje de evento JSON. El orden sigue el esquema Apache Avro subyacente, un sistema de serialización en el que se basan los eventos de cambio. Cuando un evento se amplía a formato JSON, el orden de los campos podría no coincidir con el esquema dependiente del cliente empleado para recibir el evento.
Eventos de cambio combinados
Por motivos de eficiencia, a veces los eventos de cambio para una transacción se combinan en un evento si el mismo cambio se producto en varios registros del mismo tipo de objeto durante un segundo. Cuando los eventos de cambio se combinan, Salesforce envía un evento de cambio para todos los registros afectados y el campo redordlds contiene los identificadores de todos los registros que tengan el mismo cambio. Para obtener más información, consulte los Eventos de cambio combinados en la Guía del desarrollador de Captura de datos de cambio.
Enriquecimiento de eventos de cambio con campos adicionales
Seleccione campos para enriquecer eventos de cambio entregados a suscriptores de CometD. Los campos seleccionados se incluyen en los mensajes de eventos de cambio incluso cuando no se cambian. Por ejemplo, utilice el enriquecimiento cuando su aplicación necesite un Id. externo para coincidir los registros en un sistema externo. O bien incluya siempre un campo que proporcione información importante sobre el registro cambiado. Para obtener más información, consulte Enriquecimiento de eventos de cambio con campos adicionales en la Guía del desarrollador de Captura de datos de cambio y este proyecto de Trailhead: Cree un canal personalizado y enriquezca eventos de cambio.
Otros tipos de eventos: Eventos de vacío y eventos de desbordamiento
Se generan otros tipos de eventos de cambio para tratar situaciones especiales. Salesforce genera eventos de vacío cuando los eventos de cambio no pueden generarse o para informar a suscriptores sobre errores. Salesforce genera eventos de desbordamiento cuando el volumen de los cambios es grande. Los eventos de vacío y de desbordamiento no contienen datos de registros. Los eventos de vacío incluyen el Id. del registro, lo que le permite recuperar datos de registros. Para obtener más información, consulte Eventos de vacío, Eventos de desbordamiento, y Pasos de replicación de alto nivel en la Guía del desarrollador de Captura de datos de cambio.
Suscripción a un canal de eventos
Ahora que conoce la apariencia de un mensaje de evento de cambio, averigüemos cómo recibir los eventos de cambio. Salesforce ofrece varias maneras de suscribirse a un canal de eventos de cambio. Para aplicaciones externas a Salesforce, puede utilizar la API de transmisión o herramientas y bibliotecas basadas en CometD, una biblioteca de código abierto que simula la tecnología de distribución. La API de transmisión proporciona un mecanismo de suscripción basado en CometD.
Para procesar cambios de datos de forma asíncrona en Lightning Platform, escriba un desencadenador de Apex para el evento de cambio. Aprenderá más sobre los desencadenadores de Apex para eventos de cambio más adelante en este módulo.
Para recibir notificaciones instantáneas de cambios en los datos de Salesforce en una aplicación que se ejecuta en Lightning Platform, puede utilizar el componente Lightning empApi.
Usted indica en la obtención de qué eventos está interesada su aplicación suscribiéndose a un canal. Su aplicación de transmisión recibe eventos en tiempo real siempre que se produzca un cambio en Salesforce.
Si desea construir su propia aplicación empleando la API de transmisión, consulte la Guía del desarrollador de la API de transmisión. La guía incluye ejemplos de código para suscribirse empleando CometD. Para crear una aplicación de Lightning Platform con empApi, consulte la documentación del Componente web lightning-emp-api o del Componente de Aura lightning:empApi.
Canales de suscripción
Un canal de suscripción es una transmisión de eventos de cambio que corresponden a una o más entidades. Puede suscribirse al canal para recibir notificaciones de eventos de cambio para operaciones de crear, actualizar, eliminar y anular eliminación de registro. Captura de datos de cambio proporciona canales estándar predefinidos y puede crear sus propios canales personalizados.
Canales estándar
El canal estándar ChangeEvents contiene eventos de cambio de una o más entidades seleccionadas en una sola transmisión a la que puede suscribirse. Si espera eventos de cambio de más de una entidad, utilice el canal estándar ChangeEvents. Para recibir eventos de cambio en el canal ChangeEvents, seleccione las entidades para Captura de datos de cambio. Obtiene información acerca de cómo seleccionar una entidad para eventos de cambio en la siguiente unidad.
Si espere eventos de cambio para una sola entidad únicamente, utilice canales de una sola entidad. Con canales de una sola entidad, puede suscribirse a eventos de cambio desde solo un objeto personalizado u objeto estándar.
Esta tabla le muestra cómo especificar el canal de suscripción correspondiente a los registros en los que está interesado en capturar sus cambios.
| Suscribirse a eventos de cambio para: |
Canal |
Ejemplo |
|---|---|---|
| Canal estándar para entidades seleccionadas | ||
| Todos los objetos seleccionados |
/data/ChangeEvents |
N/A |
| Canales de una sola entidad |
||
| Un objeto estándar |
/data/<Nombre_Objeto_Estándar>ChangeEvent |
Para cuentas, el canal es: /data/AccountChangeEvent |
| Un objeto personalizado |
/data/<Nombre_Objeto_Personalizado>__ChangeEvent |
Para registros de Employee__c, el canal es: /data/Employee__ChangeEvent |
Canales personalizados
Cree un canal personalizado si tiene múltiples suscriptores y cada suscriptor recibe eventos de cambio desde un conjunto de entidades diferente. Además, use un canal personalizado con enriquecimiento de eventos para aislar el envío de campos enriquecidos en eventos de cambio en un canal específico. Los canales personalizados agrupan y aíslan eventos de cambio para cada suscriptor de modo que los suscriptores solo reciben los tipos de eventos que necesitan. Las entidades se activan automáticamente para Captura de datos de cambio cuando crea un canal personalizado que las incluye. Un canal personalizado tiene el formato siguiente.
/data/YourChannelName__chn
Por ejemplo, si su nombre de canal es SalesEvents, el canal de suscripción es:
/data/SalesEvents__chn
Para obtener más información, consulte Crear transmisiones de notificaciones de Captura de datos de cambio con canales personalizados en la Guía del desarrollador de Captura de datos de cambio.
Permisos para recibir eventos de cambio
Captura de datos de cambio ignora los parámetros de colaboración y envía eventos de cambio ara todos los registros de un objeto de Salesforce. Para recibir eventos de cambio en un canal, el usuario suscrito debe tener uno o más permisos, dependiendo de las entidades asociadas con los eventos de cambio. Para obtener más información, consulte los Permisos necesarios para eventos de cambio en la Guía del desarrollador de Captura de datos de cambio.
Seguridad a nivel de campo
Captura de datos de cambio respeta la configuración de seguridad a nivel de campo de su organización. Los eventos entregados contienen únicamente los campos a los que tiene permiso para ver el usuario suscrito.
En la siguiente unidad, aprenderá cómo utilizar una herramienta de ejemplo de código abierto, EMP Connector, para suscribirse a un canal y recibir eventos.
