Aller au contenu principal
Dernière mise à jour le

Se connecter au pool dédié Azure Synapse Analytics

info

Expérimental

La documentation sur la fédération des query héritées a été retirée et pourrait ne pas être mise à jour. Les configurations mentionnées dans ce contenu ne sont ni officiellement approuvées ni testées par Databricks. Si la Lakehouse Federation prend en charge votre base de données source, Databricks recommande d'utiliser cette dernière.

Ce tutoriel vous guide à travers toutes les étapes nécessaires pour vous connecter d'Azure Databricks à un pool dédié Azure Synapse Analytics en utilisant un Service Principal, Azure Managed Service Identity (MSI) et l'authentification SQL. Le connecteur Azure Synapse utilise trois types de connexions réseau :

  • Driver Spark vers Azure Synapse
  • Driver et exécuteurs Spark vers le compte de stockage Azure
  • Compte de stockage Azure Synapse vers Azure

Connecteur Azure Synapse

Exigences​

Effectuez ces tâches avant de commencer le tutoriel :

Connectez-vous à Azure Synapse Analytics à l'aide d'un Service Principal​

Les étapes suivantes de ce tutoriel vous montrent comment vous connecter à Azure Synapse Analytics à l'aide d'un Service Principal.

Étape 1 : Créer un Service Principal Microsoft Entra ID pour l'Azure Data Lake Storage​

