Eseguire query federate in Salesforce Data Cloud

Articolo
09/25/2024

Questo articolo descrive come configurare Lakehouse Federation di Azure Databricks per eseguire query federate sui dati di Salesforce Data Cloud non gestiti da Azure Databricks. Per altre informazioni sulla federazione di lakehouse, si veda Che cos'è Lakehouse Federation?.

Per connettersi al database Salesforce Data Cloud usando Lakehouse Federation, è necessario creare quanto segue nel metastore del catalogo Unity di Azure Databricks:

Connessione al database Salesforce Data Cloud.
Catalogo esterno che rispecchia il database di Salesforce Data Cloud nel catalogo Unity, in modo da poter utilizzare la sintassi delle query del catalogo Unity e gli strumenti di governance dei dati per gestire l'accesso degli utenti di Azure Databricks al database.

Operazioni preliminari

Requisiti dell'area di lavoro:

Area di lavoro abilitata per il catalogo Unity

Requisiti dell’ambiente di calcolo:

Connettività di rete dal cluster Databricks Runtime o dal warehouse SQL ai sistemi di database di destinazione. Si veda Raccomandazioni di rete per Lakehouse Federation.
I cluster di Azure Databricks devono usare Databricks Runtime 15.2 o versione successiva e la modalità di accesso condiviso o utente singolo.
I warehouse SQL devono essere Pro o Serverless e devono usare la versione 2024.30 o successive.

Autorizzazioni necessarie:

Per creare una connessione, è necessario essere un amministratore del metastore o un utente con il privilegio CREATE CONNECTIONper il metastore del catalogo Unity collegato all'area di lavoro.
Per creare un catalogo esterno, è necessario disporre dell'autorizzazione CREATE CATALOG per il metastore e essere il proprietario della connessione o avere il privilegio CREATE FOREIGN CATALOG per la connessione.

In ogni sezione basata su attività che segue vengono specificati requisiti di autorizzazione aggiuntivi.

Creare un'app connessa a Salesforce

Le app connesse a Salesforce consentono a un'applicazione esterna di integrarsi con Salesforce usando API e protocolli standard. Questa sezione descrive come creare un'app connessa usando SSO per consentire a Databricks di eseguire l'autenticazione con Salesforce.

Nota

Per istruzioni più dettagliate, si veda Creare un'app connessa nella documentazione di Salesforce Data Cloud.

Per creare un'app connessa a Salesforce, eseguire le seguenti operazioni:

In alto a destra di Data Cloud fare clic su Configura.
In Strumenti piattaforma fare clic su Gestione app>.
Fare clic su Nuova app connessa.
Immettere un nome e un indirizzo di posta elettronica del contatto.
Abilitare le impostazioni di OAuth:
1. Immettere URL di callback nel seguente formato: https://<databricks_instance_url>/login/oauth/salesforce.html. Ad esempio: https://cust-success.cloud.databricks.com/login/oauth/salesforce.html.
2. (Facoltativo) Se si prevede di usare SQL per creare la connessione di Azure Databricks e il catalogo esterno nel passaggio successivo, l'app connessa Salesforce deve anche supportare l'URI https://login.salesforce.com/services/oauth2/successdi reindirizzamento . Questa operazione non è necessaria se si prevede di usare Esplora cataloghi per creare la connessione di Azure Databricks e il catalogo esterno. Databricks raccomanda di usare Esplora cataloghi perché richiede meno passaggi manuali rispetto ad altri metodi.
3. Aggiungere i seguenti Ambiti:
  - Accedere a tutte le risorse dell'API Data Cloud (cdp_api)
  - Gestire i dati utente tramite le API (API)
  - Eseguire query SQL ANSI sui dati di Data Cloud (cdp_query_api)
  - Eseguire richieste in qualsiasi momento (refresh_token, offline_access)
4. Fare clic su Salva.
5. Fare clic su Continua.
Nella pagina di panoramica dell'app connessa fare clic su Gestisci dettagli consumer. Verrà richiesto di eseguire l'autenticazione.
Al termine dell'autenticazione, vengono rivelati la chiave consumer e il segreto consumer. Salvare questi valori. Saranno necessari quando si crea una connessione di Azure Databricks.

Creare una connessione Azure Databricks.

Una connessione specifica un percorso e le credenziali per accedere a un sistema di database esterno. Per creare una connessione, è possibile usare Esplora cataloghi o il comando SQL CREATE CONNECTION in un notebook di Azure Databricks o nell'editor di query SQL di Databricks.

Nota

È anche possibile usare l'API REST di Databricks o l'interfaccia della riga di comando di Databricks per creare una connessione. Vedere Comandi POST /api/2.1/unity-catalog/connections e catalogo Unity.

Autorizzazioni necessarie: amministratore o utente metastore con il privilegio CREATE CONNECTION.

Esplora cataloghi

