Inscrever-se em eventos de plataforma

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:
  • Descrever como se inscrever para receber mensagens de eventos de plataforma.
  • Inscreva-se em um evento na plataforma e em aplicativos externos.
  • Testar eventos de plataforma em um método de teste do Apex.
  • Inscrever-se em eventos de plataforma por meio do CometD.

Inscrever-se em eventos de plataforma

Agora que você já viu como publicar eventos de plataforma, como fazer para se inscrever neles para ser notificado das últimas notícias ou do envio de um pacote? Na Salesforce Platform, acionadores do Apex, processos e fluxos. Os aplicativos de componente do Lightning empApi e Visualforce recebem notificações de evento por meio de CometD. Em um aplicativo externo, você se inscreve em eventos usando CometD também.

Inscrever-se em notificações de evento de plataforma com acionadores do Apex

Você provavelmente já usou acionadores do Apex antes para executar ações baseadas em eventos de banco de dados. Com eventos de plataforma, o processo é similar. Você simplesmente escreve um acionador after insert do Apex no objeto de evento para se inscrever em eventos de entrada. Os acionadores fornecem um mecanismo de inscrição automática no Apex. Não é necessário explicitamente criar e ouvir um canal. Os acionadores recebem notificações de evento de várias fontes – sejam elas publicadas por meio do Apex ou de APIs.

Eventos de plataforma só são compatíveis com acionadores after insert. O evento do acionador after insert corresponde ao tempo depois que um evento de plataforma é publicado. Após uma mensagem de evento ser publicada, o acionador after insert é ativado.

Para criar um acionador de evento de plataforma, use o Console do desenvolvedor.

  1. Clique no ícone de configuração, selecione Developer Console e clique em File (Arquivo) | New (Novo) | Apex Trigger (Acionador do Apex).
  2. Forneça um nome e escolha seu evento para o sObject e clique em Submit (Enviar).

O Console do desenvolvedor adiciona automaticamente o evento after insert no modelo do acionador. Além disso, você pode convenientemente criar um acionador na página de definição do evento em Setup (Configuração), na lista relacionada Triggers (Acionadores), mas você precisa especificar a palavra-chave after insert.

O exemplo a seguir mostra um acionador para o evento Cloud News. Ele itera cada evento e verifica se a notícia é urgente por meio do campo Urgent__c. Se a notícia for urgente, o acionador cria um caso para enviar um repórter e adiciona o local do evento ao assunto do caso.

Nota

Nota

Antes de executar esse exemplo, crie uma fila com um rótulo de Envio regional. Para saber como configurar uma fila, consulte Configurar filas na Ajuda do Salesforce. Para saber mais sobre o objeto Grupo, consulte Grupo na Referência de objeto para o Salesforce e a Lightning Platform. Cada OwnerId do caso é atribuído a um ID de fila. O objeto de Grupo representa uma fila. Atribuir casos a uma fila permite distribuir casos a uma equipe de agentes de suporte que são membros da fila.

// Trigger for listening to Cloud_News events.
trigger CloudNewsTrigger on Cloud_News__e (after insert) {
    // List to hold all cases to be created.
    List<Case> cases = new List<Case>();
    // Get queue Id for case owner
    Group queue = [SELECT Id FROM Group WHERE Name='Regional Dispatch' AND Type='Queue'];
    // Iterate through each notification.
    for (Cloud_News__e event : Trigger.New) {
        if (event.Urgent__c == true) {
            // Create Case to dispatch new team.
            Case cs = new Case();
            cs.Priority = 'High';
            cs.Subject = 'News team dispatch to ' +
                event.Location__c;
            cs.OwnerId = queue.Id;
            cases.add(cs);
        }
   }
    // Insert all cases corresponding to events received.
    insert cases;
}

Configurar registro de depuração

Diferentemente do que acontece com acionadores em objetos padrão ou personalizados, os acionadores em eventos de plataforma não são executados na mesma transação do Apex que aquela que publicou o evento. O acionador é executado em seu próprio processo sob a entidade de Processo automatizado, que é um usuário do sistema. Como resultado, os registros de depuração correspondentes à execução do acionador são criados pela entidade de Processo automatizado e não estão disponíveis no Console do desenvolvedor. Para coletar registros de acionador de evento de plataforma, adicione uma entrada de sinalizador de rastreio para a entidade de Processo automatizado em Setup (Configuração).

  1. Em Setup (Configuração), digite Debug Logs (Registros de depuração) na caixa Quick Find (Busca rápida) e depois clique em Debug Logs (Registros de depuração).
  2. Clique em Novo.
  3. Em Traced Entity Type (Tipo de entidade rastreada), selecione Automated Process (Processo automatizado).
  4. Selecione a data de início e a data de expiração para os registros que deseja coletar.
  5. Em Debug Level (Nível de depuração), digite * e clique em Search (Pesquisar).
  6. Selecione um nível de depuração predefinido, como SFDC_DevConsole, ou clique em New (Novo) para criar seu próprio nível de depuração.
  7. Clique em Salvar.
