Openflow Connector for Salesforce Bulk API: Configuração do conector¶

Nota

O conector está sujeito aos Termos do conector Snowflake.

Este tópico descreve as etapas para configurar o Openflow Connector for Salesforce Bulk API.

Instalação do conector¶

Siga estas etapas para instalar o Openflow Connector for Salesforce Bulk API em um tempo de execução do Openflow:

Navegue até a página Overview do Openflow. Na seção Featured connectors, selecione View more connectors.
Na página de conectores do Openflow, encontre Openflow connector for Salesforce Bulk API e selecione Add to runtime.
Na caixa de diálogo Select runtime, selecione seu tempo de execução na lista suspensa Available runtimes.

A tela do Openflow é exibida com o grupo de processos do conector adicionado a ela.

Configuração do conector¶

Para configurar o conector, execute as seguintes etapas:

Clique com o botão direito do mouse no grupo de processos importado e selecione Parameters.
Preencha os valores de parâmetro necessários conforme descrito na tabela abaixo.


Parâmetro	Descrição
Estratégia de remoção de coluna	Define a estratégia a ser adotada quando uma coluna deve ser removida na tabela de destino com base no esquema recebido mais recente. Três valores possíveis: `Drop Column`, `Rename Column`, `Ignore Column`. `Drop Column`: descarte a coluna da tabela Snowflake. `Rename Column`: renomeie a coluna na tabela do Snowflake. `Ignore Column`: ignore a coluna, deixando-a como está na tabela do Snowflake.
Chave do app conectado	A chave privada utilizada para autenticação do JWT Bearer Flow com o Salesforce. Copie e cole o conteúdo do arquivo `private.key` gerado durante a configuração do Salesforce. Essa chave privada deve corresponder ao certificado público (`public.crt`) carregado no app cliente externo no Salesforce. Você também pode usar o próximo parâmetro para carregar o arquivo de chave privada.
Arquivo da chave do app conectado	Carregue o arquivo `private.key` selecionando a caixa de seleção Reference asset, depois carregue o arquivo como um recurso e selecione o recurso como o valor do parâmetro. Essa é uma alternativa a colar o conteúdo da chave no parâmetro Connected App Key.
Senha da chave do app conectado	Senha definida no arquivo de chave privada durante as etapas de configuração do Salesforce.
Banco de dados de destino	Nome do banco de dados no Snowflake onde os dados do Salesforce serão replicados. O banco de dados deve existir antes de iniciar o conector.
Esquema de destino	Nome do esquema, no banco de dados acima, no qual o conector criará tabelas para os dados do Salesforce a serem adicionados. O esquema deve existir antes de iniciar o conector.
Habilitar tabelas de diário	Se definida como `true`, uma tabela `JOURNAL_<Object Name>` é criada para cada objeto sincronizado que tem um campo `SystemModstamp` ou `LastModifiedDate`. Todas as alterações são anexadas à tabela de diário, fornecendo um histórico completo das modificações. Isso é adicional à tabela principal que contém os dados mesclados para o objeto. Se ocorrer uma recarga completa para um determinado tipo de objeto, a tabela de diário dele também será recriada. Padrão: `false`.
Habilitar a criação de exibições	Se definida como `true`, uma exibição chamada `<Object Type>_FORMULA_VW` será criada para cada objeto sincronizado que contém campos de fórmula. A exibição converte as expressões de fórmula do Salesforce compatíveis em Snowflake SQL, permitindo que você consulte os resultados da fórmula diretamente sem replicar os valores do campo de fórmula do Salesforce. Consulte Campos de fórmula do Salesforce para obter mais detalhes. Padrão: `false`.
Filter	Lista de objetos separados por vírgulas a serem replicados do Salesforce ou expressão regular a ser aplicada a todos os objetos existentes. O filtro não diferencia maiúsculas de minúsculas, o que significa que um filtro definido como `account` corresponde ao tipo de objeto `Account`. Exemplo: `Account, Opportunity, Contact`. Nota Se deixado em branco, todos os objetos serão replicados. Não recomendamos isso, pois geralmente existem milhares de objetos em uma instância do Salesforce.
Descarregamento incremental	Se o processador deve executar o descarregamento incremental. Se for `true`, o processador buscará apenas os registros que foram modificados desde o último envio do trabalho de consulta usando uma cláusula `WHERE` no campo de carimbo de data/hora apropriado. Se for `false`, todos os registros serão buscados a cada execução do conector.
Divisão em partes do carregamento inicial	Se for definido para um valor diferente de `NONE`, o carregamento inicial de dados será dividido em vários trabalhos com base nesse intervalo. Na primeira execução de um objeto, o conector consultará o Salesforce para encontrar o registro mais antigo e usá-lo como ponto de partida. Cada trabalho subsequente consultará a próxima parte de tempo até alcançar o tempo atual. Deve ser definido com um dos seguintes valores: `NONE`, `MONTHLY`, `QUARTERLY`, `YEARLY`. Isso é útil para grandes conjuntos de dados, em que o carregamento de todos os dados históricos em uma única consulta pode expirar, exceder os limites de API ou ultrapassar o tamanho de armazenamento do repositório de conteúdo do tempo de execução. Depois disso, o processador continua com o comportamento de descarregamento incremental normal.
Público do OAuth2	Público a ser definido no token JWT. Defina como `https://login.salesforce.com` para ambientes de produção ou `https://test.salesforce.com` para ambientes de teste e sandboxes.
ID de cliente do OAuth2	Deve ser definido com o valor de Consumer Key obtido durante as etapas de configuração do Salesforce.
Assunto do OAuth2	Deve ser definido como o nome de usuário de um usuário aprovado pelo administrador para que o aplicativo interaja com as APIs do Salesforce em nome desse usuário.
URL do ponto de extremidade do token OAuth2	Ponto de extremidade para negociar tokens por meio do JWT Bearer Flow. Exemplo: `https://myCompany.my.salesforce.com/services/oauth2/token`.
JSON de filtro de campos de objeto	Um JSON especificando quais campos e padrões de campo devem ser incluídos ou excluídos, por objeto do Salesforce. Assume a forma de uma matriz com um item por objeto. Exemplo 1: Isso incluirá todos os campos que terminam com “name” no objeto “Account” do Salesforce: `[ {"objectType":"Account", "includedPattern":".*name"} ]` Exemplo 2: Isso incluirá os campos Id, Name e Revenue no objeto “Account” do Salesforce: `[ {"objectType":"Account", "included": ["Id", "Name", "Revenue"]} ]` `excluded` e `excludedPattern` também estão disponíveis para configurar os filtros.
Resolução do identificador do objeto	Determina se os nomes de esquema/tabela/coluna são tratados de forma a diferenciar ou não maiúsculas e minúsculas. Uma das seguintes opções: `CASE_INSENSITIVE`/`CASE_SENSITIVE`. Nota Alterar o valor deste parâmetro exigirá limpar o estado e recarregar completamente todos os objetos.
Sufixo de nome de coluna removido	Sufixo adicionado ao nome da coluna quando o parâmetro Column Removal Strategy é definido como `Rename Column`. Padrão: `__deleted`.
Cronograma de execução	Frequência com que o conector verificará atualizações no Salesforce para objetos configurados por meio do parâmetro Filter. Padrão: `15 minutes`.
Instância do Salesforce	Nome do host da instância do Salesforce, incluindo o nome do domínio. Não inclua o prefixo do protocolo (`https://`). Por exemplo, use `myCompany.my.salesforce.com`.
Identificador de conta Snowflake	Nome da conta Snowflake formatado como `[organization-name]-[account-name]`, onde os dados serão persistidos. Exemplo: `PM-CONNECTORS`.
Nome de usuário do Snowflake	O nome do usuário de serviço que o conector usa para se conectar ao Snowflake. O usuário de serviço é necessário apenas ao usar a estratégia de autenticação `KEY_PAIR` (somente BYOC do Openflow).
Chave privada Snowflake	A chave privada RSA que o conector usa para autenticação no Snowflake, formatada de acordo com os padrões PKCS8 e incluindo cabeçalhos e rodapés PEM padrão. A linha de cabeçalho começa com `-----BEGIN PRIVATE`. Isso é necessário apenas ao usar a estratégia de autenticação `KEY_PAIR` (somente BYOC do Openflow). Você também pode usar o próximo parâmetro para carregar a chave privada no tempo de execução do Openflow.
Arquivo de chave privada Snowflake	O arquivo que contém a chave privada RSA que o conector usa para autenticação no Snowflake, formatado de acordo com os padrões PKCS8 e incluindo cabeçalhos e rodapés PEM padrão. A linha de cabeçalho começa com `-----BEGIN PRIVATE`. Necessário apenas ao usar a estratégia de autenticação `KEY_PAIR` (somente BYOC do Openflow). Marque a caixa de seleção Reference asset para carregar o arquivo de chave privada e armazená-lo com segurança no tempo de execução do Openflow.
Senha de chave privada Snowflake	A senha associada ao arquivo de chave privada do Snowflake (se criptografado). Isso é necessário apenas ao usar a estratégia de autenticação `KEY_PAIR` (somente BYOC do Openflow).
Função Snowflake	Nome da função do Snowflake utilizada durante a execução da consulta. Ao usar `SNOWFLAKE_MANAGED`, esta é a função do Snowflake para tempos de execução do Openflow. Ao usar `KEY_PAIR` (somente BYOC do Openflow), esta é a função atribuída ao nome de usuário do Snowflake especificado.
Estratégia de autenticação Snowflake	Estratégia de autenticação para o conector se conectar ao Snowflake. Usar `SNOWFLAKE_MANAGED` (padrão) utiliza o token gerenciado pelo Snowflake associado à função do tempo de execução do Snowflake especificada. Se estiver usando o OpenFlow BYOC, você também poderá usar `KEY_PAIR` para especificar um usuário e função específicos por meio de um par de chaves personalizado.
Warehouse Snowflake	O warehouse Snowflake utilizado para executar consultas.
Filtro de objetos especiais	Lista de objetos separados por vírgula para descarregar do Salesforce (usando acesso direto à API) ou expressão regular para aplicar a todos os objetos existentes. O filtro não diferencia maiúsculas de minúsculas, o que significa que um filtro definido como `account` corresponde ao tipo de objeto `Account`. Este filtro deve ser utilizado apenas para objetos que não são compatíveis com a API Salesforce Bulk, como dados de conhecimento, por exemplo. Este parâmetro não deve se sobrepor ao parâmetro Filter. Exemplo: `Knowledge.*`

