Executar consultas federadas no Salesforce Data 360

Esta página descreve como configurar a Federação Lakehouse para executar consultas federadas em dados do Salesforce Data 360, que não são gerenciados pelo Azure Databricks. Para saber mais sobre a Federação Lakehouse, veja o que é a Federação Lakehouse?

Para se conectar ao banco de dados Salesforce Data 360 usando a Lakehouse Federation, você deve criar o seguinte no metastore do Azure Databricks Unity Catalog:

• Uma conexão com o banco de dados Salesforce Data 360.
• Um catálogo estrangeiro que espelha seu banco de dados Salesforce Data 360 no Catálogo do Unity para que você possa usar a sintaxe de consulta do Catálogo do Unity e as ferramentas de governança de dados para gerenciar o acesso do usuário do Azure Databricks ao banco de dados.

Qual conector do Salesforce devo usar?

O Databricks oferece vários conectores para o Salesforce. Há dois conectores de cópia zero: o conector de compartilhamento de arquivos Salesforce Data 360 (antigo Data Cloud) e o conector de federação de consulta Salesforce Data 360. Elas permitem que você consulte dados no Salesforce Data 360 sem movê-los. Há também um conector de ingestão da Salesforce que copia dados de vários produtos, incluindo Salesforce Data 360 e Salesforce Sales Cloud.

A tabela a seguir resume as diferenças entre os conectores do Salesforce no Databricks:

Antes de começar

Requisitos do workspace:

• Workspace habilitado para o Catálogo do Unity.

Requisitos de computação:

• Conectividade de rede do recurso de computação para os sistemas de banco de dados de destino. Confira Recomendações de rede para a Federação de Lakehouse.
• A computação do Azure Databricks deve usar o Databricks Runtime 15.2 ou superior e o modo de acesso Standard ou Dedicado .
• Os sql warehouses devem ser profissionais ou sem servidor e devem usar 2024.30 ou superior.

Permissões necessárias:

• Para criar uma conexão, você deve ser um administrador de metastore ou um usuário com o privilégio de CREATE CONNECTION no metastore do Catálogo do Unity anexado ao workspace.
• Para criar um catálogo estrangeiro, você precisa ter a permissão de CREATE CATALOG no metastore e ser o proprietário da conexão ou ter o privilégio de CREATE FOREIGN CATALOG na conexão.

Requisitos de permissão adicionais são especificados em cada seção baseada em tarefa a seguir.

Criar um aplicativo conectado ao Salesforce

Os aplicativos conectados do Salesforce permitem que um aplicativo externo se integre ao Salesforce usando APIs e protocolos padrão. Esta seção descreve como criar um aplicativo conectado usando o SSO para permitir que o Databricks se autentique com o Salesforce.

Para criar um aplicativo conectado do Salesforce, faça o seguinte:

1. No canto superior direito do Data 360, clique em Configurar.
2. Em Ferramentas de Plataforma, clique em Aplicativos > Gerenciador de Aplicativos.
3. Clique em Novo Aplicativo Conectado.
4. Insira um nome e um endereço de email de contato.
5. Habilite as Configurações do OAuth:
   1. Insira a URL de retorno de chamada no seguinte formato: https://<databricks_instance_url>/login/oauth/salesforce.html. Por exemplo: https://cust-success.cloud.databricks.com/login/oauth/salesforce.html.
   2. (Opcional) Se você planeja usar o SQL para criar a conexão do Azure Databricks e o catálogo estrangeiro na próxima etapa, seu aplicativo conectado do Salesforce também precisará dar suporte ao URI de redirecionamento https://login.salesforce.com/services/oauth2/success. Isso não será necessário se você planeja usar o Catalog Explorer para criar a conexão do Azure Databricks e o catálogo estrangeiro. O Databricks recomenda o uso do Explorador de Catálogos porque requer menos etapas manuais do que outros métodos.
   3. Adicione os seguintes Escopos:
      • Acessar todos os recursos da API do Data 360 (cdp_api)
      • Gerenciar dados do usuário por meio de APIs (api)
      • Executar consultas SQL ANSI em dados data 360 (cdp_query_api)
      • Executar solicitações a qualquer momento (refresh_token, offline_access)
   4. Clique em Save (Salvar).
   5. Clique em Continuar.
6. Na página Visão geral do Aplicativo Conectado, clique em Gerenciar Detalhes do Consumidor. Você será solicitado a se autenticar.
7. Após uma autenticação bem-sucedida, a chave do consumidor e o segredo do consumidor são revelados. Salve esses valores. Você precisará deles ao criar uma conexão do Azure Databricks.

Criar uma conexão do Azure Databricks