Pour utiliser les Service Principals pour se connecter à Azure Data Lake Gen2, un utilisateur administrateur doit créer une nouvelle application Microsoft Entra ID (anciennement connue sous le nom d'Azure Active Directory). Si vous avez déjà un Service Principal Microsoft Entra ID disponible, passez à l' étape 3 . Pour créer un Service Principal Microsoft Entra ID, suivez ces instructions :

  1. Connectez-vous au portail Azure.
  2. Si vous avez accès à plusieurs tenants, abonnements ou répertoires, cliquez sur l'icône Répertoires + abonnements (répertoire avec filtre) dans le menu supérieur pour passer au répertoire dans lequel vous souhaitez provisionner le Service Principal.
  3. Recherchez et sélectionnez Microsoft Entra ID .
  4. Dans Gérer , cliquez sur Enregistrements d'applications > Nouvel enregistrement .
  5. Pour Nom , saisissez le nom de l'application.
  6. Dans la section Types de compte pris en charge , sélectionnez Comptes dans ce répertoire d'organisation uniquement (Single tenant) .
  7. Cliquez sur S'INSCRIRE .

(Facultatif) Étape 2 : Créer un Service Principal Microsoft Entra ID pour Azure Synapse Analytics​

Vous pouvez éventuellement créer un service principal dédié à Azure Synapse Analytics en répétant les instructions de l’étape 1. Si vous ne créez pas un ensemble distinct d’identifiants de service principal, la connexion utilisera le même service principal pour se connecter à Azure Data Lake Gen2 et à Azure Synapse Analytics.

Étape 3 : Créez un secret client pour vos principaux de service Azure Data Lake Gen2 (et Azure Synapse Analytics)​

  1. Dans Gérer , cliquez sur Certificats et secrets
  2. Dans l'onglet **Secrets client**, cliquez sur **Nouveau secret client**.
  3. Dans le volet Ajouter un secret client , pour Description , saisissez une description pour le secret client.
  4. Pour Expire le , sélectionnez une période d’expiration pour le secret client, puis cliquez sur Ajouter .
  5. Copiez et stockez la Valeur du secret client dans un endroit sûr, car ce secret client est le mot de passe de votre application.
  6. Sur la page Vue d'ensemble de l'application, dans la section Essentiels , copiez les valeurs suivantes :
    • ID de l'application (client)
    • ID du répertoire (tenant)
remarque

Si vous avez créé un ensemble d'informations d'identification de Service Principal pour Azure Synapse Analytics, suivez à nouveau les étapes pour créer un secret client.

Étape 4 : Accorder l'accès du Service Principal à Azure Data Lake Storage​

Vous accordez l'accès aux Ressources de stockage en attribuant des rôles à votre Service Principal. Dans ce tutoriel, vous attribuez le rôle Storage Blob Data Contributor au ou aux Service Principal de votre compte Azure Data Lake Storage. Vous devrez peut-être attribuer d'autres rôles en fonction des exigences spécifiques.

  1. Dans le portail Azure, accédez au service Comptes de stockage .
  2. Sélectionnez un compte de stockage Azure à utiliser.
  3. Cliquez sur Accès conditionnel (IAM) .
  4. Cliquez sur **+ Ajouter** et sélectionnez **Ajouter une attribution de rôle** dans le menu déroulant.
  5. Définissez le champ **Sélectionner** sur le nom de l'application Microsoft Entra ID que vous avez créé à l'étape 1 et définissez le rôle sur **Storage Blob Data Contributor**.
  6. Cliquez sur Enregistrer .
remarque

Si vous avez créé un ensemble d'informations d'identification Service Principal pour Azure Synapse Analytics, suivez à nouveau les étapes pour accorder l'accès au Service Principal sur Azure Data Lake Storage.

Étape 5 : Créer une clé principale dans le pool dédié Azure Synapse Analytics​

Connectez-vous au pool dédié Azure Synapse Analytics et créez une clé principale si vous ne l'avez pas déjà fait.

SQL
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>'

Étape 6 : Accorder des autorisations au Service Principal dans le Pool dédié Azure Synapse Analytics​

Connectez-vous au pool dédié Azure Synapse Analytics et créez un utilisateur externe pour le service principal qui va se connecter à Azure Synapse Analytics :

SQL
CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER
remarque

Le nom du Service Principal doit correspondre à celui créé à l'Étape 2 (ou à l'Étape 1 si vous avez ignoré la création d'un Service Principal dédié pour Azure Synapse Analytics).

Accordez les autorisations au Service Principal pour être un db_owner en exécutant la commande ci-dessous :

SQL
sp_addrolemember 'db_owner', '<serviceprincipal>'

Accordez les autorisations requises pour pouvoir insérer dans une table existante :

SQL
GRANT ADMINISTER DATABASE BULK OPERATIONS TO <serviceprincipal>
GRANT INSERT TO <serviceprincipal>

(Facultatif) Accorder les autorisations requises pour pouvoir insérer dans une nouvelle table :

SQL
GRANT CREATE TABLE TO <serviceprincipal>
GRANT ALTER ON SCHEMA ::dbo TO <serviceprincipal>

Étape 7 : Exemple de syntaxe : query et écriture de données dans Azure Synapse Analytics​

Vous pouvez interroger Synapse en Scala, Python, SQL et R. Les exemples de code suivants utilisent des clés de compte de stockage et transmettent les informations d'identification de stockage d'Azure Databricks à Synapse.

Les exemples de code suivants vous montrent comment :

  • Définir la clé d'accès du compte de stockage dans la session du Notebook
  • Définir les identifiants du Service Principal pour le compte de stockage Azure
  • Définissez un ensemble distinct d'identifiants de Service Principal pour Azure Synapse Analytics (Si non défini, le connecteur utilisera les identifiants du compte de stockage Azure)
  • Obtenez des données d'une table Azure Synapse
  • Chargez des données à partir d'une query Azure Synapse
  • Appliquer des transformations aux données, puis utiliser l'API de source de données pour réécrire les données dans une autre table dans Azure Synapse.
Scala
  import org.apache.spark.sql.DataFrame

// Set up the storage account access key in the notebook session
conf.spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Define the service principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<ApplicationId>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<SecretValue>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<DirectoryId>/oauth2/token")

// Define a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<ApplicationId>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<SecretValue>")

// Get some data from an Azure Synapse table
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("enableServicePrincipalAuth", "true")
  .option("dbTable", "dbo.<your-table-name>")
  .load()

// Load data from an Azure Synapse query
val df1: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("enableServicePrincipalAuth", "true")
  .option("query", "select * from dbo.<your-table-name>")
  .load()

// Apply some transformations to the data, then use the
// Data Source API to write the data back to another table in Azure Synapse
df1.write
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("enableServicePrincipalAuth", "true")
  .option("dbTable", "dbo.<new-table-name>")
  .save()

Dépannage​

Les sections suivantes abordent les messages d'erreur que vous pouvez rencontrer et leurs significations possibles.

L'identifiant du Service principal n'existe pas en tant qu'utilisateur.​

com.microsoft.sqlserver.jdbc.SQLServerException: Login failed for user '<token-identified principal>'

L'erreur précédente signifie probablement que les informations d'identification du Service Principal n'existent pas en tant qu'utilisateur dans le workspace Synapse analytique.

Exécutez la commande suivante dans le pool dédié Azure Synapse Analytics pour créer un utilisateur externe :

SQL
CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER

Les autorisations SELECT du Service Principal sont insuffisantes​

com.microsoft.sqlserver.jdbc.SQLServerException: The SELECT permission was denied on the object 'TableName', database 'PoolName', schema 'SchemaName'. [ErrorCode = 229] [SQLState = S0005]

L'erreur précédente signifie probablement que les informations d'identification du service principal n'ont pas suffisamment de permissions SELECT dans le pool dédié Azure Synapse Analytics.

Exécutez la commande suivante dans le pool dédié Azure Synapse Analytics pour accorder les autorisations SELECT :

SQL
GRANT SELECT TO <serviceprincipal>

Les informations d'identification du Service Principal ne disposent pas des autorisations d'utilisation COPY​

com.microsoft.sqlserver.jdbc.SQLServerException: User does not have permission to perform this action. [ErrorCode = 15247] [SQLState = S0001]

L'erreur précédente signifie probablement que les identifiants du service principal ne disposent pas des autorisations suffisantes dans le pool dédié Azure Synapse Analytics pour utiliser COPY. Le service principal nécessite des autorisations différentes selon l'opération (insérer dans une table existante ou insérer dans une nouvelle table). Assurez-vous que le service principal dispose des autorisations Azure Synapse requises.

remarque

Le service principal n'est pas un db_owner du pool dédié Azure Synapse Analytics.

Exécutez la commande suivante dans le pool dédié Azure Synapse Analytics pour accorder les autorisations db_owner :

SQL
sp_addrolemember 'db_owner', 'serviceprincipal'

Pas de clé principale dans le pool dédié​

com.microsoft.sqlserver.jdbc.SQLServerException: Please create a master key in the database or open the master key in the session before performing this operation. [ErrorCode = 15581] [SQLState = S0006]

L'erreur précédente signifie probablement qu'il n'y a pas de clé principale dans le Pool dédié Azure Synapse Analytics.

Créez une clé principale dans Azure Synapse Analytics pour résoudre ce problème.

Les informations d'identification du Service Principal disposent d'autorisations d'écriture insuffisantes​

com.microsoft.sqlserver.jdbc.SQLServerException: CREATE EXTERNAL TABLE AS SELECT statement failed as the path name '' could not be used for export. Please ensure that the specified path is a directory which exists or can be created, and that files can be created in that directory. [ErrorCode = 105005] [SQLState = S0001]

L'erreur précédente signifie probablement que :

Sur cette page