Definir e publicar eventos de plataforma

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

Definir um evento de plataforma.
Descrever como mensagens de eventos de plataforma podem ser publicadas no Apex.
Usar um método do Apex para publicar um evento.
Publicar um evento usando cliques em um processo ou fluxo.
Publicar um evento usando API REST por meio da inserção de um sObject.

Nota

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.

Definir e publicar eventos de plataforma

Agora que você entende o que são eventos de plataforma e quando eles são usados, vamos pôr a mão na massa e definir um evento de plataforma! Lembra da agência de notícias Cloud News? Vamos criar uma definição de evento de plataforma que retenha os dados de eventos de notícias.

Defina um evento de plataforma chamado Cloud News:

Em Configuração, digite Eventos de plataforma na caixa Busca rápida e, em seguida, selecione Eventos de plataforma.
Na página Eventos de plataforma, clique em Novo evento de plataforma.
Em Rótulo, digite Cloud News.
Em Rótulo plural, digite Cloud News.
Em Descrição, digite Os eventos da Cloud News trazem as notícias até as pontas de seus dedos.
Para Publicar comportamento, mantenha o padrão de Publicar após compromisso.
Clique em Salvar.
Na lista relacionada de Campos e relacionamentos personalizados, clique em Novo.
Selecione Text e clique em Avançar.
Em Rótulo/Nome do campo, digite Local.
Em Comprimento, digite 100. Mantenha os padrões para os outros campos e deixe o campo Descrição vazio. Clique em Salvar.
Siga as etapas 7, 8 e 9 para adicionar os próximos dois campos:

Rótulo/Nome do campo	Tipo de campo
Urgente	Caixa de seleção
News Content	Área de texto (longo)

Para o evento da Cloud News que você acaba de definir, você criou campos de vários tipos, como um campo de texto ou uma caixa de seleção. Todos os tipos de campo compatíveis com eventos de plataforma são:

Caixa de seleção
Data
Data/hora
Número
Texto
Área de texto (longo)

Retenção de eventos e campo do sistema de ID de reprodução

O Salesforce armazena eventos de plataforma de grande volume por 72 horas no barramento de eventos. Os eventos de volume padrão que foram definidos antes da versão Spring '19 são armazenados por 24 horas no barramento de eventos.

Os eventos recentemente definidos são de alto volume por padrão. Os eventos de volume padrão são os predecessores dos eventos de alto volume eventos e você não pode mais definir tais eventos.

Você pode recuperar eventos armazenados do barramento de eventos usando a API Pub/Sub. Você pode recuperar todos os eventos armazenados ou especificar a ID de reprodução de um evento como a linha de base para a porção recuperada de eventos. Com os acionadores do Apex, você pode retomar um acionador suspenso e coletar os primeiros eventos não processados retidos. Você aprenderá mais tarde neste módulo como gerenciar as assinaturas dos acionadores do Apex.

Embora o Salesforce retenha mensagens de evento temporariamente, você não pode consultá-las por meio de SOQL ou SOSL. Da mesma forma, você não pode usar mensagens de evento na interface do usuário em relatórios, modos de exibição de lista e pesquisa.

A cada mensagem de evento é atribuída uma ID opaca contida no campo ReplayId. O valor do campo ReplayId, preenchido pelo sistema quando o evento é entregue aos assinantes, se refere à posição do evento no fluxo de eventos. Não é garantido que os valores de ID de reprodução sejam contíguos para eventos consecutivos. Um assinante pode armazenar um valor de ID de reprodução e usá-lo em uma nova assinatura para recuperar eventos dentro da janela de retenção. Por exemplo, um assinante pode recuperar eventos perdidos após uma falha de conexão. Os assinantes não podem calcular novas IDs de reprodução, com base em uma ID de reprodução armazenada, para referenciar outros eventos no fluxo.

Sufixo de nome da API

Quando você cria um evento de plataforma, o sistema anexa o sufixo __e para criar o nome da API do evento. Por exemplo, para o evento Cloud News, o nome da API é Cloud_News__e. Utilize o nome da API sempre que se referir ao evento programaticamente, por exemplo, no Apex, API REST ou API Pub/Sub.

Transações e eventos de plataforma

Os eventos da plataforma que são definidos com o comportamento de publicação Publish After Commit (Publicar após confirmar) são transacionais e podem ser revertidos, mas aqueles definidos com o comportamento de publicação Publish Immediately (Publicar imediatamente) não são e não podem ser revertidos. Observe as seguintes diferenças de comportamento.

Comportamento Publicar após compromisso

