Conhecer as características do Change Data Capture

Objetivos de aprendizagem

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

• Saber quais objetos estão disponíveis para o Change Data Capture.
• Listar os campos que são retornados no cabeçalho de evento de alteração e descrever quais campos são incluídos no corpo para cada operação.
• Criar um nome para o canal de eventos de alteração.
• Listar as permissões necessárias para assinar eventos de alteração.

Suporte a objetos

O Change Data Capture pode gerar eventos de alteração para todos os objetos personalizados definidos em sua organização do Salesforce e um subconjunto de objetos padrão. Ele dá suporte a eventos de alteração para a maioria dos objetos padrão mais populares, incluindo Conta, Contato, Lead, Usuário, Pedido, OrderItem, Product2 e outros. Para obter uma lista de objetos compatíveis com eventos de alteração, consulte StandardObjectNameChangeEvent na Referência de objeto para Salesforce e Lightning Platform.

Para receber notificações sobre alterações de registros, selecione os objetos personalizados e os objetos padrão com suporte desejados na página do Change Data Capture, em Configuração. Veremos as etapas para escolher objetos mais adiante neste módulo.

Um exemplo de evento de alteração

Lembra do Robert? Seu cliente de consultoria definiu um objeto personalizado chamado Employee__c, que é parte de um aplicativo de RH personalizado para gerenciar dados de funcionários. Para sincronizar dados de funcionários no Salesforce com um sistema externo de RH, Robert criou um aplicativo que recebe e integra eventos de alteração de registros de funcionários novos ou alterados. 

Vamos ver um exemplo de uma mensagem de evento recebida pelo aplicativo. Ela contém dados de um novo registro de funcionário criado por um usuário no Salesforce. Observe os valores dos campos changeType e entityName.

{
  "schema": "-pszPCNGMHqUPU1ftkjxEA",
  "payload": {
    "ChangeEventHeader": {
      "commitNumber": 65824495947,
      "commitUser": "005RM000001vI4mYAE",
      "sequenceNumber": 1,
      "entityName": "Employee__c",
      "changeType": "CREATE",
      "changedFields": [],
      "changeOrigin": "com/salesforce/api/soap/47.0;client=SfdcInternalAPI/",
      "transactionKey": "0005163c-8d04-d729-39bd-b917b035a66c",
      "commitTimestamp": 1569436136000,
      "recordIds": [
        "a00RM0000004ICOYA2"
      ]
    },
    "First_Name__c": "Jane",
    "Tenure__c": 2.0,
    "Name": "e-100",
    "Last_Name__c": "Smith",
    "CreatedDate": "2019-09-25T18:28:55.000Z",
    "LastModifiedDate": "2019-09-25T18:28:55.000Z",
    "OwnerId": "005RM000001vI4mYAE",
    "CreatedById": "005RM000001vI4mYAE",
    "LastModifiedById": "005RM000001vI4mYAE",
  },
  "event": {
    "replayId": 1
  }
}

A mensagem de evento de alteração de exemplo contém o nome, o sobrenome e o tempo no cargo do funcionário, além dos campos de sistema, como a data de criação. No caso de um novo registro, a mensagem de evento exclui os campos que o usuário não definiu. Por exemplo, se o usuário não preencheu o campo Tempo no cargo, ele será excluído da mensagem de evento. 

O campo ChangeEventHeader inclui campos de cabeçalho que contêm informações sobre o evento. Alguns campos de cabeçalho relevantes estão listados abaixo.

entityName

Esse campo contém o nome do objeto padrão ou personalizado da alteração de registro. Em nosso exemplo, é Employee__c.

changeType

Esse campo contém a operação que causou a alteração. Em caso de eventos de alteração comuns, esse campo pode ter um dos valores a seguir. 

• CREATE
• UPDATE
• DELETE
• UNDELETE

Em nosso exemplo, o evento de alteração foi de criação de um registro, ou seja, o valor é CREATE.

changedFields

Use esse campo para encontrar os campos que foram alterados em uma operação de atualização. Esse campo fica vazio em outras operações. Como o exemplo de evento de alteração é para um novo registro, o campo está vazio. Se você atualizar um ou mais campos, os nomes do campo, junto com LastModifiedDate, serão incluídos em changedFields. Por exemplo, se First_Name__c for alterado, o valor de campo será ["LastModifiedDate", "First_Name__c"].

changeOrigin

Use este campo para descobrir o que causou a alteração. Se seu aplicativo de integração altera um registro em resposta a uma alteração de registro do mesmo objeto, você pode entrar em um ciclo infinito de alterações. Para evitar isso, use esse campo para detectar se seu aplicativo iniciou a alteração e, caso tenha iniciado, não processe a alteração novamente e evite, assim, um ciclo interminável de alterações. Esse campo contém a API do Salesforce e o ID do cliente da API que iniciou a alteração, caso seja definido pelo cliente. Esse campo é preenchido para alterações feitas por aplicativos de API ou do Lightning Experience e, caso contrário, estará vazio.

