Usar a API de transmissão

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:
  • Descrever qual a vantagem principal da tecnologia push em relação à tecnologia pull.
  • Criar um PushTopic e receber notificações de evento.
  • Definir um evento de plataforma e derivar o canal de assinatura.
  • Transmitir uma mensagem com a transmissão genérica.
  • Especificar opções de reprodução para uma transmissão durável.

Como transmitir eventos

Para concluir nossa pesquisa sobre APIs de dados do Salesforce, vamos falar sobre uma API que serve a um caso de uso completamente diferente. A API de transmissão permite a transmissão por push de notificações do Salesforce para aplicativos cliente com base em critérios que você define. De que modo é que a transmissão por push de notificações é diferente do paradigma pull que as nossas outras APIs usam, em que o aplicativo cliente solicita, ou extrai (pull), dados do Salesforce? Vamos analisar o problema desde um ponto de vista do capitão de uma embarcação.

Imagine que você está navegando em alto mar e quer ficar de olho em possíveis perigos, outras embarcações e ilhas do tesouro. Você coloca um marinheiro no cesto do mastro para vigiar. Agora, vista de novo a pele de desenvolvedor. Digamos que você está escrevendo um aplicativo usando a API REST ou a API SOAP que periodicamente verifica se alguma conta foi atualizada. Você pode usar uma solução semelhante e se manter vigilante solicitando constantemente dados da conta e verificando se correspondem aos dados antigos.

Agora, imagine que você está em sua embarcação novamente, mas desta vez tem acesso a um monitor de radar novinho em folha. Você não precisa manter um marinheiro no cesto do mastro, pois sempre que um objeto de interesse se aproxima, o monitor emite um bipe.

A API de transmissão é seu radar. Ela permite definir notificações de evento e por push para seu aplicativo cliente quando os eventos ocorrem. Você não precisa vigiar as alterações de dados; você não precisa sondar constantemente o Salesforce e fazer solicitações de API desnecessárias.

A API de transmissão pode ser usada como um radar para detectar alterações de dados e enviar notificações

Rastrear alterações de dados no Salesforce é especialmente útil quando você tem dados comerciais armazenados em um sistema externo ao Salesforce. Você pode usar a API de transmissão para manter sua fonte externa sincronizada com seus dados do Salesforce usando eventos PushTopic e eventos Alterar captura de dados. Do mesmo modo, a API de transmissão permite que você processe lógica de negócios em um sistema externo em resposta a alterações de dados no Salesforce. Por exemplo, você pode usar a API de transmissão para notificar um centro de processamento de pedidos sempre que uma oportunidade é atualizada.

Nota

Nota

Para mais informações sobre Alterar captura de dados, consulte o módulo Noções básicas de Alterar captura de dados do Trailhead.

Além de alterações de dados, você pode usar a API de transmissão para transmitir notificações personalizadas com eventos de plataforma e transmissão genérica. Por exemplo, um aplicativo pode gerar notificações de evento de plataforma para pedidos processados por um serviço de processamento de pedidos. Ou um aplicativo poderá ouvir eventos genéricos e exibir uma mensagem sempre que uma janela de manutenção do sistema estiver quase começando ou quando uma nova oferta estiver disponível para seus usuários.

PushTopics

Um PushTopic é um sObject que contém os critérios de eventos que você quer ouvir, tais como alterações de dados para um objeto específico. Você define os critérios como uma consulta SOQL no PushTopic e especifica as operações de registro para notificar (criar, atualizar, excluir e cancelar exclusão). Além de critérios de eventos, um PushTopic representa o canal que os aplicativos cliente assinam.

Vamos nos aprofundar nesse assunto quando criarmos nosso próprio PushTopic.

Objetos suportados nas consultas PushTopic

As consultas PushTopic dão suporte a todos os objetos personalizados e a alguns objetos padrão mais usados, como Conta, Contato e Oportunidade. Para uma lista completa de objetos padrão com suporte, consulte o Guia do desenvolvedor da API de streaming na seção Recursos.

PushTopics e notificações

Um PushTopic permite que você defina o objeto, os campos e os critérios em que você está interessado ao receber notificações de evento. O seguinte exemplo mostra um PushTopic definido e inserido no Apex. Depois que esse PushTopic é criado, você pode assinar o canal do PushTopic para acompanhar as alterações em contas cuja cidade de faturamento é São Francisco. Esse PushTopic especifica que os campos Id, Name e Phone são retornados em cada notificação de evento. Por padrão, notificações são enviadas para criar, atualizar, excluir e desfazer exclusões de operações que correspondem aos critérios da 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;

No mínimo, defina o nome do PushTopic, a consulta e a versão da API. Você pode usar valores padrão para as demais propriedades. Por padrão, os campos na lista de campos da instrução SELECT e a cláusula WHERE são os que acionam as notificações. As notificações são enviadas apenas para registros que correspondem aos critérios na cláusula WHERE. As notificações incluem os campos da cláusula SELECT. Para alterar quais campos acionam notificações, defina pushTopic.NotifyForFields para um desses valores.