Verificar a conexão do Salesforce¶

Antes de habilitar e iniciar o conector, o Snowflake recomenda verificar se a autenticação do Salesforce está configurada corretamente. O recurso Verificação nos serviços do controlador permite testar a conexão sem iniciar o fluxo completo do conector.

O serviço de controlador JWT Bearer OAuth2 Access Token Provider depende de outros dois serviços de controlador que devem ser ativados primeiro: o Salesforce Private Key Service e o Web Client Service Provider.

Clique duas vezes no grupo de processos do conector para abri-lo.
Clique com o botão direito do mouse em uma área vazia da tela e selecione Controller Services.
Ative os serviços Salesforce Private Key Service e Web Client Service Provider.
Localize o serviço JWT Bearer OAuth2 Access Token Provider na lista.
Clique no botão Verification do serviço. Uma caixa de diálogo será aberta, na qual você poderá fornecer substituições de propriedades. Você pode ignorar essa caixa de diálogo e clicar diretamente em Verify.
Se tudo estiver configurado corretamente, a etapa Acquire token exibirá uma marca de seleção verde indicando sucesso. Isso confirma que o conector pode se autenticar com o Salesforce e obter um token de acesso. Você pode prosseguir para a próxima etapa para executar o conector.
Se a verificação falhar, revise a mensagem de erro e verifique o seguinte:
- O parâmetro OAuth2 Client ID corresponde ao Consumer Key do app cliente externo no Salesforce.
- A chave privada corresponde ao certificado carregado no app cliente externo.
- O usuário OAuth2 Subject está autorizado para o app cliente externo (consulte Aprovar um aplicativo cliente para um usuário).
- O OAuth2 Token Endpoint URL usa o nome de host correto da instância do Salesforce.
- O OAuth2 Audience está definido com o valor correto: https://login.salesforce.com para produção ou https://test.salesforce.com para sandboxes.
Para obter informações detalhadas sobre solução de problemas, consulte Solução de problemas do Openflow Connector for Salesforce Bulk API.

