Esta página foi traduzida pela API Cloud Translation.

Integração com o Salesforce (SFDC)

Esta página descreve as etapas de integração da carga de trabalho operacional do Salesforce (SFDC) no Cortex Framework Data Foundation. O Cortex Framework integra dados do Salesforce com pipelines do Dataflow até o BigQuery, enquanto o Cloud Composer programa e monitora esses pipelines do Dataflow para gerar insights com base nos seus dados.

Arquivo de configuração

O arquivo config.json no repositório de dados da base do Cortex Framework configura as configurações necessárias para transferir dados de qualquer fonte, incluindo o Salesforce. Este arquivo contém os seguintes parâmetros para cargas de trabalho operacionais do Salesforce:

    "SFDC": {
        "deployCDC": true,
        "createMappingViews": true,
        "createPlaceholders": true,
        "datasets": {
            "cdc": "",
            "raw": "",
            "reporting": "REPORTING_SFDC"
        }
    }

A tabela a seguir descreve o valor de cada parâmetro operacional do SFDC:

Parâmetro	Significado	Valor padrão	Descrição
`SFDC.deployCDC`	Implantar a CDC	`true`	Gere scripts de processamento de CDC para serem executados como DAGs no Cloud Composer. Consulte a documentação para conferir as diferentes opções de transferência para o Salesforce Sales Cloud.
`SFDC.createMappingViews`	Criar visualizações de mapeamento	`true`	Os DAGs fornecidos para buscar novos registros das APIs do Salesforce atualizam os registros na página de destino. Esse valor definido como verdadeiro gera visualizações no conjunto de dados processado pelo CDC para expor tabelas com a "versão mais recente da verdade" do conjunto de dados bruto. Se for falso e `SFDC.deployCDC` for `true`, os DAGs serão gerados com o processamento de captura de dados de alteração (CDC) com base no SystemModstamp. Confira detalhes sobre o processamento de CDC para o Salesforce.
`SFDC.createPlaceholders`	Criar marcadores de posição	`true`	Crie tabelas de marcador de posição vazias caso elas não sejam geradas pelo processo de ingestão para permitir que a implantação de relatórios downstream seja executada sem falhas.
`SFDC.datasets.raw`	Conjunto de dados de destino bruto	-	Usado pelo processo de CDC, é aqui que a ferramenta de replicação armazena os dados do Salesforce. Se estiver usando dados de teste, crie um conjunto de dados vazio.
`SFDC.datasets.cdc`	Conjunto de dados processado pela CDC	-	Conjunto de dados que funciona como origem para as visualizações de relatórios e como destino para os DAGs processados de registros. Se estiver usando dados de teste, crie um conjunto de dados vazio.
`SFDC.datasets.reporting`	Conjunto de dados de relatórios do SFDC	`"REPORTING_SFDC"`	Nome do conjunto de dados que pode ser acessado pelos usuários finais para gerar relatórios, em que visualizações e tabelas voltadas ao usuário são implantadas.
`SFDC.currencies`	Como filtrar moedas	`[ "USD" ]`	Se você não estiver usando dados de teste, insira uma única moeda (por exemplo, `[ "USD" ]`) ou várias moedas (por exemplo,`[ "USD", "CAD" ]`) conforme for relevante para sua empresa. Esses valores são usados para substituir marcadores em SQL em modelos de análise, quando disponíveis.

Modelo de dados

Esta seção descreve o modelo de dados do Salesforce (SFDC) usando o diagrama de relacionamento de entidades (ERD, na sigla em inglês).

Figura 2. Salesforce (SFDC): diagrama de relacionamento de entidades.

Visualizações básicas

Esses são os objetos azuis no ERD e são visualizações em tabelas de CDC sem transformações, exceto alguns aliases de nome de coluna. Consulte os scripts em src/SFDC/src/reporting/ddls.

Visualizações de relatórios

Esses são os objetos verdes no DER e contêm os atributos dimensionais relevantes usados pelas tabelas de relatórios. Consulte os scripts em src/SFDC/src/reporting/ddls.

Requisitos de dados do Salesforce

