Introduction aux API de montage/démontage de fichiers dans Azure Synapse Analytics

L’équipe Azure Synapse Studio a créé deux nouvelles API de montage/démontage dans le package Microsoft Spark Utilities (mssparkutils). Vous pouvez utiliser ces API pour attacher un stockage distant (Stockage Blob Azure ou Azure Data Lake Storage Gen2) à tous les nœuds de travail (nœud pilote et nœuds Worker). Une fois le stockage en place, vous pouvez utiliser l’API de fichier local pour accéder aux données comme s’il est stocké dans le système de fichiers local. Pour plus d’informations, consultez Présentation des utilitaires Microsoft Spark.

L’article vous montre comment utiliser des API de montage/démontage dans votre espace de travail. Vous apprendrez ce qui suit :

• Comment monter Data Lake Storage Gen2 ou Stockage Blob.
• Comment accéder aux fichiers sous le point de montage via l’API de système de fichiers local.
• Comment accéder aux fichiers sous le point de montage à l’aide de l’API mssparktuils fs.
• Comment accéder aux fichiers sous le point de montage à l’aide de l’API de lecture Spark.
• Comment démonter le point de montage.

Avertissement

Le montage du partage de fichiers Azure est temporairement désactivé. Vous pouvez utiliser le montage Data Lake Storage Gen2 ou Stockage Blob Azure à la place, comme décrit dans la section suivante.

Le stockage Azure Data Lake Storage Gen1 n’est pas pris en charge. Vous pouvez migrer vers Data Lake Storage Gen2 en suivant les instructions de migration Azure Data Lake Storage Gen1 vers Gen2 avant d’utiliser les API de montage.

Monter le stockage

Cette section montre comment monter Data Lake Storage Gen2 étape par étape en tant qu’exemple. Le montage de Stockage Blob fonctionne de la même façon.

L’exemple suppose que vous avez un compte Data Lake Storage Gen2 nommé storegen2. Le compte a un conteneur nommé mycontainer sur lequel vous souhaitez monter /test dans votre pool Spark.

Pour monter le conteneur appelé mycontainer, mssparkutils doit d’abord vérifier si vous disposez de l’autorisation d’accéder au conteneur. Actuellement, Azure Synapse Analytics prend en charge trois méthodes d’authentification pour l’opération de montage du déclencheur : linkedService, accountKeyet sastoken.

Monter à l’aide d’un service lié (recommandé)

Nous vous recommandons de monter un déclencheur via un service lié. Cette méthode évite les fuites de sécurité, car mssparkutils ne stocke aucun secrète ou aucune valeur d’authentification elle-même. Au lieu de cela, mssparkutils récupère toujours les valeurs d’authentification du service lié pour demander des données d’objet blob à partir du stockage distant.

Vous pouvez créer un service lié pour Data Lake Storage Gen2 ou Stockage Blob. Actuellement, Azure Synapse Analytics prend en charge deux méthodes d’authentification lorsque vous créez un service lié :

• Créer un service lié à l’aide d’une clé de compte

  

• Créer un service lié à l’aide d’une identité managée affectée par le système

  

Important

• Si le service lié créé ci-dessus pour Azure Data Lake Storage Gen2 utilise un point de terminaison privé managé (avec un URI dfs), nous devons créer un autre point de terminaison privé managé secondaire en utilisant l’option Stockage Blob Azure (avec un URI d’objet blob) pour veiller à ce que le code fsspec/adlfs interne puisse se connecter à l’aide de l’interface BlobServiceClient.
• Si le point de terminaison privé managé secondaire n’est pas configuré correctement, un message d’erreur tel que ServiceRequestError : Impossible de se connecter à l’hôte [storageaccountname].blob.core.windows.net:443 ssl:True [Nom ou service inconnu] s’affiche

Notes

Si vous créez un service lié utilisant une identité managée comme la méthode d’authentification, assurez-vous que le fichier MSI de l’espace de travail a le rôle Contributeur aux données Blob du stockage du conteneur monté.

Une fois le service lié créé avec succès, vous pouvez facilement monter le conteneur dans votre pool Spark avec le code Python suivant :

mssparkutils.fs.mount( 
    "abfss://mycontainer@<accountname>.dfs.core.windows.net", 
    "/test", 
    {"linkedService": "mygen2account"} 
) 