Uma conexão especifica um caminho e credenciais para acessar um sistema de banco de dados externo. Para criar uma conexão, você pode usar o Explorador do Catálogo ou o comando SQL CREATE CONNECTION em um notebook do Azure Databricks, ou o editor de consulta do Databricks SQL.

Permissões necessárias: administrador do metastore ou usuário com o privilégio CREATE CONNECTION.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone Adicionar e selecione Adicionar uma conexão no menu.

   Como alternativa, na página Acesso rápido, clique no botão Dados externos >, vá até a guia Conexões e clique em Criar conexão.

3. Na página Noções básicas sobre a conexão do assistente Configurar conexão, insira um Nome da conexão amigável.

4. Selecione um tipo de conexão do Salesforce Data 360.

5. (Opcional) Adicione um comentário.

6. Na página Autenticação , insira as seguintes propriedades de conexão para o Salesforce Data 360:

   • (Opcional) Selecionar É área restrita.
   • ID do cliente: chave do consumidor do aplicativo conectado do Salesforce.
   • Segredo do cliente: segredo do consumidor do aplicativo conectado do Salesforce.
   • Escopo do cliente: cdp_api api cdp_query_api refresh_token offline_access

7. Clique em Entrar com o Salesforce.

8. (OAuth) Você será solicitado a entrar no Salesforce Data 360 usando suas credenciais de SSO.

9. Após o logon bem-sucedido, você será direcionado de volta para o assistente Configurar conexão do Databricks. O botão Entrar com Salesforce foi substituído por uma Successfully authorized mensagem.

10. Clique em Criar conexão.

11. Na página Noções básicas sobre o catálogo, insira um nome para o catálogo estrangeiro. Um catálogo estrangeiro espelha um banco de dados em um sistema de dados externo para que você possa consultar e gerenciar o acesso aos dados nesse banco de dados usando o Azure Databricks e o Catálogo do Unity.

12. Acesse o espaço de dados do Salesforce.

13. (Opcional) Clique em Testar conectividade para confirmar se está funcionando.

14. Clique em Criar catálogo.

15. Na página Access, selecione os workspaces nos quais os usuários podem acessar o catálogo que você criou. Você pode selecionar Todas as áreas de trabalho têm acesso ou clicar em Atribuir aos workspaces, selecionar as áreas de trabalho e então clicar em Atribuir.

16. Altere o Proprietário que poderá gerenciar o acesso a todos os objetos do catálogo. Comece a digitar uma entidade de segurança na caixa de texto e clique na entidade de segurança nos resultados retornados.

17. Conceda Privilégios no catálogo. Clique em Conceder:

    1. Especifique as Entidades de segurança que terão acesso a objetos no catálogo. Comece a digitar uma entidade de segurança na caixa de texto e clique na entidade de segurança nos resultados retornados.
    2. Selecione as Predefinições de privilégio a conceder a cada usuário. Todos os usuários da conta recebem BROWSE como padrão.
       • Selecione Leitor de Dados no menu suspenso para conceder privilégios read nos objetos no catálogo.
       • Selecione Editor de Dados no menu suspenso para conceder os privilégios read e modify nos objetos no catálogo.
       • Selecione manualmente os privilégios a serem concedidos.
    3. Selecione Conceder.

18. Clique em Próximo.

19. Na página Metadados, especifique os pares chave-valor daas tags. Para obter mais informações, consulte Aplicar etiquetas a objetos securitizáveis do Catálogo Unity.

20. (Opcional) Adicione um comentário.

21. Clique em Save (Salvar).

SQL

O Databricks recomenda usar o Explorador de Catálogos para criar a conexão e o catálogo estrangeiro, pois requer menos etapas manuais do que outros métodos.

Se você planeja usar o SQL para criar a conexão do Azure Databricks e o catálogo estrangeiro, seu aplicativo conectado do Salesforce precisará dar suporte ao URI de redirecionamento https://login.salesforce.com/services/oauth2/success. Isso não será necessário se você usar o Catalog Explorer.

1. Gere os códigos de desafio de código e verificador de código PKCE. Você pode fazer isso usando uma ferramenta online, como https://tonyxu-io.github.io/pkce-generator/ ou executando o seguinte script Python:

   %python
   
   import base64
   import re
   import os
   import hashlib
   
   code_verifier = base64.urlsafe_b64encode(os.urandom(40)).decode('utf-8')
   code_verifier = re.sub('[^a-zA-Z0-9]+', '', code_verifier)
   
   code_challenge = hashlib.sha256(code_verifier.encode('utf-8')).digest()
   code_challenge = base64.urlsafe_b64encode(code_challenge).decode('utf-8')
   code_challenge = code_challenge.replace('=', '')
   print(f"pkce_verifier  = \"{code_verifier}\"")
   print(f"code_challenge = \"{code_challenge}\"")
   