Esta seção descreve as especificidades de como os dados do Salesforce precisam ser estruturados para uso com o Cortex Framework.

Estrutura da tabela:
- Nomeação:os nomes de tabelas usam snake_case (palavras em letras minúsculas separadas por sublinhados) e são plurais. Por exemplo, some_objects.
- Tipos de dados:as colunas mantêm os mesmos tipos de dados que são representados no Salesforce.
- Legibilidade:alguns nomes de campo podem ser ligeiramente ajustados para maior clareza na camada de relatórios.
Implantação e tabelas vazias:todas as tabelas necessárias que estão faltando no conjunto de dados bruto são criadas automaticamente como tabelas vazias durante o processo de implantação. Isso garante a execução suave da etapa de implantação do CDC.
Requisitos da CDC:os campos Id e SystemModstamp são essenciais para que os scripts da CDC rastreiem as mudanças nos dados. Eles podem ter esses nomes exatos ou diferentes. Os scripts de processamento bruto fornecidos buscam esses campos automaticamente nas APIs e atualizam a tabela de replicação de destino.
- Id: atua como um identificador exclusivo para cada registro.
- SystemModstamp: esse campo armazena um carimbo de data/hora que indica a última vez que um registro foi modificado.
Scripts de processamento bruto:os scripts de processamento bruto fornecidos não exigem processamento (CDC) adicional. Esse comportamento é definido durante a implantação por padrão.

Tabelas de origem para conversão de moeda

O Salesforce permite gerenciar moedas de duas maneiras:

Básico:é o padrão, em que todos os dados usam uma única moeda.
Avançado: converte entre várias moedas com base nas taxas de câmbio. É necessário ativar a Gerenciamento avançado de moedas.

Se você usa a gestão avançada de moedas, o Salesforce usa duas tabelas especiais:

CurrencyTypes: essa tabela armazena informações sobre as diferentes moedas usadas (por exemplo, USD, EUR etc.).
DatedConversionRates: essa tabela contém as taxas de câmbio entre moedas ao longo do tempo.

O Cortex Framework espera que essas tabelas estejam presentes se você usar a gestão de moeda avançada. Se você não usa o gerenciamento avançado de moedas, é possível remover entradas relacionadas a essas tabelas de um arquivo de configuração (src/SFDC/config/ingestion_settings.yaml). Essa etapa evita tentativas desnecessárias de extrair dados de tabelas inexistentes.

Como carregar dados do SFDC no BigQuery

O Cortex Framework oferece uma solução de replicação baseada em scripts Python programados no Apache Airflow e na API Bulk do Salesforce 2.0. Esses scripts Python podem ser adaptados e programados na sua ferramenta preferida. Para mais informações, consulte Módulo de extração do SFDC.

O Cortex Framework também oferece três métodos diferentes para integrar seus dados, dependendo de onde eles vêm e como são gerenciados:

Chamadas de API:essa opção é para dados que podem ser acessados diretamente por uma API. O Cortex Framework pode chamar a API, extrair os dados e armazená-los em um conjunto de dados "Raw" no BigQuery. Se houver registros no conjunto de dados, o Cortex Framework poderá atualizá-los com os novos dados.
Visualizações de mapeamento de estrutura:esse método é útil se você já tiver seus dados carregados no BigQuery por outra ferramenta, mas a estrutura de dados não corresponder ao que o Cortex Framework precisa. O Cortex Framework usa "visualizações" (como tabelas virtuais) para traduzir a estrutura de dados existente no formato esperado pelos recursos de relatórios do Cortex Framework.
Scripts de processamento de CDC (captura de dados de alteração):essa opção foi projetada especificamente para dados que mudam constantemente. Os scripts da CDC rastreiam essas mudanças e atualizam os dados no BigQuery. Esses scripts dependem de dois campos especiais nos dados:
- Id: identificador exclusivo para cada registro.
- SystemModstamp: um carimbo de data/hora que indica quando um registro foi alterado.
Se os dados não tiverem esses nomes exatos, os scripts poderão ser ajustados para reconhecê-los com nomes diferentes. Também é possível adicionar campos personalizados ao seu esquema de dados durante esse processo. Por exemplo, a tabela de origem com dados do objeto Account precisa ter os campos originais Id e SystemModstamp. Se esses campos tiverem nomes diferentes, o arquivo src/SFDC/src/table_schema/accounts.csv precisa ser atualizado com o nome do campo Id mapeado para AccountId e qualquer campo de carimbo de data/hora de modificação do sistema mapeado para SystemModstamp. Para mais informações, consulte a documentação do SystemModStamp.

