Executar consultas federadas no Salesforce Data Cloud

Este artigo descreve como configurar a Federação de Lakehouse para executar consultas federadas em dados do Salesforce Data Cloud que não são gerenciados pelo Azure Databricks. Para saber mais sobre a Federação do Lakehouse, consulte O que é a Federação do Lakehouse?.

Para se conectar ao seu banco de dados do Salesforce Data Cloud usando a Federação de Lakehouse, você deve criar o seguinte no metastore do Catálogo do Unity do Azure Databricks:

• Uma conexão com seu banco de dados do Salesforce Data Cloud.
• Um catálogo estrangeiro que espelha seu banco de dados do Salesforce Data Cloud 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.

Antes de começar

Requisitos do workspace:

• Workspace habilitado para o Catálogo do Unity.

Requisitos de computação:

• Conectividade de rede do cluster do Databricks Runtime ou do Warehouse SQL para os sistemas de banco de dados de destino. Confira Recomendações de rede para a Federação de Lakehouse.
• Os clusters do Azure Databricks precisam usar o Databricks Runtime 15.2 ou superior e o modo de acesso compartilhado ou de usuário único.
• Os SQL warehouses devem ser Pro 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ê deve 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 Cloud, 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 Explorador de Catálogos 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 Cloud (cdp_api)
      • Gerenciar dados do usuário por meio de APIs (api)
      • Executar consultas SQL ANSI em dados do Data Cloud (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 ou usuário do metastore com o privilégio de CREATE CONNECTION.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.
2. No painel esquerdo, expanda o menu Dados Externos e selecione Conexões.
3. Clique em Criar conexão.
4. Insira um nome de conexão simples.
5. Selecione um Tipo de conexão do Salesforce Data Cloud.
6. Insira as propriedades de conexão a seguir para o Salesforce Data Cloud.
   • Tipo de autenticação: OAuth
   • É área restrita false
   • (OAuth) Segredo do cliente: segredo do consumidor do aplicativo conectado do Salesforce
   • (OAuth) ID do cliente: chave do consumidor do aplicativo conectado do Salesforce
   • (OAuth) Escopo do cliente: cdp_api api cdp_query_api refresh_token offline_access
7. Clique em Fazer logon com o Salesforce.
8. (OAuth) Você será solicitado a entrar no Salesforce Data Cloud usando suas credenciais de SSO.
9. Após um logon bem-sucedido, você será direcionado de volta para a página do Databricks Criar Conexão. O botão Fazer logon com o Salesforce foi substituído por uma mensagem Successfully authorized.
10. (Opcional) Adicione um comentário.
11. Clique em Criar.

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 Explorador de Catálogos.

1. Gere 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.

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

Explorador do Catálogo

1. Em seu workspace do Azure Databricks, clique em Catálogo para abrir o Explorador de Catálogo.
2. No canto superior direito, clique em Criar catálogo.
3. Insira as propriedades a seguir para o catálogo do Salesforce Data Cloud.
   • 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
• Converter
• Contains, Startswith, Endswith

Mapeamentos de tipo de dados

Quando você lê do Salesforce Data Cloud 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.