Um evento de plataforma definido com o comportamento Publish After Commit (Publicar após confirmar) só é publicado depois que uma transação é confirmada com sucesso. Defina um evento com esta opção se os assinantes confiarem nos dados que a transação de publicação representa. Por exemplo, um processo publica uma mensagem de evento e cria um registro de tarefa. Um segundo processo que é subscrito ao evento é disparado e espera encontrar o registro de tarefas. Outro motivo para escolher esse comportamento é quando você não quer que a mensagem do evento seja publicada se a transação falhar.

Comportamento Publicar Imediatamente

Um evento de plataforma definido com o comportamento Publish Immediately (Publicar imediatamente) é publicado quando a chamada de publicação é executada. Selecione esta opção para que a mensagem de evento seja publicada, independentemente de a transação ser bem-sucedida. Escolha também essa opção se o editor e os assinantes forem independentes e se os assinantes não confiarem nos dados enviados pela editor. Por exemplo, o comportamento de publicação imediata é adequado para um evento usado para fins de registro. Com essa opção, um assinante pode receber a mensagem do evento antes que os dados sejam confirmados pela transação do editor.

Publicar eventos

Se seu aplicativo estiver na Salesforce Platform, você pode publicar eventos usando um método do Apex ou com a ferramenta declarativa Flow Builder. Se o seu aplicativo for externo, você poderá publicar eventos usando as APIs do Salesforce, incluindo a API Pub/Sub e as APIs de dados, como a API REST.

Publicar mensagens de evento usando Apex

Para publicar mensagens de evento, crie uma instância do evento e a transfira para o método EventBus.publish().

O exemplo a seguir cria um evento do tipo Cloud_News__e, o publica e depois verifica se a publicação foi bem-sucedida ou se houve erros. O método EventBus.publish() retorna um objeto Database.SaveResult, que contém o resultado da publicação. Se isSuccess () retornar true, a solicitação de publicação será enfileirada no Salesforce e a mensagem do evento será publicada de forma assíncrona. Se IsSuccess () retornar false, a operação de publicação de evento resultou em erros, que são retornados no objeto Database.Error. Este método não gera exceções causadas por uma falha em uma operação de publicação.

Você pode executar o snippet de código do Apex no Developer Console.

No menu de acesso rápido (), selecione Developer Console.
Clique em Debug (Depurar) | Open Execute Anonymous Window (Abrir janela Executar anônimo).

Na nova janela, substitua qualquer conteúdo pelo snippet de código e clique em Executar.

// Create an instance of the event and store it in the newsEvent variable
Cloud_News__e newsEvent = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=true,
           News_Content__c='Lake Road is closed due to mudslides.');
// Call method to publish events
Database.SaveResult sr = EventBus.publish(newsEvent);
// Inspect publishing result
if (sr.isSuccess()) {
    System.debug('Successfully published event.');
} else {
    for(Database.Error err : sr.getErrors()) {
        System.debug('Error returned: ' +
                     err.getStatusCode() +
                     ' - ' +
                     err.getMessage());
    }
}

Para publicar mais de um evento na mesma chamada, adicione seus eventos a uma lista de eventos e passe a lista para o método EventBus.publish(). O resultado desse método é uma matriz de objetos Database.SaveResult: uma para cada evento publicado. O EventBus.publish() pode publicar alguns eventos passados, mesmo quando os outros eventos não podem ser publicados devido a erros. O método EventBus.publish() não gera exceções causadas por uma falha em uma operação de publicação. Ele tem um comportamento similar ao do método Database.insert() do Apex quando chamado com a opção de sucesso parcial.

// List to hold event objects to be published.
List<Cloud_News__e> newsEventList = new List<Cloud_News__e>();
// Create event objects.
Cloud_News__e newsEvent1 = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=true,
           News_Content__c='Lake Road is closed due to mudslides.');
Cloud_News__e newsEvent2 = new Cloud_News__e(
           Location__c='Mountain City',
           Urgent__c=false,
           News_Content__c='Small incident on Goat Lane causing traffic.');
// Add event objects to the list.
newsEventList.add(newsEvent1);
newsEventList.add(newsEvent2);
// Call method to publish events.
List<Database.SaveResult> results = EventBus.publish(newsEventList);
// Inspect publishing result for each event
for (Database.SaveResult sr : results) {
    if (sr.isSuccess()) {
        System.debug('Successfully published event.');
    } else {
        for(Database.Error err : sr.getErrors()) {
            System.debug('Error returned: ' +
                        err.getStatusCode() +
                        ' - ' +
                        err.getMessage());
        }
    }
}

Quando os recursos do sistema se tornam disponíveis, a Salesforce publica os eventos enfileirados na chamada EventBus.publish() de forma assíncrona e armazena-os no barramento de eventos por um período de retenção específico. Na maioria das vezes, você não precisa se preocupar com o resultado final da publicação do evento enfileirado porque a eventual publicação vai ser bem-sucedida. Em casos raros, um erro interno do sistema pode ocorrer e causar falha na publicação assíncrona. Para ter a confirmação do resultado final da publicação do evento, use Retornos de chamada de publicação do Apex. Para obter mais informações, consulte Obter o resultado da publicação assíncrona de eventos da plataforma com Retornos de chamada de publicação do Apex no Guia do desenvolvedor de eventos da plataforma.