Nota

Nota

Registros de depuração para testes do Apex são uma exceção. Eles incluem registros para acionadores de evento no mesmo registro de execução de teste.

Coisas a se observar sobre acionadores de evento de plataforma

Ordem de processamento de eventos
Um acionador processa notificações de evento de plataforma sequencialmente na ordem em que são recebidas. A ordem dos eventos é baseada na ID de reprodução do evento. Um acionador do Apex pode receber um lote de eventos ao mesmo tempo. A ordem dos eventos é preservada em cada lote. Os eventos em um lote podem ter origem em um ou mais editores.

Execução do acionador assíncrona
Um acionador de evento de plataforma é executado em seu próprio processo de maneira assíncrona e não faz parte da transação que publicou o evento. Em decorrência disso, pode haver um atraso entre o momento em que um evento é publicado e o momento em que o acionador processa o evento. Não espere que o resultado da execução do acionador esteja disponível imediatamente após a publicação do evento.

Usuário do sistema de Processo automatizado
Como os acionadores de evento de plataforma não são executados sob o usuário que os executa (o usuário em execução), mas sob o usuário do sistema de Processo automatizado, definimos o campo ID do proprietário explicitamente em nosso exemplo CloudNewsTrigger. Usamos a ID de uma fila de usuário de amostra chamada Regional Dispatch (Envio regional) para o exemplo de acionador. Se você criar um registro do Salesforce com um campo OwnerId no acionador, como um caso ou oportunidade, defina explicitamente a ID do proprietário. Para casos e leads, você pode, em vez disso, usar regras de atribuição para definir o proprietário.

Além disso, campos do sistema referentes a registros criados ou atualizados no acionador de evento, como CreatedById e LastModifiedById, fazem referência à entidade de Processo automatizado. De modo semelhante, a instrução do Apex UserInfo.getUserId() retorna a entidade de Processo automatizado.

Nota

Nota

Você pode substituir o usuário em execução de um acionador de evento de plataforma para que o acionador seja executado sob esse usuário em vez de Processo automatizado. Configure o acionador usando PlatformEventSubscriberConfig na API de metadados ou API de ferramentas. Para saber mais, consulte Configurar usuário e tamanho do lote para seu acionador de eventos da plataforma no Guia do desenvolvedor de eventos da plataforma.
Limites do administrador do Apex
Assim como os acionadores de objeto padrão ou personalizado, os acionadores de evento de plataforma estão sujeitos aos limites do administrador do Apex.

Limitações do acionador do Apex
Os acionadores de evento de plataforma compartilham muitas das mesmas limitações dos acionadores de objeto padrão e personalizado. Por exemplo, você não pode fazer callouts do Apex de maneira síncrona a partir de acionadores.

Tamanho do lote de acionador
O tamanho do lote em um acionador de evento de plataforma é de 2.000 mensagens de evento, o que é maior do que o tamanho do lote do acionador do objeto Salesforce, de 200. O tamanho do lote corresponde ao tamanho da lista Trigger.New. Você pode modificar o tamanho do lote de um acionador de evento de plataforma. Para saber mais, consulte Configurar usuário e tamanho do lote para seu acionador de eventos da plataforma no Guia do desenvolvedor de eventos da plataforma.

Você pode visualizar o estado de todos os acionadores de evento na página Platform Event Definition Detail (Detalhes de definição de evento de plataforma) em Setup (Configuração). Em Subscriptions (Inscrições), cada acionador ativo é listado juntamente com as informações de execução e o estado. As informações incluem a ID de reprodução dos últimos eventos publicados e processados. O estado indica se o acionador está sendo executado ou se está desconectado da inscrição devido a erros irrecuperáveis ou a permissões insuficientes. O estado Error (Erro) é alcançado apenas quando um acionador foi experimentado o número máximo de vezes. O instantâneo abaixo mostra a lista relacionada de Inscrições na página de detalhes do evento Cloud News.

Nota

Nota

  • A lista relacionada de Assinaturas também lista fluxos e processos que estão inscritos no evento.
  • A lista relacionada de Assinaturas não inclui assinantes que usam Cometd ou o componente empApi do Lightning. Você aprenderá sobre os outros tipos de assinantes mais adiante nesta unidade.
  • Para eventos de plataforma de alto volume, o valor do Último ID publicado não está disponível e é sempre mostrado como Não disponível.

Gerenciar assinantes do acionador do Apex de um evento