Se você já tiver carregado dados por outra ferramenta (e ela for constantemente atualizada), o Cortex ainda poderá usá-los. Os scripts do CDC vêm com arquivos de mapeamento que podem traduzir sua estrutura de dados atual para o formato necessário do Cortex Framework. Você pode até adicionar campos personalizados aos seus dados durante esse processo.

Configurar a integração da API e o CDC

Para importar dados do Salesforce para o BigQuery, use uma destas opções:

Scripts do Cortex para chamadas de API: fornece scripts de replicação para o Salesforce ou uma ferramenta de replicação de dados de sua escolha.A chave é que os dados que você envia precisam ter a mesma aparência que se tivessem vindo das APIs do Salesforce.
Ferramenta de replicação e anexar sempre : se você estiver usando uma ferramenta para replicação, essa opção é para uma ferramenta que pode adicionar novos registros de dados (_appendalways_pattern) ou atualizar registros existentes.
Ferramenta de replicação e adição de novos registros: se a ferramenta não atualizar os registros e replicar todas as mudanças como novos registros em uma tabela de destino (bruta), a Cortex Data Foundation oferece a opção de criar scripts de processamento de CDC. Para mais informações, consulte o processo do CDC.

Carga de trabalho do Salesforce: opções de integração de dados

Figura 1. Carga de trabalho do Salesforce: opções de integração de dados.

Para garantir que seus dados correspondam ao esperado pelo Cortex Framework, ajuste a configuração de mapeamento para mapear sua ferramenta de replicação ou esquemas existentes. Isso gera visualizações de mapeamento compatíveis com a estrutura esperada pela Cortex Framework Data Foundation.

Use o arquivo ingestion_settings.yaml para configurar a geração de scripts para chamar as APIs do Salesforce e replicar os dados no conjunto de dados brutos (seção salesforce_to_raw_tables) e a geração de scripts para processar as mudanças recebidas no conjunto de dados brutos e no conjunto de dados processado pelo CDC (seção raw_to_cdc_tables).

Por padrão, os scripts fornecidos para leitura de APIs atualizam as alterações no conjunto de dados brutos. Portanto, os scripts de processamento do CDC não são necessários, e as visualizações de mapeamento para alinhar o esquema de origem ao esperado são criadas.

A geração de scripts de processamento do CDC não será executada se SFDC.createMappingViews=true estiver no config.json (comportamento padrão). Se os scripts do CDC forem necessários, defina SFDC.createMappingViews=false. Essa segunda etapa também permite o mapeamento entre os esquemas de origem e os esquemas necessários, conforme exigido pela base de dados do Cortex Framework.

O exemplo a seguir de um arquivo de configuração setting.yaml ilustra a geração de visualizações de mapeamento quando uma ferramenta de replicação atualiza os dados diretamente no conjunto de dados replicado, conforme ilustrado em option 3. Ou seja, não é necessário CDC, apenas o remapeamento de tabelas e nomes de campos. Como nenhum CDC é necessário, essa opção é executada desde que o parâmetro SFDC.createMappingViews no arquivo config.json permaneça como true.

  salesforce_to_raw_tables:
  - base_table: accounts
    raw_table: Accounts
    api_name: Account
      load_frequency: "@daily"
  - base_table: cases
    raw_table: cases2
    api_name: Case
    load_frequency: "@daily"

Nesse exemplo, a remoção da configuração de uma tabela base ou de todas elas das seções pula a geração de DAGs dessa tabela base ou de toda a seção, como ilustrado para salesforce_to_raw_tables. Para esse cenário, definir o parâmetro deployCDC : False tem o mesmo efeito, já que não é necessário gerar scripts de processamento do CDC.

