execução de consultas federadas no Salesforce Data Cloud

Este artigo descreve como configurar o Lakehouse Federation para executar consultas federadas nos dados do Salesforce Data Cloud que não são gerenciados por Databricks. Para saber mais sobre a lakehouse Federation, consulte O que é a lakehouse Federation?

Para se conectar ao banco de dados do Salesforce Data Cloud usando o Lakehouse Federation, o senhor deve criar o seguinte no metastore Databricks Unity Catalog :

• Uma conexão com seu banco de dados do Salesforce Data Cloud.
• Um catálogo externo que espelha o banco de dados do Salesforce Data Cloud no Unity Catalog para que o senhor possa usar a sintaxe de consulta do Unity Catalog e as ferramentas de governança de dados para gerenciar o acesso do usuário do Databricks ao banco de dados.

Antes de começar

Requisitos do workspace:

• Espaço de trabalho preparado para o Catálogo do Unity.

Requisitos de computação:

• Conectividade de rede do seu recurso compute para os sistemas de banco de dados de destino. Veja as recomendações do Networking para a Lakehouse Federation.
• Databricks compute deve usar o site Databricks Runtime 15.2 ou acima e o modo de acesso Standard ou Dedicated .
• SQL O armazém deve ser pro ou serverless e deve usar 2024.30 ou acima.

Permissões necessárias:

• Para criar uma conexão, é preciso ser administrador de metastore ou usuário com o privilégio CREATE CONNECTION no metastore do Unity Catalog anexado ao espaço de trabalho.
• Para criar um catálogo externo é preciso ter a permissão CREATE CATALOG no metastore e ser proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG na conexão.

Outros requisitos de permissão são definidos em cada seção baseada em tarefa a seguir.

Crie um aplicativo conectado ao Salesforce

Os aplicativos conectados ao 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 SSO para permitir que o Databricks se autentique no Salesforce.

nota

Para obter instruções mais detalhadas, consulte Criar um aplicativo conectado na documentação do Salesforce Data Cloud.

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

1. No canto superior direito do Data Cloud, clique em Configurar.

2. Em Ferramentas da plataforma , clique em Apps > App Manager .

3. Clique em Novo aplicativo conectado .

4. Digite um nome e um endereço de contato email.

5. Ativar as configurações do OAuth :

   1. Insira o 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 o senhor planeja usar o SQL para criar a conexão Databricks e o catálogo externo na próxima etapa, seu Salesforce Connected App também precisa suportar o URI de redirecionamento https://login.salesforce.com/services/oauth2/success. Isso não é necessário se o senhor planeja usar o Catalog Explorer para criar a conexão com o Databricks e o catálogo externo. A Databricks recomenda o uso do Catalog Explorer porque ele exige menos etapas manuais do que outros métodos.

   3. Adicione os seguintes escopos :

      • Acessar todos os dados da nuvem API recurso (cdp_api )
      • Gerenciar dados do usuário via APIs (api )
      • Realizar consultas ANSI SQL nos dados do Data Cloud (cdp_query_api )
      • Realizar solicitações a qualquer momento (refresh, offline_access )

   4. Clique em Salvar .

   5. Clique em "Continuar" .

6. Na página de visão geral do Connected App , clique em gerenciar Consumer Details . Você será solicitado a se autenticar.

7. Após a autenticação bem-sucedida, o consumidor key e o segredo do consumidor são revelados. Salve esses valores. O senhor precisará deles quando criar uma conexão com o Databricks.

Criar uma conexão com o Databricks

A conexão especifica um caminho e as credenciais para acessar um sistema de banco de dados externo. Para criar uma conexão, você pode usar o Catalog Explorer ou o comando CREATE CONNECTION do SQL em um Notebook do Databricks ou no editor de consultas SQL do Databricks.

nota

O senhor também pode usar a API REST da Databricks ou a CLI da Databricks para criar uma conexão. Veja POST /api/2.1/unity-catalog/connections e Unity Catalog comando.

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

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

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 de acesso rápido , clique no botão Dados externos >, acesse a tab Conexões e clique em Criar conexão .

3. Na página Noções básicas de conexão do assistente de configuração de conexão , insira um nome de conexão fácil de usar.

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

5. (Opcional) Adicione um comentário.

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

   • (Opcional) Selecione Is sandbox .
   • ID do cliente : Consumidor do aplicativo conectado do Salesforce key.
   • Segredo do cliente: segredo do consumidor do aplicativo conectado à Salesforce.
   • Escopo do cliente : cdp_api api cdp_query_api refresh_token offline_access

7. Clique em Entrar com o Salesforce .

8. (OAuth) Será solicitado que o senhor faça login no Salesforce Data Cloud usando suas credenciais de SSO.

9. Após o login bem-sucedido, o senhor será direcionado de volta ao assistente de conexão do Databricks Set up. O botão Entrar com o Salesforce foi substituído por uma mensagem Successfully authorized.