Retome uma assinatura suspensa de onde parou, começando do mensagem de evento mais antigo que está disponível no barramento de eventos. Se você quiser ignorar mensagens de evento que estão causando erros ou que não são mais necessárias, você pode retomar a assinatura a partir da dica, começando das mensagens de novos eventos.

Para gerenciar uma assinatura de acionador, nas listas relacionadas de Assinaturas, clique em Gerenciar ao lado do acionador do Apex.

Na página de detalhes de assinatura, escolha a ação apropriada.
  • Para suspender uma assinatura em execução, clique em Suspender.

  • Para retomar uma assinatura suspensa, a partir da mensagem de evento mais antiga disponível no barramento de eventos, clique em Retomar.
  • Para retomar uma assinatura suspensa, a partir das mensagens de novos eventos, clique em Retomar da dica.


Não é possível gerenciar assinaturas de fluxos e processos por meio da lista relacionada de Assinaturas.

Nota

Nota

Quando você salva um acionador, a assinatura do acionador é retomada automaticamente. Para saber mais, consulte Exibir e gerenciar assinantes de um evento na página de detalhes do evento de plataforma no Guia do desenvolvedor de eventos de plataforma.

Testar acionadores de evento de plataforma

Certifique-se de que seu acionador de evento de plataforma esteja funcionando corretamente, adicionando um teste do Apex. Antes de empacotar ou implantar qualquer código do Apex (incluindo acionadores) na produção, seu código do Apex precisa ser testado. Para publicar eventos de plataforma em um teste do Apex, inclua as instruções publish nas instruções Test.startTest e Test.stopTest.

// Create test events
Test.startTest();
// Publish events
Test.stopTest();
// Perform validation here

Em um contexto de teste, a chamada de método publish coloca na fila a operação publish. A instrução Test.stopTest() faz com que a publicação do evento seja realizada. Após Test.stopTest(), faça suas validações.

Aqui está um exemplo de uma classe de teste para nosso evento Cloud_News e seu acionador associado. Publicar o evento faz com que o acionador associado seja ativado. Após Test.stopTest(), o teste verifica se a publicação foi bem-sucedida, inspecionando o valor retornado por isSuccess() em Database.SaveResult. Além disso, o teste consulta o caso que o acionador criou. Se o registro do caso for encontrado, o acionador foi executado com sucesso e o teste é aprovado.

@isTest
public class PlatformEventTest {
    @isTest static void test1() {
        // Create test event instance
        Cloud_News__e newsEvent = new Cloud_News__e(
            Location__c='Mountain City',
            Urgent__c=true,
            News_Content__c='Test message.');
        Test.startTest();
        // Call method to publish events
        Database.SaveResult sr = EventBus.publish(newsEvent);
        Test.stopTest();
        // Perform validation here
        // Verify that the publish was successful
        System.assertEquals(true, sr.isSuccess());
        // Check that the case that the trigger created is present.
        List<Case> cases = [SELECT Id FROM Case];
        // Validate that this case was found.
        // There is only one test case in test context.
        System.assertEquals(1, cases.size());
    }
}

Inscrever-se em notificações de evento de plataforma com um componente do Lightning

Os aplicativos Lightning podem usar o componente EmpApi Lightning Web ou Aura para se inscreverem em eventos no aplicativo.

Inscrever-se em um Componente Web do Lightning

Para usar os métodos empApi em seu componente Web do Lightning, importe os métodos do módulo lightning/empApi conforme abaixo.

import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled }
    from 'lightning/empApi';

Em seguida, chame os métodos importados em seu código JavaScript.

Para obter um exemplo de como usar o módulo lightning/empApi e uma referência completa, consulte a documentação lightning-emp-api na Biblioteca de Componentes do Lightning.

Inscrever-se em um Componente Aura

Para usar os métodos empApi em seu componente Aura, adicione o componente lightning:empApi dentro de seu componente personalizado e atribua a ele um atributo aura:id.

<lightning:empApi aura:id="empApi"/>

No controlador do lado do cliente, adicione funções para chamar os métodos dos componentes.

Para obter um exemplo de como usar o componente lightning:empApi e uma referência completa, consulte a documentação lightning:empApi na Biblioteca de Componentes do Lightning.

Inscrever-se em notificações de evento de plataforma usando cliques

Para assinar mensagens de evento sem código, crie um processo que inicia quando uma mensagem de evento de plataforma é recebida.

Este instantâneo mostra que um processo é iniciado quando um evento Cloud News é recebido. Ao iniciar, o processo procura um registro de contato cuja cidade para cidade para correspondência corresponda ao local da notificação do evento.

Tela de critérios de correspondência do Process Builder

