Empiece a realizar un seguimiento de su progreso
Inicio de Trailhead
Inicio de Trailhead

Usar la API de transmisión

Objetivos de aprendizaje

Después de completar esta unidad, podrá:
  • Describir la ventaja principal de la tecnología de inserción en comparación con la tecnología de extracción.
  • Crear un envío de tema y recibir notificaciones de eventos.
  • Definir un evento de plataforma y derivar el canal de suscripción.
  • Transmitir un mensaje mediante la transmisión genérica.
  • Especificar las opciones de reproducción para una transmisión duradera.

Eventos de transmisión

Para concluir nuestro análisis de las API de datos de Salesforce, vamos a examinar una API que es de utilidad para un caso de uso totalmente distinto. La API de transmisión le permite insertar un flujo de notificaciones de Salesforce en aplicaciones cliente de acuerdo con los criterios que haya definido. ¿En qué se diferencian las notificaciones de inserción del paradigma de extracción que usan nuestras otras API, según el cual la aplicación cliente solicita (o extrae) datos de Salesforce? Vamos a examinar la cuestión desde el punto de vista del capitán de un navío.

Imagínese que va a poner rumbo a altamar y desea no perder de vista los peligros ocultos, otros barcos y las islas con tesoros abundantes. Ordene a un marinero que se suba a la cofa para vigilar a conciencia. Ahora, debe representar de nuevo el papel del desarrollador. Supongamos que desarrolla una aplicación con la API de REST o la API de SOAP que comprueba periódicamente si se ha actualizado alguna cuenta. Puede usar una solución similar y mantener una vigilancia activa mediante la solicitud constante de datos de las cuentas y la comprobación de las coincidencias con los datos anteriores.

A continuación, imagine que se encuentra en su barco de nuevo, pero esta vez tiene acceso a un flamante radar. Ahora no necesita apostar a un marinero en la cofa, ya que siempre que esté próximo un objeto de interés, el radar le alertará de ello.

La API de transmisión es su radar. Le permite definir eventos y enviar notificaciones a la aplicación cliente siempre que se generen eventos. No es necesario que vigile atentamente los cambios en los datos y además ya no tiene que sondear constantemente Salesforce ni procesar solicitudes de API innecesarias.

La API de transmisión se puede usar como un radar para detectar cambios en los datos y enviar notificaciones.

El seguimiento de los cambios en los datos en Salesforce es especialmente útil si tiene datos de negocio almacenados en un sistema externo distinto de Salesforce. Puede usar la API de transmisión para mantener el origen externo sincronizado con sus datos de Salesforce con eventos de envío de tema y eventos de captura de datos de cambio. Además, la API de transmisión le permite procesar la lógica de negocio de un sistema externo en respuesta a cambios en los datos en Salesforce. Por ejemplo, puede usar la API de transmisión para enviar una notificación a un centro de cumplimiento siempre que se actualice una oportunidad.

Nota

Nota

Para obtener más información sobre Cambiar captura de datos, consulte el módulo de Trailhead Fundamentos de Cambiar captura de datos.

Además de para los cambios en los datos, puede usar la API de transmisión para transmitir notificaciones personalizadas con eventos de plataforma y transmisiones genéricas. Por ejemplo, una aplicación puede generar notificaciones de eventos de plataforma para pedidos que procesa un servicio de realización de pedidos. O bien, una aplicación puede escuchar eventos genéricos y mostrar un mensaje siempre que se vaya a iniciar un periodo de mantenimiento del sistema o cuando haya una nueva oferta disponible para sus usuarios.

Envío de temas

Un envío de tema es un sObject que contiene los criterios de los eventos que desea escuchar, como los cambios en los datos de un objeto determinado. Debe definir los criterios como una consulta SOQL en el envío de tema y especificar las operaciones de registro que notificar (crear, actualizar, eliminar y recuperar). Además de los criterios de eventos, un envío de tema representa el canal al que las aplicaciones cliente están suscritas.

Examinaremos esto más detalladamente cuando creemos nuestro propio envío de tema.

Objetos compatibles con consultas de envío de tema

Las consultas de envío de tema admiten todos los objetos personalizados y algunos de los objetos estándar más utilizados, como Cuenta, Contacto y Oportunidad. Para obtener una lista completa de los objetos estándar admitidos, consulte la Guía del desarrollador de la API de transmisión en la sección Recursos.

Envío de temas y notificaciones