Notes

Il se peut que vous deviez importer mssparkutils s’il n’est pas disponible :

from notebookutils import mssparkutils 

Nous ne vous recommandons pas de monter un dossier racine, quelle que soit la méthode d’authentification que vous utilisez.

Paramètres de montage :

• fileCacheTimeout : les objets blob sont mis en cache dans le dossier temporaire local pendant 120 secondes par défaut. Parallèlement, BlobFuse ne vérifie pas si le fichier est à jour ou non. Le paramètre peut être défini pour modifier le délai d’expiration par défaut. Lorsque plusieurs clients modifient des fichiers en même temps, afin d’éviter les incohérences entre les fichiers locaux et distants, nous vous recommandons de raccourcir le temps de mise en cache, ou même de le remplacer par 0, et de toujours obtenir les derniers fichiers à partir du serveur.
• timeout : le délai d’expiration de l’opération de montage est de 120 secondes par défaut. Le paramètre peut être défini pour modifier le délai d’expiration par défaut. Lorsque le nombre d’exécuteurs est trop élevé ou que le montage expire, nous vous recommandons d’augmenter la valeur.
• étendue : ce paramètre est utilisé pour spécifier l’étendue du montage. La valeur par défaut est « travail ». Si l’étendue est définie sur « travail », le montage est visible uniquement pour le cluster actuel. Si l’étendue est définie sur « espace de travail », le montage est visible pour tous les blocs-notes de l’espace de travail actuel, et le point de montage est automatiquement créé s’il n’existe pas. Ajoutez les mêmes paramètres à l’API démonte pour démonter le point de montage. Le montage au niveau de l’espace de travail est pris en charge uniquement pour l’authentification du service lié.

Vous pouvez utiliser ces paramètres comme suit :

mssparkutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"linkedService":"mygen2account", "fileCacheTimeout": 120, "timeout": 120}
)

Montage via un jeton de signature d’accès partagé ou une clé de compte

Outre le montage via un service lié, mssparkutils prend en charge le passage explicite d’une clé de compte ou d’un jeton de signature d’accès partagé (SAP) en tant que paramètre pour monter la cible.

Pour des raisons de sécurité, nous vous recommandons de stocker des clés de compte ou des jetons SAP dans Azure Key Vault (comme l’illustre l’exemple de capture d’écran suivant). Vous pouvez ensuite les récupérer à l’aide de l’API mssparkutil.credentials.getSecret. Pour plus d’informations, consultez Gérer les clés de compte de stockage avec Key Vault et l’interface de ligne de commande Azure.

Voici l’exemple de code :

from notebookutils import mssparkutils  

accountKey = mssparkutils.credentials.getSecret("MountKV","mySecret")  
mssparkutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
) 

Notes

Par souci de sécurité, ne stockez pas d’informations d’identification dans du code.

Accéder aux fichiers sous le point de montage à l’aide de l’API mssparkutils fs

L'objectif principal de l'opération de montage est de permettre aux clients d'accéder aux données stockées dans un compte de stockage distant en utilisant une API de système de fichiers local. Vous pouvez également accéder aux données à l’aide de l’API mssparkutils fs avec un chemin d’accès monté en tant que paramètre. Le format de chemin d’accès utilisé ici est un peu différent.

En supposant que vous avez monté le conteneur Data Lake Storage Gen2 mycontainer sur /test à l’aide de l’API de montage. Lors de l’accès aux données via une API de système de fichiers local :

• Pour les versions Spark inférieures ou égales à 3.3, le format de chemin est /synfs/{jobId}/test/{filename}.
• Pour les versions Spark supérieures ou égales à 3.4, le format de chemin est /synfs/notebook/{jobId}/test/{filename}.

Nous vous recommandons d’utiliser un mssparkutils.fs.getMountPath() pour obtenir le chemin d’accès précis :

path = mssparkutils.fs.getMountPath("/test")

Remarque

Lorsque vous montez le stockage avec workspace étendue, le point de montage est créé sous le /synfs/workspace dossier. Et vous devez utiliser mssparkutils.fs.getMountPath("/test", "workspace") pour obtenir le chemin d’accès précis.