Da mesma forma, você pode se inscrever em um evento de plataforma nos fluxos usando um elemento de pausa. Em vez de iniciar um fluxo quando ocorre um evento de plataforma, um fluxo iniciado anteriormente é interrompido até o recebimento de uma mensagem de evento de plataforma, para depois ser retomado. Por exemplo, existe um elemento de pausa que aguarda até que o Salesforce receba uma mensagem de evento Cloud News. O fluxo só é retomado se o local do evento corresponder a {!contact.MailingCity}. {!contact} é uma variável de registro no fluxo que armazena valores de um registro de contato.

Configuração de pausa no Flow Builder

Inscrever-se em notificações de evento de plataforma com o CometD

Aplicativos externos se inscrevem em eventos de plataforma com o CometD e executam long polling. As páginas de componente do Lightning empApi e Visualforce, que são executadas na plataforma, também podem usar CometD e são consideradas clientes CometD. O CometD é um barramento de roteamento de eventos escalável baseado em HTTP que utiliza um padrão de tecnologia de AJAX push conhecido como Comet. Ele implementa o protocolo Bayeux. Long polling, também chamado de programação Comet, permite a emulação de um envio por push de informações de um servidor para um cliente. Similar a um polling normal, o cliente se conecta e solicita informações do servidor. Contudo, em vez de enviar uma resposta vazia se as informações não estiverem disponíveis, o servidor retém a solicitação e aguarda até que as informações estejam disponíveis (que um evento ocorra).

O Salesforce fornece uma biblioteca Java, EMP Connector, que implementa todos os detalhes da conexão com o CometD e audição de um canal. Você pode usar o EMP Connector para se inscrever facilmente em eventos de plataforma. O EMP Connector disfarça a complexidade da inscrição em eventos. Para obter mais informações sobre o EMP Connector, consulte o exemplo do cliente Java no Guia do desenvolvedor da API de streaming.

O processo de inscrição em notificações de evento de plataforma por meio do CometD é similar ao de inscrição em eventos PushTopic ou eventos genéricos. A única diferença é o nome do canal. O nome do canal de eventos da plataforma diferencia maiúsculas de minúsculas e deve estar no formato a seguir.

/event/<EventName>__e

Por exemplo, se você tiver um evento de plataforma chamado Cloud News, forneça esse nome de canal ao se inscrever.

/event/Cloud_News__e

Especifique a versão da API no fim da URL do CometD, como mostrado abaixo.

// Connect to the CometD endpoint
    cometd.configure({
               url: 'https://<Salesforce_URL>/cometd/48.0/',
               requestHeaders: { Authorization: 'OAuth <Session_ID>'}
    });

Mensagem de evento de plataforma em formato JSON

A mensagem de um evento de plataforma entregue se parece com o exemplo abaixo para um evento Cloud News.

{
  "data": {
    "schema": "_2DBiqh-utQNAjUH78FdbQ",
    "payload": {
      "CreatedDate": "2017-04-27T16:50:40Z",
      "CreatedById": "005D0000001cSZs",
      "Location__c": "San Francisco",
      "Urgent__c": true,
      "News_Content__c": "Large highway is closed due to asteroid collision."
    },
    "event": {
      "replayId": 2
    }
  },
  "channel": "/event/Cloud_News__e"
}

O campo de esquema na mensagem de evento contém a ID do esquema de evento de plataforma (neste exemplo, é "schema": "_2DBiqh-utQNAjUH78FdbQ"). O esquema é compatível com versões – quando o esquema muda, a ID do esquema também muda.

Para determinar se o esquema de um evento foi alterado, recupere o esquema por meio da API REST. Use a ID do esquema executando uma solicitação GET para este recurso API REST: /vXX.X/event/eventSchema/Schema_ID. Ou então você pode recuperar o esquema do evento fornecendo o nome do evento a este ponto de extremidade: /vXX.X/sobjects/Platform_Event_Name__e/eventSchema. Para obter mais informações, consulte o Guia do desenvolvedor da API REST.

Nota

Nota

Diferentemente do que acontece com eventos genéricos e PushTopic, os eventos de plataforma não são compatíveis com o uso de inscrições filtradas. Por exemplo, inscrever-se em /event/Cloud_News__e?Location__c='San Francisco' para filtrar por local não é compatível.

Agora que você viu como usar eventos de plataforma na Salesforce Platform e em aplicativos externos, as possibilidades são infinitas! Use eventos de plataforma para diversas aplicações e integrações, como o processamento de transações comerciais ou a participação em um serviço de atendimento ao cliente proativo. Com os eventos de plataforma, você adota um modelo de programação baseado em eventos e aproveita os benefícios da arquitetura de software baseada em eventos.

Continue a aprender de graça!
Inscreva-se em uma conta para continuar.
O que você ganha com isso?
  • Receba recomendações personalizadas para suas metas de carreira
  • Pratique suas habilidades com desafios práticos e testes
  • Monitore e compartilhe seu progresso com os empregadores
  • Conecte-se a orientação e oportunidades de carreira