Executar consultas federadas no Salesforce Data Cloud

Artigo
12/04/2024

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

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

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 Unity Catalog para que você possa usar a sintaxe de consulta do Catálogo 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 espaço de trabalho:

Espaço de trabalho habilitado para o Catálogo Unity.

Requisitos de computação:

Conectividade de rede do seu recurso de computação para os sistemas de banco de dados de destino. Consulte Recomendações de rede para a Lakehouse Federation.
A computação do Azure Databricks deve usar o Databricks Runtime 15.2 ou superior e modo de acesso partilhado ou para utilizador único.
Os armazéns SQL 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 CREATE CONNECTION privilégio no metastore do Unity Catalog anexado ao espaço de trabalho.
Para criar um catálogo estrangeiro, você deve ter a CREATE CATALOG permissão no metastore e ser o proprietário da conexão ou ter o CREATE FOREIGN CATALOG privilégio na conexão.

Os requisitos de permissão adicionais são especificados em cada seção baseada em tarefas a seguir.

Criar 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 com o 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:

No canto superior direito do Data Cloud, clique em Configuração.
Em Ferramentas de Plataforma, clique em Apps > App Manager.
Clique em Novo aplicativo conectado.
Introduza um Nome e um endereço de e-mail de Contacto.
Habilite 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 você planeja usar o SQL para criar a conexão do Azure Databricks e o catálogo estrangeiro na próxima etapa, seu Salesforce Connected App também precisa dar suporte ao URI https://login.salesforce.com/services/oauth2/successde redirecionamento. Isso não é necessário se você planeja usar o Gerenciador de Catálogos para criar a conexão do Azure Databricks e o catálogo estrangeiro. O Databricks recomenda o uso do Catalog Explorer porque ele requer menos etapas manuais do que outros métodos.
3. Adicione os seguintes escopos:
  - Acesse todos os recursos da API do Data Cloud (cdp_api)
  - Gerencie dados do usuário por meio de APIs (api)
  - Executar consultas ANSI SQL em dados do Data Cloud (cdp_query_api)
  - Executar solicitações a qualquer momento (refresh_token, offline_access)
4. Clique em Guardar.
5. Clique em Continue (Continuar).
Na página de visão geral do Aplicativo Conectado, clique em Gerenciar Detalhes do Consumidor. Você será solicitado a autenticar.
Após a autenticação bem-sucedida, a chave do consumidor e o segredo do consumidor são revelados. Guarde estes valores. Você precisará deles quando 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 Gerenciador de Catálogos ou o CREATE CONNECTION comando SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL.

Nota

Você também pode usar a API REST do Databricks ou a CLI do Databricks para criar uma conexão. Consulte os comandos POST /api/2.1/unity-catalog/connections e Unity Catalog.

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

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Dados Externos e selecione Conexões.
Clique em Criar conexão.
Insira um nome de conexão amigável.
Selecione um tipo de conexão do Salesforce Data Cloud.
Insira as seguintes propriedades de conexão para seu Salesforce Data Cloud.
- Tipo de autenticação: OAuth
- É sandboxfalse
- (OAuth) Segredo do cliente: segredo do consumidor do aplicativo conectado ao Salesforce
- (OAuth) ID do cliente: chave do consumidor do aplicativo conectado ao Salesforce
- (OAuth) Âmbito do cliente: cdp_api api cdp_query_api refresh_token offline_access
Clique em Fazer login com o Salesforce.
(OAuth) Você será solicitado a fazer login no Salesforce Data Cloud usando suas credenciais de SSO.
Após o login bem-sucedido, você será direcionado de volta para a página Criar conexão do Databricks. O botão Fazer login com o Salesforce foi substituído por uma Successfully authorized mensagem.
(Opcional) Adicione um comentário.
Clique em Criar.

SQL

O Databricks recomenda o uso do Catalog Explorer para criar a conexão e o catálogo estrangeiro porque ele 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 Salesforce Connected App precisa dar suporte ao URI https://login.salesforce.com/services/oauth2/successde redirecionamento. Isso não é necessário se você usar o Gerenciador de Catálogos.

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

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}\"")

Visite o URL a seguir e autentique-se com suas credenciais do Salesforce para obter o authorization_code (substituir <client_id> e <code_challenge> com 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 por URL é visível no URL redirecionado.

Execute o seguinte em um bloco de anotações ou no editor de consultas Databricks 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"
  );

O Databricks recomenda que você use segredos do Azure Databricks em vez de cadeias de caracteres de texto sem formatação 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 como configurar segredos, consulte Gerenciamento 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 Unity Catalog. 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 Gerenciador de Catálogos ou o CREATE FOREIGN CATALOG comando SQL em um bloco de anotações do Azure Databricks ou no editor de consultas SQL.

Nota

Você também pode usar a API REST do Databricks ou a CLI do Databricks para criar um catálogo. Consulte POST /api/2.1/unity-catalog/catalogs e comandos do Unity Catalog.

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

Explorador de Catálogos

No espaço de trabalho do Azure Databricks, clique em Catálogo para abrir o Gerenciador de Catálogos.
No canto superior direito, clique em Criar catálogo.
Insira as seguintes propriedades para seu 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.
- Dataspace: um espaço de dados do Salesforce.
Clique em Criar.

SQL

Execute o seguinte comando SQL em um bloco de anotações ou no editor de consultas SQL. Os itens entre parênteses 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 suportados

As seguintes flexões são suportadas:

Filtros
Projeções
Limite
Agregados
Desvio
Cost
Contém, Começa, Termina com

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:

Tipo de Salesforce Data Cloud	Tipo de faísca
Boolean	BooleanType
Date	Tipo de Data
Datetime	Tipo de carimbo de data/hora
Email, Telefone, Texto, Url	StringType
Número, Percentagem	Tipo decimal(38, 18)

Limitações

Apenas um Salesforce Data Space por catálogo Databricks é suportado.

Recursos adicionais

O Lakehouse Federation não oferece suporte conexões somente leitura ao Salesforce Sales Cloud, mas o LakeFlow Connect permite que você ingira dados do Salesforce Sales Cloud em um lago Databricks. Consulte Ingestão de dados do Salesforce.

Partilhar via

Executar consultas federadas no Salesforce Data Cloud

Antes de começar

Criar um aplicativo conectado ao Salesforce

Criar uma conexão do Azure Databricks

Explorador de Catálogos

SQL

Criar um catálogo estrangeiro

Explorador de Catálogos

SQL

Pushdowns suportados

Mapeamentos de tipo de dados

Limitações

Recursos adicionais

Comentários

Recursos adicionais