Mapeamento de dados

É necessário mapear os campos de dados recebidos para o formato esperado pela Cortex Data Foundation. Por exemplo, um campo chamado unicornId do sistema de dados de origem precisa ser renomeado e reconhecido como AccountId (com um tipo de dados de string) na Cortex Data Foundation:

Campo de origem: unicornId (nome usado no sistema de origem)
Campo do Cortex: AccountId (nome esperado pelo Cortex)
Tipo de dados: String (tipo de dados esperado pelo Cortex)

Como mapear campos polimórficos

A Cortex Framework Data Foundation oferece suporte ao mapeamento de campos polimórficos, que são campos cujo nome pode variar, mas a estrutura permanece consistente. Os nomes de tipo de campo polimórfico (por exemplo, Who.Type) podem ser replicados adicionando um item [Field Name]_Type nos respectivos arquivos CSV de mapeamento: src/SFDC/src/table_schema/tasks.csv. Por exemplo, se você precisar que o campo Who.Type do objeto Task seja replicado, adicione a linha Who_Type,Who_Type,STRING. Isso define um novo campo chamado Who.Type que é mapeado para si mesmo (mantém o mesmo nome) e tem um tipo de dados de string.

Como modificar modelos de DAG

Talvez seja necessário ajustar os modelos de DAG para CDC ou para processamento de dados brutos, conforme exigido pela sua instância do Airflow ou do Cloud Composer. Para mais informações, consulte Como coletar as configurações do Cloud Composer.

Se você não precisar de CDC ou geração de dados brutos de chamadas de API, defina deployCDC=false. Como alternativa, remova o conteúdo das seções em ingestion_settings.yaml. Se as estruturas de dados forem consistentes com as esperadas pelo Cortex Framework Data Foundation, você poderá pular a geração de visualizações de mapeamento definindo SFDC.createMappingViews=false.

Como configurar o módulo de extração

Esta seção apresenta as etapas para usar o módulo de extração do Salesforce para o BigQuery fornecido pela Data Foundation. Seus requisitos e fluxo podem variar dependendo do sistema e da configuração atual. Você também pode usar outras ferramentas disponíveis.

Configurar credenciais e o app conectado

Faça login como administrador na sua instância do Salesforce para concluir as seguintes etapas:

Crie ou identifique um perfil no Salesforce que atenda aos seguintes requisitos:
1. Permission for Apex REST Services and API Enabled é concedida em Permissões do sistema.
2. A permissão View All é concedida para todos os objetos que você quer replicar. Por exemplo, "Conta" e "Casos". Verifique se há restrições ou problemas com seu administrador de segurança.
3. Nenhuma permissão concedida relacionada ao login da interface do usuário, como o Salesforce Anywhere na Experiência do Lightning, o Salesforce Anywhere no dispositivo móvel, o usuário da Experiência do Lightning e o usuário do Login do Lightning. Verifique se há restrições ou problemas com seu administrador de segurança.
Crie ou use um usuário existente no Salesforce. Você precisa saber o nome de usuário, a senha e o token de segurança do usuário. Considere o seguinte:
- O ideal é que seja um usuário dedicado a executar essa replicação.
- O usuário precisa ser atribuído ao perfil que você criou ou identificou na etapa 1.
- Você pode conferir o Nome de usuário e redefinir a Senha aqui.
- É possível redefinir o token de segurança se você não tiver um e ele não for usado por outro processo.
Crie um app conectado. Esse é o único canal de comunicação para estabelecer conexão com o Salesforce do mundo externo com a ajuda do perfil, da API do Salesforce, das credenciais de usuário padrão e do token de segurança.
1. Siga as instruções para ativar as configurações de OAuth para integração de API.
2. Verifique se Require Secret for Web Server Flow e Require Secretfor Refresh Token Flow estão ativados na seção API (Enabled OAuth Settings).
3. Consulte a documentação sobre como conseguir a chave de consumidor (que será usada mais tarde como ID do cliente). Verifique com o administrador de segurança se há problemas ou restrições.
Atribua o app conectado ao perfil criado.
1. Selecione Configuração no canto superior direito da tela inicial do Salesforce.
2. Na caixa Pesquisa rápida, digite profile e selecione Perfil. Pesquise o perfil criado na etapa 1.
3. Abra o perfil.
4. Clique no link Apps conectados atribuídos.
5. Clique em Editar.
6. Adicione o app conectado recém-criado.
7. Clique no botão Save.

