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 que o seu aplicativo recebe pela API Pub/Sub. Ela contém dados de um novo registro de funcionário criado por um usuário no Salesforce. A carga útil do evento de alteração contém campos de cabeçalho em ChangeEventHeader que contêm informações sobre a alteração, campos de registro e campos de sistema. Esta 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 CreatedDate. O campo Tenure (Tempo no cargo) é nulo porque não foi definido. Os eventos de alteração recebidos com a API Pub/Sub contêm todos os campos de registro, inclusive os campos nulos. Em ChangeEventHeader, o campo entityName contém o nome do objeto do Salesforce e o campo changeType indica que esta alteração foi uma criação do registro.

{
  "ChangeEventHeader": {
    "entityName": "Employee__c",
    "recordIds": [
      "a00aj000006yrE7AAI"
    ],
    "changeType": "CREATE",
    "changeOrigin": "com/salesforce/api/soap/60.0;client=SfdcInternalAPI/",
    "transactionKey": "000033a1-751e-415e-47bc-60f581b7e049",
    "sequenceNumber": 1,
    "commitTimestamp": 1712601294000,
    "commitNumber": 1712601294485905400,
    "commitUser": "005aj0000032E1yAAE",
    "nulledFields": [],
    "diffFields": [],
    "changedFields": []
  },
  "OwnerId": "005aj0000032E1yAAE",
  "Name": "e-100",
  "CreatedDate": 1712601294000,
  "CreatedById": "005aj0000032E1yAAE",
  "LastModifiedDate": 1712601294000,
  "LastModifiedById": "005aj0000032E1yAAE",
  "Last_Name__c": "Smith",
  "First_Name__c": "Patricia",
  "Tenure__c": null
}

O campo ChangeEventHeader inclui campos de cabeçalho que contêm informações sobre a alteração. 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 (Criar)
UPDATE (Atualizar)
DELETE (Excluir)
UNDELETE (Desfazer exclusão)

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"].

diffFields

Disponível somente em eventos recebidos na API Pub/Sub e em acionadores do Apex. Contém os nomes dos campos cujos valores são enviados como um diferencial unificado porque contêm valores de texto grandes.

nulledFields

Disponível somente em eventos recebidos na API Pub/Sub e em acionadores do Apex. Contém os nomes dos campos cujos valores foram alterados para nulo em uma operação de atualização. Use esse campo para determinar se um campo foi alterado para nulo em uma atualização e não é um campo inalterado.

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 clientIDGetCloudy cria o registro Employee (Funcionário) por meio de API SOAP, o valor do campo changeOrigin é com/salesforce/api/soap/60.0;client=GetCloudy. Em nosso exemplo, o valor é com/salesforce/api/soap/60.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.

Campos incluídos no corpo de uma mensagem de evento

Os campos que o Salesforce inclui em uma mensagem de evento que um cliente recebe dependem da operação executada e do tipo de assinante. Por exemplo, 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.

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 captura de dados de alteração.

Enriquecer eventos de alteração com campos extras

Selecione campos para enriquecer eventos de alteração entregues a assinantes da API Pub/Sub. 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 de captura de dados de alteração, e este projeto do 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 obter mais informações, consulte Eventos de lacuna, Eventos de estouro e Etapas para replicação de alto nível no Guia do desenvolvedor de captura de dados de alteração.

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. Esse módulo usa a API Pub/Sub e os acionadores do Apex para assinar eventos de alteração. O Salesforce oferece várias formas de assinar um canal de evento de alteração.

Para aplicativos externos ao Salesforce, você pode usar a API Pub/Sub, uma API eficiente baseada em gRPC e HTTP/2, que publica e entrega mensagens de eventos binários.

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 Pub/Sub, confira o Guia do desenvolvedor da API Pub/Sub. 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.

Assine eventos de alteração de:	Canal	Exemplo
Canal padrão para entidades selecionadas
Todos os objetos selecionados	`/data/ChangeEvents`	N/D
Canais de entidade única
Um objeto padrão	`/data/<Standard_Object_Name>ChangeEvent`	Para contas, o canal é: `/data/AccountChangeEvent`
Um objeto personalizado	`/data/<Custom_Object_Name>__ChangeEvent`	Para registros Employee__c, o canal é: `/data/Employee__ChangeEvent`

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.

Procurando ajuda?

Descubra mais