Esta página foi traduzida pela API Cloud Translation.

Integração com o Salesforce (SFDC)

Esta página descreve os passos de integração para a carga de trabalho operacional do Salesforce (SFDC) na Data Foundation do Cortex Framework. A framework Cortex integra dados da Salesforce com pipelines do Dataflow através do BigQuery, enquanto o Cloud Composer agenda e monitoriza estes pipelines do Dataflow para obter estatísticas a partir dos seus dados.

Ficheiro de configuração

O ficheiro config.json no repositório da base de dados do Cortex Framework configura as definições necessárias para transferir dados de qualquer origem de dados, incluindo o Salesforce. Este ficheiro 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 seguinte descreve o valor de cada parâmetro operacional do SFDC:

Parâmetro	Significado	Valor predefinido	Descrição
`SFDC.deployCDC`	Implemente o CDC	`true`	Gere scripts de processamento de CDC para executar como DAGs no Cloud Composer. Consulte a documentação para ver diferentes opções de carregamento para o Salesforce Sales Cloud.
`SFDC.createMappingViews`	Crie visualizações de mapeamento	`true`	Os DAGs fornecidos para obter novos registos das APIs Salesforce atualizam os registos na página de destino. Este valor definido como verdadeiro gera vistas no conjunto de dados processado de CDC para expor tabelas com a "versão mais recente da verdade" do conjunto de dados não processado. Se for falso e `SFDC.deployCDC` for `true`, são gerados DAGs com o processamento de captura de dados de alterações (CDC) com base em SystemModstamp. Veja detalhes sobre o processamento de CDC para o Salesforce.
`SFDC.createPlaceholders`	Crie marcadores de posição	`true`	Crie tabelas de marcadores de posição vazias caso não sejam geradas pelo processo de carregamento para permitir que a implementação de relatórios a jusante seja executada sem falhas.
`SFDC.datasets.raw`	Conjunto de dados de destino não processados	-	Usado pelo processo de CDC, é aqui que a ferramenta de replicação coloca os dados do Salesforce. Se usar dados de teste, crie um conjunto de dados vazio.
`SFDC.datasets.cdc`	Conjunto de dados processados do CDC	-	Conjunto de dados que funciona como origem para as vistas de relatórios e destino para os DAGs processados de registos. Se usar dados de teste, crie um conjunto de dados vazio.
`SFDC.datasets.reporting`	Conjunto de dados de relatórios SFDC	`"REPORTING_SFDC"`	Nome do conjunto de dados acessível aos utilizadores finais para fins de relatórios, onde as visualizações e as tabelas orientadas para o utilizador são implementadas.
`SFDC.currencies`	Filtrar moedas	`[ "USD" ]`	Se não estiver a usar dados de teste, introduza uma única moeda (por exemplo, `[ "USD" ]`) ou várias moedas (por exemplo, `[ "USD", "CAD" ]`), conforme relevante para a sua empresa. Estes valores são usados para substituir marcadores de posição em SQL nos modelos de estatísticas quando disponíveis.

Modelo de dados

Esta secção descreve o modelo de dados do Salesforce (SFDC) através do diagrama de relação entre entidades (ERD).

Figura 2. Salesforce (SFDC): diagrama de relação entre entidades.

Visualizações de base

Estes são os objetos azuis no DRE e são vistas em tabelas de CDC sem transformações, exceto alguns alias de nomes de colunas. Veja guiões em src/SFDC/src/reporting/ddls.

Visualizações de propriedade de relatórios

Estes são os objetos verdes no DER e contêm os atributos dimensionais relevantes usados pelas tabelas de relatórios. Veja guiões em src/SFDC/src/reporting/ddls.

Requisitos de dados do Salesforce

Esta secção descreve os detalhes de como os seus dados do Salesforce têm de ser estruturados para utilização com o Cortex Framework.