Por exemplo, se um aplicativo com clientID GetCloudy cria o registro de funcionário por meio de API SOAP, o valor do campo changeOrigin é com/salesforce/api/soap/47.0;client=GetCloudy. Em nosso exemplo, o valor é com/salesforce/api/soap/47.0;client=SfdcInternalAPI/, o que significa que a alteração do registro foi feita por meio do interface de usuário do Salesforce.

Campos de cabeçalho relativos à transação

Os campos de cabeçalho a seguir contém informações sobre a transação da alteração atual. 

• transactionKey
• sequenceNumber

Use os campos de transação para manter uma réplica exata dos dados de sua organização em outro sistema. O campo transactionKey identifica a transação da qual a alteração faz parte de forma exclusiva. O campo sequenceNumber identifica a sequência da alteração em uma transação. O número sequencial é útil para operações que incluem várias etapas, como conversão de lead ou criação de registros relacionados em um acionador do Apex pós-inserção. Se nem todos os objetos envolvidos em uma transação estiverem habilitados para Captura de dados de alteração, haverá uma lacuna nos números da sequência. Recomendamos que você replique todas as alterações em uma transação como uma única confirmação em seu sistema. 

Caso escolha não usar um processo de replicação baseado em transação, seus dados replicados poderão não estar completos se a assinatura for interrompida. Por exemplo, se sua assinatura for interrompida no meio de um fluxo de eventos de uma transação, somente parte das alterações da transação serão replicadas no sistema.

Campo replayId do evento

A última parte da mensagem de evento contém um campo chamado replayId. Esse campo contém um ID para a mensagem de evento que você pode usar para reproduzir os eventos dos últimos três dias. Não vamos abordar a reprodução dos eventos neste módulo. Para obter mais informações, confira a seção Recursos.

Campos incluídos no corpo de uma mensagem de evento

Os campos que o Salesforce inclui em uma mensagem de evento que um cliente CometD recebe dependem da operação executada e do tipo de assinante. Por exemplo: para um novo registro, uma mensagem de evento recebida em um cliente CometD inclui todos os campos de registro que não estiverem vazios e os campos de sistema. Entretanto, em um acionador do Apex ou em um cliente de API Pub/Sub, a mensagem de evento inclui todos os campos de registro, estejam vazios ou não, e os campos de sistema. Para obter mais informações, consulte Campos no corpo de evento de alteração no Guia do desenvolvedor do Change Data Capture.

Ordem dos campos na mensagem de evento

A ordem dos campos na mensagem de evento JSON não é garantida. A ordem segue um esquema Apache Avro subjacente, um sistema de serialização de dados que serve de base para os eventos de alteração. Quando um evento é expandido em formato JSON, a ordem dos campos pode não corresponder ao esquema, dependendo do cliente usado para receber o evento.

Eventos de alteração mesclados

Por questão de eficiência, às vezes, eventos de alteração de uma transação são mesclados em um só evento se a mesma alteração ocorreu em vários registros do mesmo tipo de objeto durante um segundo. Quando eventos de alteração são mesclados, o Salesforce envia um evento de alteração para todos os registros afetados e o campo recordIds contém as IDs de todos os registros que têm a mesma alteração. Para saber mais, consulte Eventos de alteração mesclados no Guia do desenvolvedor do Change Data Capture.

Enriquecer eventos de alteração com campos extras

Selecione campos para enriquecer eventos de alteração entregues a assinantes CometD. Os campos selecionados são incluídos nas mensagens de evento de alteração mesmo quando inalterados. Por exemplo, use o enriquecimento quando seu aplicativo precisar de um campo de ID externo para correspondência de registros em um sistema externo. Ou inclua sempre um campo que forneça informações importantes sobre o registro alterado. Para obter mais informações, consulte Enriquecer eventos de alteração com campos extras no Guia do desenvolvedor do Change Data Capture, e este projeto Trailhead: Criar um canal personalizado e enriquecer eventos de alteração.

Outros tipos de eventos: Eventos de lacuna e eventos de estouro

Outros tipos de eventos de alteração são gerados para lidar com situações especiais. O Salesforce gera eventos de lacuna quando eventos de alteração não podem ser gerados ou para informar os assinantes sobre erros. O Salesforce gera eventos de estouro quando o volume de alterações é grande. Os eventos de lacuna e de estouro não contêm dados do registro. Os eventos de lacuna incluem o ID do registro, permitindo que você recupere dados do registro. Para saber mais, consulte Eventos de lacuna, Eventos de estouro e Etapas para replicação de alto nível no Guia do desenvolvedordo Change Data Capture.

