Exécuter des requêtes fédérées sur Salesforce Data Cloud

Article
10/15/2024

Cet article explique comment configurer Lakehouse Federation pour exécuter des requêtes fédérées sur des données Salesforce Data Cloud non gérées par Azure Databricks. Pour en savoir plus sur Lakehouse Federation, consultez l’article Qu’est-ce que Lakehouse Federation ?.

Pour vous connecter à votre base de données Salesforce Data Cloud à l’aide de Lakehouse Federation, vous devez créer les éléments suivants dans votre metastore Azure Databricks Unity Catalog :

Une connexion à votre base de données Salesforce Data Cloud.
Un catalogue étranger qui reflète votre base de données Salesforce Data Cloud dans Unity Catalog afin que vous puissiez utiliser la syntaxe de requête et les outils de gouvernance des données Unity Catalog pour gérer l’accès utilisateur Azure Databricks à la base de données.

Avant de commencer

Conditions requises pour l’espace de travail :

Espace de travail activé pour Unity Catalog.

Voici les exigences de calcul à respecter :

Connectivité réseau de votre cluster Databricks Runtime ou de votre entrepôt SQL aux systèmes de base de données cibles. Consultez l’article Recommandations de mise en réseau pour Lakehouse Federation.
Les clusters Azure Databricks doivent utiliser Databricks Runtime 15.2 ou version ultérieure et le mode d'accès partagé ou mono-utilisateur.
Les entrepôts SQL doivent être Pro ou Serverless et doivent utiliser la version 2024.30 ou ultérieure.

Autorisations requises :

Pour créer une connexion, vous devez être un administrateur de metastore ou un utilisateur disposant du privilège CREATE CONNECTION sur le metastore Unity Catalog attaché à l’espace de travail.
Pour créer un catalogue étranger, vous devez disposer de l’autorisation CREATE CATALOG sur le metastore et être le propriétaire de la connexion ou disposer du privilège CREATE FOREIGN CATALOG sur la connexion.

Des exigences d’autorisation supplémentaires sont spécifiées dans chaque section basée sur les tâches qui suit.

Créer une application connectée Salesforce

Les applications connectées Salesforce permettent à une application externe de s’intégrer à Salesforce à l’aide d’API et de protocoles standard. Cette section explique comment créer une application connectée à l’aide de l’authentification unique pour permettre à Databricks de s’authentifier auprès de Salesforce.

Remarque

Pour obtenir des instructions plus détaillées, consultez Créer une application connectée dans la documentation Salesforce Data Cloud.

Pour créer une application connectée Salesforce, suivez les étapes suivantes :

En haut à droite de Data Cloud, cliquez sur Configuration.
Sous Outils de plateforme, cliquez sur Apps >Gestionnaire d’apps.
Cliquez sur Nouvelle application connectée.
Entrez un nom et une adresse e-mail de contact.
Activez les paramètres OAuth :
1. Entrez l’URL de rappel, au format suivant : https://<databricks_instance_url>/login/oauth/salesforce.html. Par exemple : https://cust-success.cloud.databricks.com/login/oauth/salesforce.html.
2. (Facultatif) Si vous envisagez d’utiliser SQL pour créer la connexion Azure Databricks et le catalogue étranger à l’étape suivante, votre application connectée Salesforce doit également prendre en charge l’URL de redirection https://login.salesforce.com/services/oauth2/success. Cela n’est pas nécessaire si vous envisagez d’utiliser l’Explorateur de catalogues pour créer la connexion Azure Databricks et le catalogue étranger. Databricks recommande d’utiliser l’Explorateur de catalogues, car cela nécessite moins d’étapes manuelles que les autres méthodes.
3. Ajoutez les étendues suivantes :
  - Accéder à toutes les ressources de l’API Data Cloud (cdp_api)
  - Gérer les données utilisateur via des API (api)
  - Effectuer des requêtes ANSI SQL sur des données Data Cloud (cdp_query_api)
  - Effectuer des requêtes à tout moment (refresh_token, offline_access)
4. Cliquez sur Enregistrer.
5. Cliquez sur Continuer.
Dans la page Vue d’ensemble de l’application connectée , cliquez sur Gérer les détails du consommateur. Vous serez invité à vous authentifier.
Une fois l’authentification réussie, la clé consommateur et le secret consommateur sont révélés. Enregistrez ces valeurs. Vous en aurez besoin lors de la création d’une connexion Azure Databricks.

Créer une connexion Azure Databricks

Une connexion spécifie un chemin d’accès et des informations d’identification pour accéder à un système de base de données externe. Pour créer une connexion, vous pouvez utiliser l’Explorateur de catalogues ou la commande SQL CREATE CONNECTION dans un notebook Azure Databricks ou l’éditeur de requête SQL Databricks.

Remarque

Vous pouvez également utiliser l’API REST Databricks ou l’interface CLI Databricks pour créer une connexion. Consultez POST /api/2.1/unity-catalog/connections et Commandes Unity Catalog.

Autorisations requises : administrateur de metastore ou utilisateur disposant du privilège CREATE CONNECTION.

Explorateur de catalogues