Executar o conector¶

Siga estas etapas para iniciar o conector e começar a replicar dados do Salesforce para o Snowflake:

Clique com o botão direito do mouse em uma área vazia na tela e selecione Enable all Controller Services.
Clique com o botão direito do mouse no grupo de processos do conector e selecione Start.

Gerenciar replicação de objetos¶

Após o conector ser iniciado e os objetos serem replicados, você pode adicionar novos objetos ou remover objetos existentes da replicação.

Adicionar novos objetos à replicação¶

Para adicionar um novo objeto à replicação, atualize o parâmetro Filter (ou o parâmetro Special Objects Filter, se aplicável) com os nomes dos novos objetos. Você não precisa interromper o conector. O novo objeto será replicado na próxima execução agendada.

Por exemplo, se o valor atual de Filter for Account, Opportunity e você quiser adicionar o objeto Contact, altere o valor para Account, Opportunity, Contact.

Remover objetos da replicação¶

A remoção de um objeto da replicação requer a interrupção do conector e a limpeza do estado do conector e da tabela de destino no Snowflake:

Interrompa todos os processadores no fluxo clicando com o botão direito do mouse no grupo de processos do conector e selecionando Stop.
Certifique-se de que não há FlowFiles sendo processados.
Clique com o botão direito do mouse na tela e selecione Parameters, depois remova o nome do objeto do parâmetro Filter (ou do parâmetro Special Objects Filter, se aplicável).
Clique com o botão direito do mouse na tela e selecione Disable all controller services.
Acesse Controller services e abra o estado do serviço do controlador chamado Salesforce Bulk Jobs State.
Selecione o ícone da lixeira ao lado do tipo de objeto que você removeu para excluir a entrada de estado dele.
Clique com o botão direito do mouse na tela e selecione Enable all controller services, depois inicie todos os processadores para retomar o conector.
Se aplicável, descarte a tabela correspondente do banco de dados de destino do Snowflake para limpar os dados replicados anteriormente. Por exemplo:
```
DROP TABLE <database_name>.<schema_name>.<object_name>;
```

Próximos passos¶

Para monitorar e solucionar problemas do conector, consulte Solução de problemas do Openflow Connector for Salesforce Bulk API.