Lorsque vous souhaitez accéder aux données à l’aide de l’API mssparkutils fs , le format de chemin d’accès est semblable à ceci : synfs:/notebook/{jobId}/test/{filename}. Vous pouvez voir que le synfs est utilisé comme schéma dans ce cas, au lieu d’une partie du chemin d’accès monté. Bien sûr, vous pouvez également utiliser le schéma du système de fichiers local pour accéder aux données. Par exemple : file:/synfs/notebook/{jobId}/test/{filename}.

Les trois exemples suivants montrent comment accéder à un fichier avec un chemin d’accès au point de montage à l’aide de mssparkutils fs.

• Lister des répertoires :

  mssparkutils.fs.ls(f'file:{mssparkutils.fs.getMountPath("/test")}') 
  

• Lisez le contenu du fichier :

  mssparkutils.fs.head(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv') 
  

• Créer un répertoire :

  mssparkutils.fs.mkdirs(f'file:{mssparkutils.fs.getMountPath("/test")}/myDir') 
  

Accéder aux fichiers sous le point de montage à l’aide de l’API de lecture Spark

Vous pouvez fournir un paramètre pour accéder aux données via l’API de lecture Spark. Le format de chemin d’accès est le même lorsque vous utilisez l’API mssparkutils fs .

Lire un fichier à partir d’un compte de stockage monté Data Lake Storage Gen2

L’exemple suivant suppose qu’un compte de stockage Data Lake Storage Gen2 a déjà été monté, puis que vous lisez le fichier à l’aide d’un chemin de montage :

%%pyspark 

df = spark.read.load(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv', format='csv') 
df.show() 

Remarque

Lorsque vous montez le stockage à l’aide d’un service lié, vous devez toujours définir explicitement la configuration du service lié Spark avant d’utiliser le schéma synfs pour accéder aux données. Pour plus d’informations, reportez-vous à Stockage ADLS Gen2 avec des services liés.

Lire un fichier à partir d’un compte de stockage Blob monté

Si vous avez monté un compte de stockage Blob et souhaitez y accéder à l’aide de mssparkutils ou de l’API Spark, vous devez configurer explicitement le jeton SAP via une configuration Spark avant d’essayer de monter le conteneur à l’aide de l’API de montage :

1. Pour accéder à un compte de stockage Blob à l’aide de mssparkutils ou de l’API Spark après un montage de déclencheur, mettez à jour la configuration Spark comme illustré dans l’exemple de code suivant. Vous pouvez contourner cette étape si vous souhaitez accéder à la configuration Spark uniquement à l’aide de l’API de fichier local après le montage.

   blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") 
   
   spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token) 
   

2. Créez le service lié myblobstorageaccount et montez le compte de stockage Blob à l’aide du service lié :

   %%spark 
   mssparkutils.fs.mount( 
       "wasbs://mycontainer@<blobStorageAccountName>.blob.core.windows.net", 
       "/test", 
       Map("linkedService" -> "myblobstorageaccount") 
   ) 
   

3. Montez le conteneur de stockage Blob, puis lisez le fichier à l’aide du chemin d’accès de montage via l’API de fichier local :

       # mount the Blob Storage container, and then read the file by using a mount path
       with open(mssparkutils.fs.getMountPath("/test") + "/myFile.txt") as f:
       print(f.read())
   

4. Lisez les données du conteneur de stockage Blob monté via l’API de lecture Spark :

   %%spark
   // mount blob storage container and then read file using mount path
   val df = spark.read.text(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.txt')
   df.show()
   

Démonter le point de montage

Utilisez le code suivant pour démonter votre point de montage (/test dans cet exemple) :

mssparkutils.fs.unmount("/test") 

Limitations connues

• Le mécanisme de démontage n’est pas automatique. Une fois l’exécution de l’application terminée, pour démonter le point de montage afin de libérer l’espace disque, vous devez appeler explicitement une API de démontage dans votre code. Sinon, le point de montage existera toujours dans le nœud une fois l’exécution de l’application terminée.

• Le montage d’un compte de stockage Data Lake Storage Gen1 n’est pas pris en charge pour l’instant.

Étapes suivantes

• Bien démarrer avec Azure Synapse Analytics
• Surveiller votre espace de travail Synapse
• Présentation des utilitaires Microsoft Spark