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.
  

Observação

Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e copie e cole os valores de português (Brasil). Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

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, você se inscreve em eventos usando acionadores do Apex, processos, fluxos e o componente do Lightning empApi. Em um aplicativo externo, você se inscreve em eventos usando API Pub/Sub.

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. No menu de acesso rápido ( ), clique em Developer Console e depois 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.

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, que representa uma fila, consulte Grupo na Referência de objeto para o Salesforce e a Lightning Platform.

Este exemplo atribui casos a uma fila. As filas não fazem parte de eventos de plataforma e você não precisa usá-las para usar eventos de plataforma. 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 New (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 Save (Salvar).
   

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.

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 acionamento

O tamanho do lote em um acionador de eventos da plataforma é de 2.000 mensagens de eventos, o que é maior do que o tamanho do lote de 200 do acionador de objetos do Salesforce. 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.

Lista relacionada de Inscrições na página de definição de evento

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.

• 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 API Pub/Sub 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

Como administrador do sistema, você pode retomar uma assinatura suspensa de onde parou, começando da 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 Suspend (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 Resume from Tip (Retomar da dica).
  
  

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

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 iniciar um fluxo quando uma mensagem de evento de plataforma é recebida, crie um fluxo acionado por eventos de plataforma. A partir do elemento Iniciar, escolha um evento de plataforma cujas mensagens de evento acionem o fluxo a ser executado.

Ao criar o fluxo, você pode usar os valores de campo da mensagem de evento de plataforma referenciando a variável global $Record.

Como alternativa, você pode se inscrever em um evento de plataforma nos fluxos usando um elemento Pausar. Em vez de iniciar um fluxo quando uma mensagem de evento de plataforma é recebida, essa mensagem de evento faz com que uma entrevista de fluxo pausado seja retomada. Por exemplo, existe um elemento Pausar que aguarda até que o Salesforce receba uma mensagem de evento de Cloud News. O fluxo só é retomado se o local do evento corresponder a {!contact.MailingCity}. A variável de registro {!contact} armazena valores de um registro de contato.

Inscrever-se em notificações de eventos de plataforma com a API Pub/Sub

A API Pub/Sub fornece uma interface única para publicação e inscrição em eventos de plataforma. Baseada na API gRPC e em HTTP/2, a API Pub/Sub publica e entrega com eficácia mensagens de evento binárias no formato Apache Avro. A gRPC é uma estrutura RPC (Remote Procedure Call) de código aberto que permite a conexão de dispositivos, aplicativos móveis e navegadores a serviços back-end. Para obter mais informações, consulte a Documentação sobre gRPC. O Apache Avro é um sistema de serialização de dados. Para obter mais informações, consulte Apache Avro.

A API Pub/Sub usa um modelo de assinatura por demanda no qual o cliente requisita uma quantidade de eventos do servidor baseado em sua capacidade de processamento. Diferente das assinaturas baseadas em notificações, nas quais o cliente espera para receber novos eventos enviados pelo servidor, com uma assinatura por demanda o cliente requisita eventos proativamente do servidor. Este controle de fluxo de eventos garante que o cliente não fique sobrecarregado com mais eventos do que ele pode tratar se houver um pico na publicação de eventos.

Alguns dos benefícios que a API Pub/Sub fornece incluem:

• Publicação, assinatura e recuperação de esquema de evento em apenas uma API.
  
• Publicação final de resultados de operações de publicação, em vez de resultados intermediários de enfileiramento.
  
• Controle de fluxo que permite especificar quantos eventos receber em uma chamada de assinatura baseada em velocidade de processamento de eventos no cliente.
  
• Transmissão de dados em tempo real de alto desempenho que usa compressão através de HTTP/2.
  
• Compatibilidade com 11 linguagens de programação no cliente, oferecidas pela API gRPC, como Python, Java, Node e C++. Para conhecer todas as linguagens compatíveis, consulte https://grpc.io/docs/languages/.
  

Um cliente da API Pub/Sub pode recuperar o esquema, a ID de reprodução e a carga útil do evento recebido separadamente e decodificar a carga útil. Por exemplo, a carga útil do evento da Cloud News recebido é semelhante a esta mensagem.

{
  "CreatedDate": 1652978695951,
  "CreatedById": "005SM000000146PYAQ",
  "Location__c": "San Francisco",
  "Urgent__c": true,
  "Ink_Percentage__c": "Large highway is closed due to asteroid collision."
}

Para obter mais informações, consulte a Documentação da API Pub/Sub.

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.

Recursos

• Documentação da API Pub/Sub: Início rápido do Java para a API da Pub/Sub
  
• Guia do desenvolvedor de eventos da plataforma: Platform Event Allocations
  
• Guia do desenvolvedor de eventos da plataforma: Tentar usar novamente acionadores de evento com EventBus.RetryableException
  
• Trailhead: Construa um aplicativo de notificação instantânea
  
• Ajuda do Salesforce: Regras de atribuição