Configurar o Secret Manager

Configure o Secret Manager para armazenar detalhes da conexão. O módulo do Salesforce para o BigQuery depende do Secret Manager para armazenar com segurança as credenciais necessárias para se conectar ao Salesforce e ao BigQuery. Essa abordagem evita a exposição de informações sensíveis, como senhas, diretamente no código ou nos arquivos de configuração, melhorando a segurança.

Crie um secret com as seguintes especificações. Para mais detalhes, consulte Criar um secret.

Nome do segredo: airflow-connections-salesforce-conn
Valor do secret:
```
http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`
```
Substitua:
- USERNAME pelo seu nome de usuário.
- PASSWORD com sua senha.
- INSTANCE_NAME com o nome da instância.
- CLIENT_ID pelo ID do cliente.
- SECRET_TOKEN pelo token secreto.

Para mais informações, consulte como encontrar o nome da instância.

Bibliotecas do Cloud Composer para replicação

Para executar os scripts Python nos DAGs fornecidos pela base de dados do Cortex Framework, é necessário instalar algumas dependências. Para a versão 1.10 do Airflow, siga a documentação de instalação de dependências do Python para o Cloud Composer 1 para instalar os seguintes pacotes, em ordem:

tableauserverclient==0.17
apache-airflow-backport-providers-salesforce==2021.3.3

Para a versão 2.x do Airflow, consulte a documentação Instalar dependências do Python para a documentação do Cloud Composer 2 para instalar o apache-airflow-providers-salesforce~=5.2.0.

Use o comando a seguir para instalar cada pacote necessário:

  gcloud composer environments update ENVIRONMENT_NAME \
  --location LOCATION \
   --update-pypi-package PACKAGE_NAME EXTRAS_AND_VERSION

Substitua:

ENVIRONMENT_NAME pelo nome do ambiente atribuído.
LOCATION com o local.
PACKAGE_NAME pelo nome do pacote escolhido.
EXTRAS_AND_VERSION com as especificações dos extras e da versão.

O comando abaixo é um exemplo de instalação de pacote necessária:

gcloud composer environments update my-composer-instance \
  --location us-central1 \
  --update-pypi-package apache-airflow-backport-providers-salesforce>=2021.3.3

Ativar o Secret Manager como um back-end

Ative o Google Secret Manager como o back-end de segurança. Nesta etapa, você vai ativar o Secret Manager como o local de armazenamento principal para informações sensíveis, como senhas e chaves de API usadas pelo ambiente do Cloud Composer. Isso melhora a segurança ao centralizar e gerenciar credenciais em um serviço dedicado. Para mais informações, consulte o Secret Manager.

Permita que a conta de serviço do Composer acesse os secrets

Essa etapa garante que a conta de serviço associada ao Cloud Composer tenha as permissões necessárias para acessar os secrets armazenados no Secret Manager. Por padrão, o Cloud Composer usa a conta de serviço do Compute Engine. A permissão necessária é Secret Manager Secret Accessor. Essa permissão permite que a conta de serviço recupere e use segredos armazenados no Secret Manager.Para conferir um guia completo sobre como configurar controles de acesso no Secret Manager, consulte a documentação de controle de acesso.

Conexão do BigQuery no Airflow

Crie a conexão sfdc_cdc_bq de acordo com a seção Como coletar as configurações do Cloud Composer. Essa conexão provavelmente é usada pelo módulo do Salesforce para BigQuery para estabelecer a comunicação com o BigQuery.

A seguir

Para mais informações sobre outras fontes de dados e cargas de trabalho, consulte Fontes de dados e cargas de trabalho.
Para mais informações sobre as etapas de implantação em ambientes de produção, consulte Pré-requisitos de implantação da base de dados do Cortex Framework.