Valor NotifyForFields
Descrição
Todos
Notificações são geradas para todas as alterações de campo de registro, desde que os registros avaliados correspondam aos critérios especificados na cláusula WHERE.
Referenced (default)
As alterações em campos referenciados nas cláusulas SELECT e WHERE são avaliadas. Notificações são geradas para os registros avaliados apenas se eles corresponderem aos critérios especificados na cláusula WHERE.
Selecione
As alterações em campos referenciados na cláusula SELECT são avaliadas. Notificações são geradas para os registros avaliados apenas se eles corresponderem aos critérios especificados na cláusula WHERE.
Onde
As alterações em campos referenciados na cláusula WHERE são avaliadas. Notificações são geradas para os registros avaliados apenas se eles corresponderem aos critérios especificados na cláusula WHERE.
Para definir preferências de notificação explicitamente, defina as seguintes propriedades como true ou false. Por padrão, todos os valores são definidos como true.
pushTopic.NotifyForOperationCreate = true;
pushTopic.NotifyForOperationUpdate = true;
pushTopic.NotifyForOperationUndelete = true;
pushTopic.NotifyForOperationDelete = true;

Se você criar uma conta, uma notificação de evento é gerada. A notificação está em formato JSON e contém os campos que especificamos na consulta PushTopic: Id, Name e Phone. A notificação de evento é semelhante ao seguinte:

{
  "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"
}

A mensagem de notificação inclui o canal para PushTopic cujo formato de nome é /topic/PushTopicName. Ao criar um PushTopic, o canal é criado automaticamente.

Consultas PushTopic

Vamos dedicar um tempo para nos aprofundar na consulta que acabamos de definir para nosso PushTopic. As consultas PushTopic são consultas SOQL regulares, ou seja, se você já conhece o SOQL, não precisa aprender um novo formato. O formato da consulta é o seguinte:
SELECT <comma-separated list of fields> FROM <Salesforce object> WHERE <filter criteria>

Para garantir que as notificações sejam enviadas de maneira oportuna, os seguintes requisitos se aplicam às consultas PushTopic.

  • A lista de campos da instrução SELECT deve incluir Id.
  • É permitido apenas um objeto por consulta.
  • O objeto deve ser válido para a versão de API especificada.
Determinadas consultas não são suportadas, tais como consultas agregadas ou semi-junções.

Notificações personalizadas com eventos de plataforma

Use eventos de plataforma para publicar e assinar notificações personalizadas com um esquema predefinido. Diferentemente de eventos PushTopic e Alterar captura de dados, os eventos de plataforma não estão vinculados aos registros do Salesforce e não são publicados automaticamente por ele. Ao invés, você define o esquema de uma mensagem de evento de plataforma criando um evento de plataforma e adicionando campos. Além disso, os clientes publicam eventos de plataforma usando ferramentas declarativas na plataforma do Lightning, Apex ou APIs.

O esquema com controle de versões de um evento de plataforma permite que os assinantes analisem eventos de forma determinística. Cada versão do esquema corresponde a uma ID de esquema exclusivo, que é incluída na mensagem de notificação do evento.

Como definir um evento de plataforma

Para definir um evento de plataforma na interface de usuário, em Configuração, digite Eventos de plataforma na caixa Busca rápida e selecione Eventos de plataforma. A adição de campos a um evento de plataforma é semelhante à adição de campos no caso de um objeto personalizado. Há suporte para um subconjunto de tipos de campo.

O nome da API de um evento de plataforma contém o sufixo __e. Por exemplo, se você criar um evento de plataforma com o rótulo Order Event, o nome da API será Order_Event__e.

Depois que um evento de plataforma é definido, um nome de canal é fornecido automaticamente. O nome de canal se baseia no nome da API do evento e o formato é /event/Event_Name. Por exemplo, /event/Order_Event__e.

Publicação de eventos de plataforma

É possível publicar eventos de plataforma usando estas ferramentas declarativas ou programáticas na plataforma do Lightning.

  • Process Builder, usando a ação Criar um registro
  • Flow, usando um elemento Criar registros
  • Método EventBus.publish() do Apex
  • Recurso sobjects da API REST
  • Chamada create() da API SOAP

Para obter mais detalhes, consulte a documentação Eventos de plataforma na seção Recursos.

Assinatura de eventos de plataforma

A API de transmissão oferece o mecanismo de assinatura para vários tipos de eventos, inclusive eventos de plataforma. Além da API de transmissão, é possível assinar eventos de plataforma usando a plataforma do Lightning.

  • Process Builder, usando um processo que se inicia quando ocorre um evento de plataforma
  • Flow, aguardando a ocorrência de um evento de plataforma
  • Acionador do Apex
  • API de transmissão usando a biblioteca de mensagens CometD
  • O componente do Lightning empApi

Este exemplo é uma mensagem de evento de plataforma para o 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 obter mais detalhes, consulte a documentação Eventos de plataforma na seção Recursos.