Nell'area di lavoro di Azure Databricks fare clic su Catalogo.
Nel riquadro di sinistra, espandere il menu Dati esterni e selezionare Connessioni.
Fare clic su Crea connessione.
Immettere un nome di connessione semplice.
Selezionare un tipo di connessione di Salesforce Data Cloud.
Immettere le seguenti proprietà di connessione per Salesforce Data Cloud.
- Auth-type: OAuth
- sandbox false
- (OAuth) Segreto client: segreto consumer dell'app connessa Salesforce
- (OAuth) ID client: chiave consumer dell'app connessa Salesforce
- (OAuth) Ambito client: cdp_api api cdp_query_api refresh_token offline_access
Fare clic su Accedi con Salesforce.
(OAuth) Viene richiesto di accedere a Salesforce Data Cloud usando le credenziali SSO.
Al termine dell'accesso, si torna alla pagina Databricks Crea connessione. Il pulsante Accedi con Salesforce è stato sostituito con un messaggio Successfully authorized.
(Facoltativo) Aggiungere un commento.
Cliccare su Crea.

SQL

Databricks consiglia di utilizzare Esplora cataloghi per creare la connessione e il catalogo estero, perché richiede meno passaggi manuali rispetto ad altri metodi.

Se si prevede di usare SQL per creare la connessione di Azure Databricks e il catalogo esterno, l'app connessa Salesforce deve supportare l'URI https://login.salesforce.com/services/oauth2/successdi reindirizzamento . Questa operazione non è necessaria se si usa Esplora cataloghi.

Generare il verificatore del codice PKCE e i codici di verifica del codice. A tale scopo, è possibile usare uno strumento online, ad esempio https://tonyxu-io.github.io/pkce-generator/, o eseguire il seguente 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}\"")

Visitare l'URL seguente ed eseguire l'autenticazione con le credenziali di Salesforce per ottenere authorization_code (sostituire <client_id> e <code_challenge> con i parametri).
```
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>
```
Un codice di autorizzazione con codifica URL è visibile nell'URL reindirizzato.

Eseguire quanto segue in un notebook o nell'editor di query SQL di 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"
  );

Databricks consiglia di usare segreti di Azure Databricks anziché stringhe di testo non crittografato per valori sensibili come le credenziali. Ad esempio:

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

Per informazioni sulla configurazione dei segreti, vedere Gestione dei segreti.

Creare un catalogo esterno

Un catalogo esterno esegue il mirroring di un database in un sistema di dati esterno in modo da poter eseguire query e gestire l'accesso ai dati in tale database usando Azure Databricks e catalogo Unity. Per creare un catalogo esterno, usare una connessione all'origine dati già definita.

Per creare un catalogo esterno, è possibile usare Esplora cataloghi o il comando SQL CREATE FOREIGN CATALOG in un notebook di Azure Databricks o nell'editor di query SQL.

Nota

È anche possibile usare l'API REST di Databricks o l'interfaccia della riga di comando di Databricks per creare un catalogo. Vedere Comandi POST /api/2.1/unity-catalog/catalogs e catalogo Unity.

Autorizzazioni necessarie: autorizzazione CREATE CATALOG per il metastore e la proprietà della connessione o il privilegio CREATE FOREIGN CATALOG per la connessione.

Esplora cataloghi

Nell'area di lavoro di Azure Databricks fare clic su Catalogo per aprire Esplora cataloghi.
In alto a destra fare clic su Crea catalogo.
Immettere le seguenti proprietà per il catalogo Salesforce Data Cloud.
- Nome catalogo: nome descrittivo per il catalogo.
- Tipo: Foreign.
- Nome connessione: nome della connessione in cui verrà creato il catalogo.
- Dataspace: spazio dati Salesforce.
Cliccare su Crea.

SQL

Eseguire il seguente comando SQL in un notebook o nell'editor di query SQL. Gli elementi tra parentesi sono facoltativi.

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

Sostituire i valori seguenti:

<catalog-name>:
<connection-name>:
<dataspace>: spazio dati salesforce. Ad esempio: default.

Pushdown supportati

Sono supportati i seguenti pushdown:

Filtri
Proiezioni
Limite
Aggregazioni
Contropartita
Cast
Contains, Startswith, Endswith

Mapping di tipi di dati

Quando si legge da Salesforce Data Cloud a Spark, i tipi di dati vengono mappati nel seguente modo:

Tipo Data Cloud di Salesforce	Tipo Spark
Booleano	BooleanType
Data	DateType
Datetime	TimestampType
Posta elettronica, Telefono, Testo, URL	StringType
Numero, Percentuale	DecimalType(38, 18)

Limiti

È supportato un solo catalogo di Salesforce Data Space per Databricks.

Condividi tramite

Eseguire query federate in Salesforce Data Cloud

Operazioni preliminari

Creare un'app connessa a Salesforce

Creare una connessione Azure Databricks.

Esplora cataloghi

SQL

Creare un catalogo esterno

Esplora cataloghi

SQL

Pushdown supportati

Mapping di tipi di dati

Limiti

Commenti e suggerimenti

Risorse aggiuntive