A Salesforce Platform fornece alocações sobre quantos eventos você pode definir em sua organização e quantos eventos você pode publicar em uma hora. Para eventos configurados com o comportamento Publicar após confirmar, cada execução de método é contada como uma instrução DML em relação ao limite de instrução DML do Apex. Você pode verificar o uso de limite usando o método Limits.getDMLStatements() do Apex. Para eventos configurados com o comportamento Publicar imediatamente, cada execução de método é contada em relação a um limite de publicação de evento separado de 150 chamadas EventBus.publish(). Você pode verificar o uso de limite usando o método Limits.getPublishImmediateDML() do Apex. Para obter mais informações, consulte a seção Recursos.

Publicar mensagens de evento usando cliques

Para publicar mensagens de evento sem código, use a funcionalidade de criação de registros no Flow Builder. Configure um elemento Criar registros para criar uma instância do evento de plataforma (Cloud_News__e) e, em seguida, defina os valores para o evento. Para definir o valor de um campo booleano, como Urgent__c, use {!$GlobalConstant.True}.

Publicar mensagens de evento usando APIs do Salesforce

Aplicativos externos utilizam uma API para publicar mensagens de eventos de plataforma. Você pode publicar eventos usando a API Pub/Sub ou APIs de dados, como a API SOAP, a API REST ou a API em massa.

Ao usar APIs de dados, você publica eventos da mesma forma que insere sObjects. Assim como com o Apex, a mensagem de evento é publicada de forma assíncrona. Quando você publica um evento e recebe um status de sucesso de true, a solicitação de publicação é enfileirada no Salesforce.

Por exemplo, para o evento Cloud News, você pode publicar notificações de evento inserindo registros Cloud_News__e. O exemplo a seguir cria um evento do tipo Cloud_News__e em API REST.

Ponto de extremidade REST do sObject:

Corpo de solicitação para uma solicitação de POST:

Depois que a mensagem de evento de plataforma é criada, a resposta REST se parece com este resultado.

Você pode usar qualquer ferramenta API REST ou um aplicativo de cliente HTTP para fazer chamadas API REST. Por exemplo, você pode usar o Postman seguindo estas etapas. Se você ainda não usou o Postman, visite o projeto Início rápido: Conectar o Postman ao Salesforce para configurar e obter um fork da coleção de APIs do Salesforce. Saiba mais sobre o Postman na seção Recursos.

Conecte sua organização DE com o Postman.

Faça login em sua organização Trailhead DE.
Abra o aplicativo Postman, selecione um Espaço de trabalho e navegue até seu fork da coleção de APIs do Salesforce.
Na guia Autorização, role até a parte inferior e clique em Obter novo token de acesso.
Clique em Permitir.
Na caixa de diálogo Gerenciar tokens de acesso, copie a URL de instância para sua área de transferência.
Clique em Usar token.
Na guia Variáveis, na linha _endpoint, na coluna VALOR ATUAL, cole a URL de instância que acabou de copiar e, em seguida, clique em Salvar. Talvez seja necessário fechar o painel de documentação para ver o botão Salvar.
Teste o funcionamento de sua conexão.

Em Coleções, selecione seu fork da coleção de APIs do Salesforce.
Selecione REST para expandir as APIs REST.
Selecione Limites GET e, em seguida, clique em Enviar.
Na janela de resposta, o campo Status deve aparecer como Status: 200 OK. Se não aparecer, repita as etapas para obter um novo token.

Faça uma chamada API REST para publicar notificações de eventos.

Em seu fork da coleção de APIs do Salesforce, clique em REST.
Clique em SObject para expandi-lo.
Clique em Criar POST SObject.
Na guia Params (Parâmetros), em Path Variables (Variáveis de caminho), para SOBJECT_API_NAME , insira Cloud_News__e.

Na guia Body (Corpo), cole os seguintes corpo JSON.

{
   "Location__c" : "Mountain City",
   "Urgent__c" : true,
   "News_Content__c" : "Lake Road is closed due to mudslides."
}

Clique em Send (Enviar). A resposta que o Salesforce retorna após publicar o evento tem a seguinte aparência.

{
  "id" : "e00xx0000000001AAA",
  "success" : true,
  "errors" : [
       {
            "statusCode": "OPERATION ENQUEUED",
            "message": "08ffc869-b9f8-4cff-a4ba-8dff9b3dd6cb",
            "fields": []
       }
   ]
}

Agora que você já viu como definir e publicar eventos, vamos ver como se inscrever neles!

Recursos

Procurando ajuda?

Descubra mais