Un envío de tema le permite definir el objeto, los campos y los criterios para los que desea recibir notificaciones de eventos. En el siguiente ejemplo se muestra un envío de tema definido e insertado en Apex. Una vez creado este envío de tema, se puede suscribir al canal de dicho envío de tema para hacer un seguimiento de los cambios en las cuentas cuya ciudad de facturación es San Francisco. Este envío de tema especifica que los campos de Id., nombre y teléfono se devuelven en cada notificación de evento. De forma predeterminada, se envían notificaciones para las operaciones de creación, actualización, eliminación y recuperación que coinciden con los criterios de la consulta.
PushTopic pushTopic = new PushTopic();
pushTopic.Name = 'AccountUpdates';
pushTopic.Query = 'SELECT Id, Name, Phone FROM Account WHERE BillingCity=\'San Francisco\'';
pushTopic.ApiVersion = 37.0;
insert pushTopic;

Como mínimo, debe definir el nombre, la consulta y la versión de la API del envío de tema. Puede usar los valores predeterminados para las demás propiedades. De forma predeterminada, los campos de la lista de campos de la declaración SELECT y la cláusula WHERE desencadenan las notificaciones. Las notificaciones solo se envían para los registros que coinciden con los criterios de la cláusula WHERE. Las notificaciones incluyen los campos de la cláusula SELECT. Para cambiar qué campos desencadenan notificaciones, establezca pushTopic.NotifyForFields en uno de los siguientes valores.

Valor de NotifyForFields
Descripción
Todos
Se generan notificaciones para todos los cambios en campos de registro, siempre que los registros evaluados coincidan con los criterios especificados en la cláusula WHERE.
Referenced (predeterminado)
Se evalúan los cambios en los campos a los que se hace referencia en las cláusulas SELECT y WHERE. Se generan notificaciones para los registros evaluados solo si coinciden con los criterios especificados en la cláusula WHERE.
Seleccione lo siguiente:
Se evalúan los cambios en los campos a los que se hace referencia en la cláusula SELECT. Se generan notificaciones para los registros evaluados solo si coinciden con los criterios especificados en la cláusula WHERE.
Dónde
Se evalúan los cambios en los campos a los que se hace referencia en la cláusula WHERE. Se generan notificaciones para los registros evaluados solo si coinciden con los criterios especificados en la cláusula WHERE.
Para establecer las preferencias de notificación de forma explícita, establezca las siguientes propiedades en true o false. De forma predeterminada, todos los valores se establecen en true.
pushTopic.NotifyForOperationCreate = true;
pushTopic.NotifyForOperationUpdate = true;
pushTopic.NotifyForOperationUndelete = true;
pushTopic.NotifyForOperationDelete = true;

Si crea una cuenta, se genera una notificación de evento. La notificación se genera en formato JSON y contiene los campos que hemos especificado en la consulta de envío de tema: Id, Name y Phone. La notificación de evento debe ser similar a la siguiente.

{
  "clientId": "lxdl9o32njygi1gj47kgfaga4k",
  "data": {
    "event": {
      "createdDate": "2016-09-16T19:45:27.454Z",
      "replayId": 1,
      "type": "created"
    },
    "sobject": {
      "Phone": "(415) 555-1212",
      "Id": "001D000000KneakIAB",
      "Name": "Blackbeard"
    }
  },
  "channel": "/topic/AccountUpdates"
}

El mensaje de notificación incluye el canal para el envío de tema, cuyo formato de nombre es /topic/PushTopicName. Cuando crea un envío de tema, el canal se crea automáticamente.

Consultas de envío de tema

Vamos a dedicar un momento a analizar la consulta que acabamos de definir para nuestro envío de tema. Dado que las consultas de envío de tema son consultas SOQL normales, si está familiarizado con SOQL, no es necesario que aprenda un nuevo formato. El formato de la consulta es:
SELECT <comma-separated list of fields> FROM <Salesforce object> WHERE <filter criteria>

Para garantizar el envío de las notificaciones en el momento oportuno, se deben cumplir los siguientes requisitos para las consultas de envío de tema.

  • La lista de campos de la declaración SELECT debe incluir Id.
  • Solo se permite un único objeto por consulta.
  • El objeto debe ser válido para la versión de la API especificada.
No se admiten determinadas consultas, como las consultas de funciones agregadas o las semicombinaciones.

Notificaciones personalizadas con eventos de plataforma

Utilice los eventos de plataforma para publicar y suscribirse a notificaciones personalizadas con un esquema predefinido. A diferencia de los eventos de Envío de tema y Captura de datos de cambio, los eventos de plataforma no están vinculados a registros de Salesforce y Salesforce no los publica automáticamente. En su lugar, usted define el esquema de un mensaje de evento de plataforma creando un evento de plataforma y agregando campos. Del mismo modo, los clientes publican eventos de plataforma empleando herramientas declarativas en la plataforma Lightning, Apex o las API.