Estrutura da tabela:
- Nomenclatura: os nomes das tabelas usam snake_case (palavras em minúsculas separadas por sublinhados) e estão no plural. 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 campos podem ser ligeiramente ajustados para maior clareza na camada de relatórios.
Tabelas vazias e implementação: todas as tabelas necessárias em falta no conjunto de dados bruto são criadas automaticamente como tabelas vazias durante o processo de implementação. Isto garante a execução sem problemas do passo de implementação da CDC.
Requisitos de CDC: os campos Id e SystemModstamp são essenciais para que os scripts de CDC acompanhem as alterações nos seus dados. Podem ter estes nomes exatos ou nomes diferentes. Os scripts de processamento não processado fornecidos obtêm estes campos automaticamente das APIs e atualizam a tabela de replicação de destino.
- Id: este valor funciona como um identificador exclusivo para cada registo.
- SystemModstamp: este campo armazena uma data/hora que indica a última vez que um registo foi modificado.
Scripts de processamento não processados:os scripts de processamento não processados fornecidos não requerem processamento adicional (CDC). Este comportamento é definido durante a implementação por predefinição.

Tabelas de origem para conversão de moeda

O Salesforce permite-lhe gerir moedas de duas formas:

Básico: esta é a predefinição, em que todos os dados usam uma única moeda.
Avançado: converte entre várias moedas com base nas taxas de câmbio (requer a ativação da gestão avançada de moedas).

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

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

O framework Cortex espera que estas tabelas estejam presentes se usar a gestão avançada de moedas. Se não usar a gestão avançada de moedas, pode remover entradas relacionadas com estas tabelas de um ficheiro de configuração (src/SFDC/config/ingestion_settings.yaml). Este passo impede tentativas desnecessárias de extrair dados de tabelas inexistentes.

Carregar dados do SFDC para o BigQuery

A estrutura Cortex oferece uma solução de replicação baseada em scripts Python agendados no Apache Airflow e na API em massa 2.0 do Salesforce. Estes scripts Python podem ser adaptados e agendados na ferramenta da sua preferência. Para mais informações, consulte o módulo de extração do SFDC.

O Cortex Framework também oferece três métodos diferentes para integrar os seus dados, consoante a origem dos dados e a forma como são geridos:

Chamadas API: esta opção destina-se a dados que podem ser acedidos diretamente através de uma API. O Cortex Framework pode chamar a API, obter os dados e armazená-los num conjunto de dados "Raw" no BigQuery. Se existirem registos no conjunto de dados, a Framework Cortex pode atualizá-los com os novos dados.
Visualizações de mapeamento de estrutura: este método é útil se já tiver os dados carregados no BigQuery através de outra ferramenta, mas a estrutura de dados não corresponder ao que a Framework Cortex precisa. O Cortex Framework usa "vistas" (como tabelas virtuais) para traduzir a estrutura de dados existente no formato esperado pelas funcionalidades de relatórios do Cortex Framework.
Scripts de processamento de CDC (captura de dados de alterações): esta opção foi concebida especificamente para dados que estão em constante mudança. Os scripts de CDC monitorizam estas alterações e atualizam os dados no BigQuery em conformidade. Estes scripts baseiam-se em dois campos especiais nos seus dados:
- Id: identificador exclusivo de cada registo.
- SystemModstamp: uma data/hora que indica quando um registo foi alterado.
Se os seus dados não tiverem exatamente estes nomes, os scripts podem ser ajustados para os reconhecer com nomes diferentes. Também pode adicionar campos personalizados ao seu esquema de dados durante este processo. Por exemplo, a tabela de origem com dados do objeto Account deve ter os campos originais Id e SystemModstamp. Se estes campos tiverem nomes diferentes, o ficheiro src/SFDC/src/table_schema/accounts.csv tem de ser atualizado com o nome do campo Id mapeado para AccountId e qualquer campo de data/hora de modificação do sistema mapeado para SystemModstamp. Para mais informações, consulte a documentação de SystemModStamp.

Se já tiver carregado dados através de outra ferramenta (e estes forem atualizados constantemente), o Cortex ainda os pode usar. Os scripts de CDC incluem ficheiros de mapeamento que podem traduzir a sua estrutura de dados existente para o formato de que o Cortex Framework precisa. Pode até adicionar campos personalizados aos seus dados durante este processo.

Configure a integração da API e a CDC

Para importar os seus dados do Salesforce para o BigQuery, pode usar as seguintes formas:

Scripts do Cortex para chamadas API: fornece scripts de replicação para o Salesforce ou uma ferramenta de replicação de dados à sua escolha.O importante é que os dados que importa devem ter o mesmo aspeto que teriam se fossem provenientes das APIs do Salesforce.
Ferramenta de replicação e anexar sempre : se estiver a usar uma ferramenta para replicação, esta forma destina-se a uma ferramenta que pode adicionar novos registos de dados (_appendalways_pattern) ou atualizar registos existentes.
Ferramenta de replicação e adicionar novos registos: se a ferramenta não atualizar os registos e replicar as alterações como novos registos numa tabela de destino (não processada), a Cortex Data Foundation oferece 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. Fluxo de trabalho do Salesforce: opções de integração de dados.

Para se certificar de que os seus dados correspondem ao que a framework Cortex espera, pode ajustar a configuração de mapeamento para mapear a sua ferramenta de replicação ou esquemas existentes. Isto gera vistas de mapeamento compatíveis com a estrutura esperada pela Data Foundation do Cortex Framework.

Use o ficheiro ingestion_settings.yaml para configurar a geração de scripts para chamar as APIs Salesforce e replicar os dados no conjunto de dados não processados (secção salesforce_to_raw_tables) e a geração de scripts para processar as alterações recebidas no conjunto de dados não processados e no conjunto de dados processados de CDC (secção raw_to_cdc_tables).

Por predefinição, os scripts fornecidos para ler a partir de APIs atualizam as alterações no conjunto de dados não processados. Por isso, não são necessários scripts de processamento de CDC. Em alternativa, são criadas vistas de mapeamento para alinhar o esquema de origem com o esquema esperado.

A geração de scripts de processamento de CDC não é executada se SFDC.createMappingViews=true no config.json (comportamento predefinido). Se forem necessários scripts de CDC, defina SFDC.createMappingViews=false. Este segundo passo também permite o mapeamento entre os esquemas de origem e os esquemas necessários, conforme exigido pela Data Foundation da Cortex Framework.

O exemplo seguinte de um ficheiro de configuração setting.yaml ilustra a geração de vistas 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). Uma vez que não é necessário nenhum CDC, esta opção é executada desde que o parâmetro SFDC.createMappingViews no ficheiro config.json permaneça 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 secções ignora a geração de DAGs dessa tabela de base ou de toda a secção, conforme ilustrado para salesforce_to_raw_tables. Neste cenário, a definição do parâmetro deployCDC : False tem o mesmo efeito, uma vez que não é necessário gerar scripts de processamento de CDC.

Mapeamento de dados

Tem de mapear os campos de dados recebidos para o formato esperado pela Cortex Data Foundation. Por exemplo, um campo denominado unicornId do seu sistema de dados de origem deve 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)
Cortex Field: AccountId (nome esperado pelo Cortex)
Tipo de dados: String (tipo de dados esperado pelo Cortex)

Mapeamento de campos polimórficos

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

Modificar modelos DAG

Pode ter de ajustar os modelos de DAG para CDC ou para processamento de dados não processados, conforme necessário para a sua instância do Airflow ou do Cloud Composer. Para mais informações, consulte o artigo Recolher definições do Cloud Composer.

Se não precisar da CDC nem da geração de dados não processados a partir de chamadas API, defina deployCDC=false. Em alternativa, pode remover o conteúdo das secções em ingestion_settings.yaml. Se souber que as estruturas de dados são consistentes com as esperadas pela base de dados do framework Cortex, pode ignorar a geração de vistas de mapeamento definindo SFDC.createMappingViews=false.

Configurar o módulo de extração

Esta secção apresenta os passos para usar o módulo de extração do Salesforce para o BigQuery fornecido pela Data Foundation. Os seus requisitos e fluxo podem variar consoante o seu sistema e configuração existente. Em alternativa, pode usar outras ferramentas disponíveis.

Configure credenciais e a app associada

Inicie sessão como administrador na sua instância do Salesforce para concluir o seguinte:

Crie ou identifique um perfil no Salesforce que cumpra os seguintes requisitos:
1. Permission for Apex REST Services and API Enabled é concedida ao abrigo das autorizações do sistema.
2. A autorização View All é concedida para todos os objetos que quer replicar. Por exemplo, Conta e Registos. Verifique se existem restrições ou problemas com o seu administrador de segurança.
3. Não foram concedidas autorizações relacionadas com o início de sessão na interface do utilizador, como o Salesforce Anywhere no Lightning Experience, o Salesforce Anywhere em dispositivos móveis, o utilizador do Lightning Experience e o utilizador de início de sessão do Lightning. Verifique se existem restrições ou problemas com o seu administrador de segurança.
Crie ou use um utilizador existente no Salesforce. Tem de saber o nome de utilizador, a palavra-passe e o token de segurança do utilizador. Considere o seguinte:
- Idealmente, deve ser um utilizador dedicado à execução desta replicação.
- O utilizador deve ser atribuído ao perfil que criou ou identificou no passo 1.
- Pode ver o Nome de utilizador e repor a Palavra-passe aqui.
- Pode repôr o token de segurança se não o tiver e não for usado por outro processo.
Crie uma app associada. É o único canal de comunicação para estabelecer ligação ao Salesforce a partir do mundo externo com a ajuda do perfil, da API Salesforce, das credenciais de utilizador padrão e do respetivo token de segurança.
1. Siga as instruções para ativar as definições do OAuth para a integração da API.
2. Certifique-se de que Require Secret for Web Server Flow e Require Secretfor Refresh Token Flow estão ativados na secção API (definições de OAuth ativadas).
3. Consulte a documentação sobre como obter a sua chave do consumidor (que será usada posteriormente como o seu ID de cliente). Verifique com o seu administrador de segurança se existem problemas ou restrições.
Atribua a sua app associada ao perfil criado.
1. Selecione Configuração na parte superior direita do ecrã principal do Salesforce.
2. Na caixa Localizar rapidamente, introduza profile e, de seguida, selecione Perfil. Pesquise o perfil criado no passo 1.
3. Abra o perfil.
4. Clique no link Apps associadas atribuídas.
5. Clique em Edit.
6. Adicione a app associada criada recentemente.
7. Clique no botão Guardar.

Configure o Secret Manager

Configure o Secret Manager para armazenar detalhes de ligação. O módulo do Salesforce para o BigQuery baseia-se no Secret Manager para armazenar em segurança as credenciais necessárias para estabelecer ligação ao Salesforce e ao BigQuery. Esta abordagem evita a exposição de informações confidenciais, como palavras-passe, diretamente no seu código ou ficheiros de configuração, o que melhora a segurança.

Crie um segredo com as seguintes especificações. Para instruções mais detalhadas, consulte o artigo Crie um segredo.

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

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

Bibliotecas do Cloud Composer para replicação

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

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

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

Use o seguinte comando para instalar cada pacote necessário:

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

Substitua o seguinte:

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

O comando seguinte é um exemplo de uma instalação de pacote obrigatória:

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

Ative o Secret Manager como um back-end

Ative o Google Secret Manager como o back-end de segurança. Este passo indica-lhe como ativar o Secret Manager como a localização de armazenamento principal para informações confidenciais, como palavras-passe e chaves de API usadas pelo seu ambiente do Cloud Composer. Isto melhora a segurança através da centralização e da gestão de credenciais num serviço dedicado. Para mais informações, consulte o Secret Manager.

Permita que a conta de serviço do Composer aceda a segredos

Este passo garante que a conta de serviço associada ao Cloud Composer tem as autorizações necessárias para aceder aos segredos armazenados no Secret Manager. Por predefinição, o Cloud Composer usa a conta de serviço do Compute Engine. A autorização necessária é Secret Manager Secret Accessor. Esta autorização permite que a conta de serviço obtenha e utilize segredos armazenados no Secret Manager.Para um guia abrangente sobre a configuração dos controlos de acesso no Secret Manager, consulte a documentação de controlo de acesso.

Ligação do BigQuery no Airflow

Certifique-se de que cria a associação sfdc_cdc_bq de acordo com o artigo Recolher definições do Cloud Composer. Esta ligação é provavelmente usada pelo módulo do Salesforce para o BigQuery para estabelecer comunicação com o BigQuery.

O que se segue?

Para mais informações sobre outras origens de dados e cargas de trabalho, consulte o artigo Origens de dados e cargas de trabalho.
Para mais informações sobre os passos de implementação em ambientes de produção, consulte os Pré-requisitos de implementação da base de dados do Cortex Framework.