Como assinar um canal de eventos

Agora que você sabe como é uma mensagem de evento de alteração, vamos ver como se faz para receber os eventos de alteração. O Salesforce oferece várias formas de assinar um canal de evento de alteração. Para aplicativos fora do Salesforce, você pode usar API de streaming ou ferramentas e bibliotecas baseadas em CometD, uma biblioteca de código aberto que simula tecnologia push. A API de streaming fornece um mecanismo de assinatura baseado em CometD. 

Para processar alterações de dados de forma assíncrona no Lightning Platform, grave um Acionador do Apex para o evento de alteração. Você aprenderá mais sobre os Acionadores do Apex para eventos de alteração mais tarde neste módulo.

Para receber notificações instantâneas sobre alterações em dados do Salesforce em um aplicativo que esteja em execução na Lightning Platform, você pode usar o componente do Lightning empApi.

Indique os eventos que seu aplicativo deseja acompanhar fazendo a assinatura de um canal. Seu aplicativo de streaming recebe eventos em tempo real sempre que uma alteração ocorre no Salesforce. 

Se quiser compilar seu próprio aplicativo usando a API de streaming, confira o Guia do desenvolvedor da API de streaming. Esse guia inclui exemplos de código para assinatura usando CometD. Para criar um aplicativo da Lightning Platform usando empApi, confira a documentação do Componente Web lightning-emp-api ou do Componente Aura lightning:empApi.   

Canais de assinatura

Um canal de assinatura é um fluxo de eventos de alteração que correspondem a uma ou mais entidades. Você pode se inscrever no canal para receber notificações de eventos de alterações para operações de criação, atualização, exclusão e cancelamento de exclusão de registros. O Change Data Capture fornece canais padrão predefinidos e você pode criar seus próprios canais personalizados. 

Canais padrão

O canal padrão do ChangeEvents contém eventos de alteração de uma ou mais entidades selecionadas em um único fluxo ao qual você pode se inscrever. Se você espera eventos de alteração de mais de uma entidade, use o canal padrão do ChangeEvents. Para receber eventos de alteração no canal ChangeEvents, selecione as entidades para Change Data Capture. Você aprenderá a selecionar uma entidade para eventos de alteração mais tarde na próxima unidade.

Se você espera eventos de alteração apenas para uma única entidade, use canais de entidade única. Com canais de entidade única, você pode se inscrever em eventos de alteração de apenas um objeto personalizado ou objeto padrão.

Esta tabela mostra como especificar o canal de assinatura correspondente aos registros cujas alterações devem ser recebidas.

Canais personalizados

Crie um canal personalizado se você tiver vários assinantes e cada assinante receber eventos de alteração de um conjunto de entidades diferente. Além disso, use um canal personalizado com enriquecimento de eventos para isolar o envio de campos enriquecidos em eventos de alteração em um canal específico. Os canais personalizados agrupam e isolam eventos de alteração para cada assinante para que eles recebam apenas os tipos de eventos de que precisam. As entidades são habilitadas automaticamente para Change Data Capture quando você cria um canal personalizado que as inclui. Um canal personalizado tem o seguinte formato.

/data/YourChannelName__chn

Por exemplo, se o nome do seu canal for SalesEvents, o canal de assinatura será:

/data/SalesEvents__chn

Para obter mais informações, consulte Compor fluxos de notificações do Change Data Capture com canais personalizados no Guia do desenvolvedor do Change Data Capture.

Permissões para receber eventos de alteração

O Change Data Capture ignora as configurações de compartilhamento e envia eventos de alteração para todos os registros de um objeto Salesforce. Para receber eventos de alteração em um canal, o usuário assinante precisa ter uma ou mais permissões, dependendo das entidades associadas aos eventos de alteração. Para saber mais, consulte Permissões obrigatórias para eventos de alteração no Guia do desenvolvedor do Change Data Capture.

Segurança em nível de campo

O Change Data Capture respeita a configuração de segurança em nível de campo da sua organização. Os eventos enviados contêm apenas os campos que um usuário assinante está autorizado a visualizar. 

Na próxima unidade, você aprenderá a usar uma ferramenta de exemplo de código aberto, o EMP Connector, para assinar um canal e receber eventos.

Recursos

• Change Data Capture Developer Guide
• Biblioteca de Componentes do Lightning: Componente Web lightning-emp-api
• Biblioteca de componentes do Lightning: componente lightning:empApi
  
• Streaming API Developer Guide
• Site externo: CometD
• Site externo: Apache Avro