El esquema con versión de un evento de plataforma permite a los suscriptores analizar eventos de manera determinista. Cada versión de esquema se corresponde con un Id. de esquema exclusivo, que se incluye en el mensaje de notificación del evento.

Definición de un evento de plataforma

Para definir un evento de plataforma en la interfaz de usuario, en Configuración, ingrese Eventos de plataforma en el cuadro Búsqueda rápida y, a continuación, seleccione Eventos de plataforma. La incorporación de campos a un evento de plataforma es similar al modo de agregar campos a un objeto personalizado. Se admite un subconjunto de tipos de campos.

El nombre de API de un evento de plataforma contiene el sufijo __e. Por ejemplo, si crea un evento de plataforma con la etiqueta Evento Pedido, el nombre de API es Evento_Pedido__e.

Una vez define un evento de plataforma, se proporciona automáticamente un nombre de canal. El nombre de canal se basa en el nombre de API del evento y el formato es /event/Nombre_Evento. Por ejemplo, /event/Evento_Pedido__e.

Publicación de eventos de plataforma

Puede publicar eventos de plataforma empleando herramientas declarativas o programáticas en la plataforma Lightning.

  • Process Builder empleando la acción Crear un registro
  • Flujo utilizando un elemento Crear registros
  • Método EventBus.publish() de Apex
  • Recurso sobjects de la API de REST
  • Llamada create() de la API de SOAP

Para obtener más detalles, consulte la documentación de Eventos de plataforma en la sección Recursos.

Suscripción a eventos de plataforma

La API de transmisión proporciona el mecanismo de suscripción para múltiples tipos de eventos, incluyendo eventos de plataforma. Además de la API de transmisión, puede suscribirse a eventos de plataforma empleando la plataforma Lightning.

  • Process Builder utilizando un proceso que se inicia cuando se produce un evento de plataforma
  • Flujo que espera que se produzca un evento de plataforma
  • Desencadenador de Apex
  • API de transmisión empleando la biblioteca de mensajería de CometD
  • El componente Lightning empApi

Este ejemplo es un mensaje de evento de plataforma para el evento de pedido.

{
  "data": {
    "schema": "dffQ2QLzDNHqwB8_sHMxdA",
    "payload": {
      "CreatedDate": "2018-08-22T12:11:40.517Z",
      "CreatedById": "005D0000001cSZs",
      "Order_Number__c": "12345",
      "Has_Shipped__c": true
    },
    "event": {
      "replayId": 1
    }
  },
  "channel": "/event/Order_Event__e"
}

Para obtener más detalles, consulte la documentación de Eventos de plataforma en la sección Recursos.

Notificaciones personalizadas con transmisión genérica

Antes de hacerse a la mar por su cuenta, vamos a dedicar unos minutos a revisar la transmisión genérica. La API de transmisión admite el envío de notificaciones con una carga genérica que no están vinculadas con cambios de datos de Salesforce.
Utilice las transmisiones genéricas para enviar y recibir notificaciones personalizadas con cargas de trabajo arbitrarias y sin esquema predefinido. La transmisión genérica le permite publicar notificaciones a un conjunto de usuarios dirigido. Para poder usar la transmisión genérica, necesita lo siguiente:
  • Un canal de transmisión que defina el canal.
  • Uno o varios clientes suscritos al canal.
  • El recurso de inserción de canal de transmisión para monitorear e invocar eventos en el canal.
Puede crear un canal de transmisión para la transmisión genérica mediante la aplicación de canales de transmisión de la interfaz de usuario o mediante la API. Dado que un canal de transmisión se representa mediante el sObject StreamingChannel, puede crearlo con Apex, la API de REST o la API de SOAP. El formato de nombre de canal para la transmisión genérica es /u/ChannelName. Por ejemplo, este miniprograma de Apex crea un canal llamado Broadcast.
StreamingChannel ch = new StreamingChannel();
ch.Name = '/u/Broadcast';
insert ch;

Otra posibilidad es permitir que Salesforce cree el canal de transmisión dinámicamente si no existe. Para activar canales de transmisión dinámicos en su organización, vaya a Configuración, ingrese Interfaz de usuario en el cuadro Búsqueda rápida y, a continuación, seleccione Interfaz de usuario. En la página Interfaz de usuario, seleccione la opción Activar creación de canales de transmisión dinámicos.

Se puede suscribir al canal mediante un cliente CometD. (En la sección Recursos se incluye un vínculo a una presentación de ejemplo de la guía del desarrollador de la API de transmisión).

Para generar eventos, envíe una solicitud POST al siguiente recurso de REST. Sustituya XX.0 por la versión de la API y sustituya Streaming Channel ID por el Id. de su canal.