10. Clique em Criar conexão .

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

12. Entre no espaço de dados do Salesforce.

13. (Opcional) Clique em Testar conexão para confirmar se está funcionando.

14. Clique em Criar catálogo .

15. Na página Access (Acesso) , selecione o espaço de trabalho no qual os usuários podem acessar o catálogo que o senhor criou. O senhor pode selecionar All workspace have access (Todos os espaços de trabalho têm acesso ) ou clicar em Assign to workspace (Atribuir ao espaço de trabalho), selecionar o espaço de trabalho e clicar em Assign (Atribuir ).

16. Altere o proprietário que poderá gerenciar o acesso a todos os objetos no catálogo. começar a digitar um diretor na caixa de texto e, em seguida, clicar no diretor nos resultados retornados.

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

    1. Especifique os diretores que terão acesso aos objetos no catálogo. começar a digitar um diretor na caixa de texto e, em seguida, clicar no diretor nos resultados retornados.

    2. Selecione as predefinições de privilégios a serem concedidas a cada diretor. Todos os usuários de account recebem BROWSE por default.

       • Selecione Leitor de dados no menu suspenso para conceder privilégios read em objetos no catálogo.
       • Selecione Editor de dados no menu suspenso para conceder os privilégios read e modify aos objetos no catálogo.
       • Selecione manualmente os privilégios a serem concedidos.

    3. Clique em Conceder .

18. Clique em Avançar .

19. Na página Metadata (Metadados ), especifique as tags em key-value. Para obter mais informações, consulte Apply tags to Unity Catalog securable objects.

20. (Opcional) Adicione um comentário.

21. Clique em Salvar .

SQL

A Databricks recomenda o uso do Catalog Explorer para criar a conexão e o catálogo externo porque ele exige menos etapas manuais do que outros métodos.

Se o senhor planeja usar o SQL para criar a conexão Databricks e o catálogo externo, seu Salesforce Connected App precisa oferecer suporte ao URI de redirecionamento https://login.salesforce.com/services/oauth2/success. Isso não é necessário se você usar o Catalog Explorer.

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

   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 o URL a seguir e autentique-se com suas credenciais do Salesforce para obter o authorization_code (substitua <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 está visível no URL redirecionado.

3. Execute o seguinte em um Notebook ou no editor de consultas Databricks SQL:

   SQL

   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"
     );

   Databricks recomenda que o senhor use Databricks segredos em vez de texto simples strings para valores confidenciais, como credenciais. Por exemplo:

   SQL

   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 a configuração de segredos, consulte Gerenciamento de segredos.

Crie um catálogo estrangeiro

nota

Se o senhor usar a interface do usuário para criar uma conexão com a fonte de dados, a criação do catálogo externo estará incluída e o senhor poderá ignorar essa etapa.

Um catálogo externo espelha um banco de dados em um sistema de dados externo para você consultar e gerenciar o acesso aos dados nesse banco de dados com Databricks e Unity Catalog. Para criar um catálogo externo, utiliza-se uma conexão com a fonte de dados que já foi definida.

Para criar um catálogo externo, o senhor pode usar o Catalog Explorer ou o comando CREATE FOREIGN CATALOG SQL em um Notebook Databricks ou o editor de consultas SQL. O senhor também pode usar a API REST da Databricks ou a CLI da Databricks para criar um catálogo. Veja POST /api/2.1/unity-catalog/catalogs e Unity Catalog comando.

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

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog para abrir o Catalog Explorer.

2. No canto superior direito, clique em Criar catálogo .

3. Insira as propriedades a seguir para seu catálogo do Salesforce Data Cloud.

   • Nome do catálogo : um nome fácil de usar 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.

SQL

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 suportados

Os seguintes pushdowns são suportados:

• Filtros
• Projeções
• Limite
• Agregados
• deslocamento
• Elenco
• Contém, começa com, termina com

Mapeamentos de tipos de dados

Quando o senhor lê do Salesforce Data Cloud para o Spark, os tipos de dados são mapeados da seguinte forma:

Tipo de nuvem de dados do Salesforce	Spark tipo
Booleana	Tipo booleano
Data	Tipo de data
Data e hora	timestampType
e-mail, telefone, texto, URL	Tipo de string
Número, Porcentagem	Tipo decimal (38, 18)

Limitações

• Só há suporte para um espaço de dados do Salesforce por catálogo do Databricks.
• No Databricks Runtime 16.1 e versões anteriores, não há suporte para nomes de tabelas e esquemas que diferenciam maiúsculas de minúsculas. Isso inclui nomes com letras maiúsculas no Salesforce Data Cloud. Por exemplo, MyTable não é suportado.

Recurso adicional

A lakehouse Federation não oferece suporte a conexões somente leitura com o Salesforce ventas Cloud, mas o LakeFlow Connect permite que o senhor ingira dados do Salesforce ventas Cloud em um Databricks lakehouse. Consulte Ingerir dados do Salesforce.