2. Visite a URL a seguir e autentique-se com suas credenciais do Salesforce para obter o authorization_code (substituir <client_id> e <code_challenge> pelos seus parâmetros).

   https://login.salesforce.com/services/oauth2/authorize
   ?client_id=<client_id>
   &redirect_uri=https://login.salesforce.com/services/oauth2/success
   &response_type=code
   &code_challenge=<code_challenge>
   

   Um código de autorização codificado em URL é visível na URL redirecionada.

3. Execute o comando a seguir em um notebook ou no editor de consultas SQL do Databricks:

   CREATE CONNECTION '<Connection name>' TYPE salesforce_data_cloud
   OPTIONS (
     client_id '<Consumer key from Salesforce Connected App>',
     client_secret '<Consumer secret from Salesforce Connected App>',
     pkce_verifier '<pkce_verifier from the last step>',
     authorization_code '<URL decoded `authorization_code`, should end with == instead of %3D%3D>',
     oauth_redirect_uri "https://login.salesforce.com/services/oauth2/success",
     oauth_scope "cdp_api api cdp_query_api refresh_token offline access",
     is_sandbox "false"
     );
   

   Recomendamos que você use segredos do Azure Databricks em vez de cadeias de caracteres de texto não criptografado para valores confidenciais, como credenciais. Por exemplo:

   CREATE CONNECTION '<Connection name>' TYPE salesforce_data_cloud
   OPTIONS (
     client_id secret ('<Secret scope>','<Secret key client id>'),
     client_secret secret ('<Secret scope>','<Secret key client secret>'),
     pkce_verifier '<pkce_verifier from the last step>',
     authorization_code '<URL decoded `authorization_code`, should end with == instead of %3D%3D>',
     oauth_redirect_uri "https://login.salesforce.com/services/oauth2/success",
     oauth_scope "cdp_api api cdp_query_api refresh_token offline access",
     is_sandbox "false"
     );
   

   Para obter informações sobre configuração de segredos, confira Gestão de segredos.

Criar um catálogo estrangeiro

Um catálogo estrangeiro espelha um banco de dados em um sistema de dados externo para que você possa consultar e gerenciar o acesso aos dados nesse banco de dados usando o Azure Databricks e o Catálogo do Unity. Para criar um catálogo estrangeiro, use uma conexão com a fonte de dados que já foi definida.

Para criar um catálogo estrangeiro, você pode usar o Explorador de Catálogos ou o comando SQL CREATE FOREIGN CATALOG em um notebook do Azure Databricks ou no editor de consultas SQL. Além disso, é possível usar a API REST do Databricks ou a CLI do Databricks para criar um catálogo. Confira POST /api/2.1/unity-catalog/catalogs e Comandos do Unity Catalog.

Permissões necessárias: permissão de CREATE CATALOG no metastore e propriedade da conexão ou o privilégio de CREATE FOREIGN CATALOG na conexão.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo para abrir o Gerenciador de Catálogos.
2. No canto superior direito, clique em Criar catálogo.
3. Insira as seguintes propriedades para o catálogo Salesforce Data 360.
   • Nome do catálogo: um nome amigável para o catálogo.
   • Tipo: Foreign.
   • Nome da conexão: o nome da conexão na qual o catálogo será criado.
   • Espaço de dados: um espaço de dados do Salesforce.
4. Clique em Criar.

SQL

Execute o seguinte comando SQL em um notebook ou no editor de consultas SQL. Os itens entre colchetes são opcionais.

CREATE FOREIGN CATALOG [IF NOT EXISTS] '<catalog-name>' USING CONNECTION '<connection-name>'
OPTIONS (dataspace '<dataspace>');

Substitua os seguintes valores:

• <catalog-name>:
• <connection-name>:
• <dataspace>: espaço de dados do Salesforce. Por exemplo, default.

Pushdowns com suporte

Há suporte para os seguintes pushdowns:

• Filtros
• Projeções
• Limite
• Agregações
• Deslocamento
• Elenco
• Contém, Começa com, Termina com

Mapeamentos de tipo de dados

Quando você lê do Salesforce Data 360 para o Spark, os tipos de dados são mapeados da seguinte maneira:

Limitações

• Há suporte para apenas um espaço de dados do Salesforce por catálogo do Databricks.
• No Databricks Runtime 16.1 e mais antigo, não há suporte para nomes de tabela e esquema que diferenciam maiúsculas de minúsculas. Isso inclui nomes com letras maiúsculas no Salesforce Data 360. Por exemplo, MyTable não há suporte.