/services/data/vXX.0/sobjects/StreamingChannel/Streaming Channel ID/push
Nota

Nota

Para obtener el Id. de su canal, ejecute una consulta SOQL en StreamingChannel, como por ejemplo: SELECT Id, Name FROM StreamingChannel

Cuerpo de la solicitud REST de ejemplo.

{
  "pushEvents": [
      {
          "payload": "Broadcast message to all subscribers",
          "userIds": []
      }
   ]
}
Nota

Nota

En lugar de transmitir para todos los suscriptores, puede especificar una lista de usuarios suscritos a los que enviar notificaciones mediante el uso del campo userIds opcional. Además, puede usar el método GET del recurso de inserción de canal de transmisión de la API de REST para obtener una lista de suscriptores activos del canal.

La notificación de evento que recibe el cliente suscrito es similar a la siguiente.

{
  "clientId": "1p145y6g3x3nmnlodd7v9nhi4k",
  "data": {
    "payload": "Broadcast message to all subscribers",
    "event": {
      "createdDate": "2016-09-16T20:43:39.392Z",
      "replayId": 1
    }
  },
  "channel": "/u/Broadcast"
}

Observe que esta notificación de evento contiene el campo replayId

Gracias a las notificaciones de eventos, puede poner rumbo a altamar con toda confianza en busca de islas con tesoros abundantes.

Recuperar notificaciones anteriores mediante una transmisión duradera

Hasta el momento aprendió sobre los diversos tipos de eventos. ¿Qué ocurre si se crea un registro de Salesforce o se genera una notificación personalizada antes de que un cliente se suscriba a un evento de canal o mientras un cliente está desconectado? Antes de la versión 37.0 de la API, el cliente no recibe la notificación correspondiente. Desde la versión 37.0 de la API, Salesforce almacena eventos de Envío de tema, eventos genéricos y eventos de plataforma de volumen estándar durante 24 horas y eventos de alto volumen durante 72 horas. Puede recuperar los mensajes de eventos en cualquier momento durante ese plazo de tiempo. ¡Sí!

A partir de la versión 37.0 de la API, cada mensaje de notificación de evento contiene un campo llamado replayId. De forma similar a la reproducción de un video, la API de transmisión reproduce las notificaciones de eventos enviadas mediante el campo replayId.

A cada mensaje de evento se le asigna un Id. opaco en el campo ReplayId. El valor de campo ReplayId, que se completa por el sistema cuando se entrega el evento a suscriptores, hace referencia a la posición del evento en la transmisión de eventos. No se garantiza que los valores de Id. de reproducción sean contiguos para los eventos consecutivos. Por ejemplo, el evento que sigue al evento con el Id. 999 puede tener asignado el Id. 1.025. Un suscriptor puede almacenar un valor de Id. de reproducción y usarlo en la renovación de la suscripción para recuperar eventos incluidos en el periodo de retención. Por ejemplo, un suscriptor puede recuperar eventos perdidos después de un error de conexión. Los suscriptores no deben computar los Id. de reproducción nuevos a partir de un Id. de reproducción almacenado para hacer referencia a otros eventos de la transmisión.

Tabla 1. Opción de reproducción
Opción de reproducción
Descripción
Uso
Id. de reproducción
El suscriptor recibe todos los eventos después del evento especificado por su valor replayId y nuevos eventos.
Póngase al día de eventos que se perdió después de un mensaje de evento específico, como por ejemplo, después de un fallo de conexión. Para suscribirse con un Id. de repetición específico, guarde el Id. de la repetición del mensaje del evento después del cual desea recuperar eventos almacenados. A continuación, utilice este Id. de repetición cuando vuelva a suscribirse.
-1
El suscriptor recibe los nuevos eventos que se difunden después de que el cliente se suscriba.
Recomendamos que los clientes se suscriban con la opción -1 para recibir nuevos mensajes de eventos. Si los clientes necesitan obtener mensajes de eventos anteriores, pueden utilizar cualquier otra opción de repetición.
-2
El suscriptor recibe todos los eventos, incluyendo los eventos pasados que se encuentren dentro del periodo de retención y los eventos nuevos.
Póngase al día de eventos que se perdió y recupere todos los eventos almacenados, como por ejemplo, después de un fallo de conexión. Utilice esta opción con prudencia. La suscripción con la opción -2 cuando hay almacenados un gran número de mensajes de eventos puede mermar el desempeño.

En este diagrama se muestra cómo los consumidores de eventos pueden leer una transmisión de eventos mediante varias opciones de reproducción.

Transmisión de eventos con opciones de reproducción