Esta página foi traduzida pela API Cloud Translation.

Integração com o Salesforce (SFDC)

Nesta página, descrevemos as etapas de integração da carga de trabalho operacional do Salesforce (SFDC) na Data Foundation do framework Cortex. O Cortex Framework integra dados do Salesforce com pipelines do Dataflow no BigQuery, enquanto o Cloud Composer programa e monitora esses pipelines do Dataflow para extrair insights dos seus dados.

Arquivo de configuração

O arquivo config.json no repositório do Cortex Framework Data Foundation configura as definições necessárias para transferir dados de qualquer fonte de dados, incluindo o Salesforce. Esse 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 executar como DAGs no Cloud Composer. Consulte a documentação sobre as diferentes opções de ingestão 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. Quando definido como "true", esse valor gera visualizações no conjunto de dados processado de CDC para expor tabelas com a "versão mais recente da verdade" do conjunto de dados bruto. Se for "false" e `SFDC.deployCDC` for `true`, os DAGs serão gerados com o processamento de captura de dados de alterações (CDC) com base em SystemModstamp. Confira detalhes sobre o processamento de CDC para o Salesforce.
`SFDC.createPlaceholders`	Criar marcadores	`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 coloca 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 uma fonte para as visualizações de relatórios e como destino para os DAGs de registros processados. 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 acessível aos usuários finais para geração de relatórios, em que as visualizações e as tabelas voltadas ao usuário são implantadas.
`SFDC.currencies`	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 relevante para sua empresa. Esses valores são usados para substituir marcadores em SQL nos 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 entre entidades (ERD, na sigla em inglês).

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

Visualizações básicas

Esses são os objetos azuis no diagrama ER e são visualizações em tabelas de CDC sem transformações além de alguns aliases de nomes de colunas. Consulte scripts em src/SFDC/src/reporting/ddls.

Vistas de relatórios

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

Requisitos de dados do Salesforce

Esta seção descreve como seus dados do Salesforce precisam ser estruturados para uso com o Cortex Framework.

Estrutura da tabela:
- Nomenclatura:os nomes de tabela usam snake_case (palavras em letras minúsculas separadas por sublinhados) e são no plural. Por exemplo, some_objects.
- Tipos de dados:as colunas mantêm os mesmos tipos de dados representados no Salesforce.
- Legibilidade:alguns nomes de campo podem ser ajustados para melhorar a clareza na camada de relatórios.
Tabelas vazias e implantação:todas as tabelas necessárias que não estiverem no conjunto de dados brutos serão criadas automaticamente como tabelas vazias durante o processo de implantação. Isso garante a execução tranquila da etapa de implantação do CDC.
Requisitos de CDC:os campos Id e SystemModstamp são cruciais para que os scripts de CDC rastreiem mudanças nos seus dados. Eles podem ter esses nomes exatos ou outros diferentes. Os scripts de processamento bruto fornecidos buscam esses campos automaticamente das APIs e atualizam a tabela de replicação de destino.
- Id: funciona 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 adicional (CDC). Esse comportamento é definido por padrão durante a implantaçã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: faz a conversão entre várias moedas com base nas taxas de câmbio. É necessário ativar o Gerenciamento avançado de moedas.

Se você usa o Gerenciamento avançado de moedas, o Salesforce usa duas tabelas especiais:

CurrencyTypes: esta tabela armazena informações sobre as diferentes moedas que você usa (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 o gerenciamento avançado de moedas. Se você não usa o gerenciamento avançado de moedas, remova as 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

Cortex Framework oferece uma solução de replicação baseada em scripts Python programados no Apache Airflow e na API Salesforce Bulk 2.0. Esses scripts podem ser adaptados e programados na ferramenta de sua preferência. 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 da origem e da forma de gerenciamento:

Chamadas de API:essa opção é para dados que podem ser acessados diretamente por uma API. O Cortex Framework pode chamar a API, coletar 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.
Estruturar visualizações de mapeamento:esse método é útil se você já tiver carregado seus dados no BigQuery usando outra ferramenta, mas a estrutura de dados não corresponder ao que o Cortex Framework precisa. Cortex Framework usa "visualizações" (como tabelas virtuais) para traduzir a estrutura de dados atual no formato esperado pelos recursos de geração 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 de CDC rastreiam essas mudanças e atualizam os dados no BigQuery de acordo com elas. Esses scripts dependem de dois campos especiais nos seus dados:
- Id: identificador exclusivo de 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 esquema de dados durante esse processo. Por exemplo, a tabela de origem com dados do objeto "Conta" precisa ter os campos originais Id e SystemModstamp. Se esses campos tiverem nomes diferentes, o arquivo src/SFDC/src/table_schema/accounts.csv precisará 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 eles forem atualizados constantemente), o Cortex ainda poderá usá-los. Os scripts de CDC vêm com arquivos de mapeamento que podem traduzir sua estrutura de dados atual para o formato necessário pelo Cortex Framework. Você pode até adicionar campos personalizados aos dados durante esse processo.

Configurar a integração da API e o CDC

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

Scripts do Cortex para chamadas de API: fornecem scripts de replicação para o Salesforce ou uma ferramenta de replicação de dados de sua escolha.O importante é que os dados importados sejam iguais aos que vêm das APIs do Salesforce.
Ferramenta de replicação e anexação sempre : se você estiver usando uma ferramenta de replicação, essa forma é para uma ferramenta que pode adicionar novos registros de dados (_appendalways_pattern) ou atualizar os registros atuais.
Ferramenta de replicação e adição de novos registros: se a ferramenta não atualizar os registros e replicar as mudanças como novos registros em uma tabela de destino (bruta), o Cortex Data Foundation vai oferecer a opção de criar scripts de processamento de CDC. Para mais informações, consulte o processo de CDC.

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

Figura 1. Opções de integração de dados da carga de trabalho do Salesforce.

Para garantir que seus dados correspondam ao que o Cortex Framework espera, ajuste a configuração de mapeamento para mapear sua ferramenta de replicação ou esquemas atuais. 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 bruto (seção salesforce_to_raw_tables) e a geração de scripts para processar as mudanças que chegam ao conjunto de dados bruto e ao conjunto de dados processado de CDC (seção raw_to_cdc_tables).

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

A geração de scripts de processamento de CDC não será executada se SFDC.createMappingViews=true em config.json (comportamento padrão). Se forem necessários scripts de CDC, 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 um novo mapeamento de tabelas e nomes de campos). Como não é necessário CDC, essa opção será executada enquanto o parâmetro SFDC.createMappingViews no arquivo config.json permanecer 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"

Neste exemplo, a remoção da configuração de uma tabela de base ou de todas elas das seções pula a geração de DAGs dessa tabela ou de toda a seção, conforme 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 de 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)

Mapear campos polimórficos

A Data Foundation do Cortex Framework é compatível com o mapeamento de campos polimórficos, que são campos cujo nome pode variar, mas a estrutura permanece consistente. Nomes de tipos de campos polimórficos (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 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 pela base de dados do Cortex Framework, 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 o seguinte:

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 Salesforce Anywhere na Lightning Experience, Salesforce Anywhere para dispositivos móveis, usuário da Lightning Experience e usuário de 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 ver o Nome de usuário e redefinir a Senha aqui.
- Você pode redefinir o token de segurança se não tiver acesso a ele e ele não estiver sendo usado por outro processo.
Crie um app conectado. Ele é o único canal de comunicação para estabelecer conexão com o Salesforce do mundo externo com a ajuda de perfil, API do Salesforce, credenciais de usuário padrão e token de segurança.
1. Siga as instruções para ativar as configurações do 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 (configurações do OAuth ativadas).
3. Consulte a documentação para saber como conseguir sua chave de consumidor (que será usada mais tarde como seu ID do cliente). Verifique com seu 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 Salvar.

Configurar o Secret Manager

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

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

Nome do secret: airflow-connections-salesforce-conn
Valor da chave secreta:
```
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 com seu ID de cliente.
- SECRET_TOKEN com seu 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 nas DAGs fornecidas pela Data Foundation do Cortex Framework, é necessário instalar algumas dependências. Para o Airflow versão 1.10, 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 o Airflow versão 2.x, consulte a documentação Instalar dependências do Python para o Cloud Composer 2 para instalar 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 com o nome do ambiente atribuído.
LOCATION com o local.
PACKAGE_NAME com o nome do pacote escolhido.
EXTRAS_AND_VERSION com as especificações dos extras e da versão.

O comando a seguir é um exemplo de instalação de pacote obrigatório:

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 back-end de segurança. Esta etapa instrui você a ativar o Secret Manager como o local de armazenamento principal para informações sensíveis, como senhas e chaves de API usadas pelo seu ambiente do Cloud Composer. Isso aumenta a segurança ao centralizar e gerenciar credenciais em um serviço dedicado. Para mais informações, consulte Secret Manager.

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

Esta etapa garante que a conta de serviço associada ao Cloud Composer tenha as permissões necessárias para acessar 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 secrets armazenados no Secret Manager.Para 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 Como reunir configurações do Cloud Composer. Essa conexão provavelmente é usada pelo módulo do Salesforce para o BigQuery para estabelecer 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 Data Foundation do framework Cortex.