Dans votre espace de travail Azure Databricks, cliquez sur Catalogue.
Dans le volet gauche, développez le menu Données externes, puis sélectionnez Connexions.
Cliquez sur Create connection (Créer la connexion).
Entrez un nom de connexion convivial.
Sélectionnez un type de connexion de Salesforce Data Cloud.
Entrez les propriétés de connexion suivantes pour votre Salesforce Data Cloud.
- Type d’authentification : OAuth
- Bac à sable false
- (OAuth) Secret client : secret consommateur de l’application connectée Salesforce
- (OAuth) ID client : clé consommateur de l’application connectée Salesforce
- (OAuth) Étendue client : cdp_api api cdp_query_api refresh_token offline_access
Cliquez sur Connexion avec Salesforce.
(OAuth) Vous êtes invité à vous connecter à Salesforce Data Cloud à l’aide de vos informations d’identification SSO.
Une fois la connexion réussie, vous êtes redirigé vers la page Databricks Créer une connexion. Le bouton Connexion avec Salesforce a été remplacé par un message Successfully authorized.
(Facultatif) Ajoutez un commentaire.
Cliquez sur Créer.

SQL

Databricks recommande d’utiliser l’Explorateur de catalogues pour créer la connexion et le catalogue étranger, car cela nécessite moins d’étapes manuelles que les autres méthodes.

Si vous envisagez d’utiliser SQL pour créer la connexion Azure Databricks et le catalogue étranger, votre application connectée Salesforce doit prendre en charge l’URL de redirection https://login.salesforce.com/services/oauth2/success. Cela n’est pas nécessaire si vous utilisez l’Explorateur de catalogues.

Générer des codes de vérificateur de code et de test de code PKCE. Pour ce faire, vous pouvez utiliser un outil en ligne tel que https://tonyxu-io.github.io/pkce-generator/, ou exécuter le script Python suivant :

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

Visitez l’URL suivante et authentifiez-vous avec vos informations d’identification Salesforce pour obtenir le authorization_code (remplacez <client_id> et <code_challenge> par vos paramètres).
```
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 code d’autorisation codé en URL est visible dans l’URL redirigée.

Exécutez ce qui suit dans un notebook ou dans l’éditeur de requête SQL 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 vous recommande d’utiliser des secrets Azure Databricks au lieu de chaînes de texte en clair pour les valeurs sensibles telles que les informations d’identification. Par exemple :

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

Pour obtenir des informations sur la configuration des secrets, consultez l’article Gestion des secrets.

Créer un catalogue étranger

Un catalogue étranger reflète une base de données dans un système de données externe afin que vous puissiez interroger et gérer l’accès aux données de cette base de données à l’aide d’Azure Databricks et Unity Catalog. Pour créer un catalogue étranger, vous utilisez une connexion à la source de données qui a déjà été définie.

Pour créer un catalogue étranger, vous pouvez utiliser Catalog Explorer ou la commande SQL CREATE FOREIGN CATALOG dans un notebook Azure Databricks ou dans l’Éditeur de requête SQL.

Remarque

Vous pouvez également utiliser l’API REST Databricks ou l’interface CLI Databricks pour créer un catalogue. Consultez POST /api/2.1/unity-catalog/catalogs et les commandes du catalogue Unity.

Autorisations requises : autorisation CREATE CATALOG sur le metastore, et être propriétaire de la connexion ou disposer du privilège CREATE FOREIGN CATALOG sur la connexion.

Explorateur de catalogues

Dans votre espace de travail Azure Databricks, cliquez sur Catalogue pour ouvrir l’Explorateur de catalogue.
En haut à droite, cliquez sur Créer un catalogue.
Entrez les propriétés suivantes pour votre catalogue Salesforce Data Cloud.
- Nom du catalogue : un nom convivial pour le catalogue.
- Type :Foreign.
- Nom de la connexion : le nom de la connexion sur laquelle le catalogue sera créé.
- Dataspace : un espace de données Salesforce.
Cliquez sur Créer.

SQL

Exécutez la commande SQL suivante dans un notebook ou dans l’Éditeur de requête SQL. Les éléments entre chevrons sont optionnels.

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

Remplacez les valeurs suivantes :

<catalog-name>:
<connection-name>:
<dataspace> : espace de données Salesforce. Par exemple : default.

Pushdowns pris en charge

Les pushdowns suivants sont pris en charge :

Filtres
Projections
Limite
Agrégats
Contrepartie
Cast
Contains, Startswith, Endswith

Mappages de types de données

Quand vous lisez de Salesforce Data Cloud vers Spark, les types de données sont mappés comme suit :

Type de Salesforce Data Cloud	Type Spark
Boolean	BooleanType
Date	DateType
Datetime	TimestampType
E-mail, téléphone, texte, URL	StringType
Nombre, pourcentage	DecimalType(38, 18)

Limites

Un seul espace de données Salesforce par catalogue Databricks est pris en charge.

Partager via

Exécuter des requêtes fédérées sur Salesforce Data Cloud

Avant de commencer

Créer une application connectée Salesforce

Créer une connexion Azure Databricks

Explorateur de catalogues

SQL

Créer un catalogue étranger

Explorateur de catalogues

SQL

Pushdowns pris en charge

Mappages de types de données

Limites

Commentaires

Ressources supplémentaires