Notificações personalizadas com transmissão genérica

Antes de zarpar por conta própria, vamos dedicar alguns minutos para revisar a transmissão genérica. A API de transmissão suporta o envio de notificações com uma carga genérica que não está associada às alterações de dados do Salesforce.
Use a transmissão genérica para enviar e receber notificações personalizadas com cargas arbitrárias e sem esquema predefinido. A transmissão genérica permite publicar notificações para um conjunto de usuários específico. Para usar transmissão genérica, é necessário:
  • Um canal de transmissão que defina o canal
  • Um ou mais clientes inscritos no canal
  • O recurso Push do canal de transmissão para monitorar e invocar eventos no canal
Você pode criar um canal de transmissão para transmissão genérica por meio do aplicativo Canais de transmissão na interface de usuário ou por meio da API. Um canal de transmissão é representado pelo sObject StreamingChannel, então você pode criá-lo por meio de Apex, API REST ou API SOAP. O formato do nome do canal para transmissão genérica é /u/ChannelName. Por exemplo, esse trecho do Apex cria um canal chamado Broadcast.
StreamingChannel ch = new StreamingChannel();
ch.Name = '/u/Broadcast';
insert ch;

Como alternativa, você pode optar para que seja o Salesforce a criar o canal de transmissão dinamicamente para você se ele não existir. Para ativar os canais de transmissão dinâmicos em sua organização, em Configuração, insira Interface de usuário na caixa Busca rápida e selecione Interface de usuário. Na página Interface de usuário, selecione a opção Ativar a criação de canal de transmissão dinâmico.

Você pode assinar o canal usando um cliente CometD. (A seção Recursos conecta-se a um guia passo a passo de exemplo no Guia do desenvolvedor da API de transmissão.)

Para gerar eventos, faça uma solicitação de POST para o recurso REST a seguir. Substitua XX.0 pela versão da API e ID do canal de transmissão pela ID do seu canal.

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

Nota

Para obter a ID do seu canal, execute uma consulta SOQL em StreamingChannel, como: SELECT Id, Name FROM StreamingChannel

Exemplo de corpo da solicitação REST.

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

Nota

Em vez de transmitir para todos os assinantes, especifique uma lista de usuários inscritos para enviar notificações usando o campo userIds opcional. Do mesmo modo, você pode usar o método GET do recurso Push do canal de transmissão da API REST para obter uma lista dos assinantes ativos do canal.

A notificação de evento que o cliente assinante recebe tem mais ou menos a seguinte aparência.

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

Observe que essa notificação de evento contém o campo replayId

Graças às notificações de evento, você pode navegar em alto mar confiante e seguir para a ilha do tesouro!

Recuperar notificações passadas usando transmissão durável

Até agora, você conheceu vários tipos de eventos. O que acontece se um registro do Salesforce é criado ou uma notificação personalizada é gerada antes de um cliente assinar um canal de eventos ou enquanto ele está desconectado? Antes da versão 37.0 da API, o cliente perde a notificação correspondente. A partir da versão 37.0 da API, o Salesforce armazena eventos PushTopic, eventos genéricos e eventos de plataforma de volume padrão por 24 horas, e eventos de grande volume por 72 horas. Você pode recuperar as mensagens de evento em qualquer momento durante essa janela de tempo. Eba!

Começando pela versão 37.0 da API, cada mensagem de notificação de evento contém um campo chamado replayId. Semelhante à reprodução de um vídeo, a API de transmissão reproduz as notificações de evento que foram enviadas usando o campo replayId.

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. Por exemplo, o evento a seguir ao evento com a ID 999 pode ter uma ID de 1,025. 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.

Tabela 1 Opções de reprodução
Opção de reprodução
Descrição
Uso
ID de reprodução
O assinante recebe todos os eventos armazenados depois do evento definido pelo respectivo valor de replayId e novos eventos.
Fique por dentro dos eventos perdidos depois de uma certa mensagem de evento, por exemplo, após uma falha de conexão. Para assinar com uma ID de reprodução específica, salve a ID de reprodução da mensagem de evento depois da qual você quer recuperar eventos armazenados. Use então esta ID de reprodução quando fizer novamente a assinatura.
-1
O assinante recebe novos eventos transmitidos depois que a assinatura é feita.
Recomendamos que os clientes assinem com a opção -1 para receber novas mensagens de evento. Se os clientes precisam receber mensagens de evento com mais antecedência, podem usar qualquer outra opção de reprodução.
-2
O assinante recebe todos os eventos, inclusive os anteriores que estejam dentro da janela de retenção, e novos eventos.
Fique por dentro dos eventos perdidos e recupere todos os eventos armazenados, por exemplo, após uma falha de conexão. Use esta opção com moderação. Assinar com a opção -2 quando uma grande quantidade de mensagens de evento está armazenada pode desacelerar o desempenho.

Este diagrama mostra como consumidores de eventos conseguem ler uma transmissão de eventos usando várias opções de reprodução.

Como transmitir eventos com opções de reprodução
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