Introduzione alle API di montaggio/smontaggio di file in Azure Synapse Analytics

Il team di Azure Synapse Studio ha creato due nuove API di montaggio/smontaggio nel pacchetto Microsoft Spark Utilities (mssparkutils). È possibile usare queste API per collegare l'archiviazione remota (Archiviazione BLOB di Azure o Azure Data Lake Archiviazione Gen2) a tutti i nodi di lavoro (nodo driver e nodi di lavoro). Al termine dell'archiviazione, è possibile usare l'API file locale per accedere ai dati come se fossero archiviati nel file system locale. Per altre informazioni, vedere Introduzione alle utilità di Microsoft Spark.

L'articolo illustra come usare le API di montaggio/smontaggio nell'area di lavoro. Si apprenderà:

• Come montare data lake Archiviazione Gen2 o Archiviazione BLOB.
• Come accedere ai file nel punto di montaggio tramite l'API del file system locale.
• Come accedere ai file nel punto di montaggio usando l'API mssparktuils fs .
• Come accedere ai file nel punto di montaggio usando l'API di lettura Spark.
• Come smontare il punto di montaggio.

Avviso

Il montaggio della condivisione file di Azure è temporaneamente disabilitato. È possibile usare invece il montaggio di Data Lake Archiviazione Gen2 o Archiviazione BLOB di Azure, come descritto nella sezione successiva.

L'archiviazione di Azure Data Lake Archiviazione Gen1 non è supportata. È possibile eseguire la migrazione a Data Lake Archiviazione Gen2 seguendo le indicazioni sulla migrazione da Azure Data Lake Archiviazione Gen1 a Gen2 prima di usare le API di montaggio.

Montare l'archiviazione

Questa sezione illustra come montare Data Lake Archiviazione Gen2 in modo dettagliato come esempio. Il montaggio di Archiviazione BLOB funziona in modo analogo.

Nell'esempio si presuppone che sia presente un account Data Lake Archiviazione Gen2 denominato storegen2. L'account ha un contenitore denominato mycontainer che si vuole montare /test nel pool di Spark.

Per montare il contenitore denominato mycontainer, mssparkutils è prima necessario verificare se si dispone dell'autorizzazione per accedere al contenitore. Attualmente, Azure Synapse Analytics supporta tre metodi di autenticazione per l'operazione di montaggio del trigger: LinkedService, accountKeye sastoken.

Montare usando un servizio collegato (scelta consigliata)

È consigliabile montare un trigger tramite il servizio collegato. Questo metodo evita perdite di sicurezza, perché mssparkutils non archivia alcun segreto o valori di autenticazione. Recupera invece mssparkutils sempre i valori di autenticazione dal servizio collegato per richiedere i dati BLOB dall'archiviazione remota.

È possibile creare un servizio collegato per Data Lake Archiviazione Gen2 o Archiviazione BLOB. Attualmente, Azure Synapse Analytics supporta due metodi di autenticazione quando si crea un servizio collegato:

• Creare un servizio collegato usando una chiave dell'account

  

• Creare un servizio collegato usando un'identità gestita

  

Importante

• Se il servizio collegato precedente creato ad Azure Data Lake Archiviazione Gen2 usa un endpoint privato gestito (con un URI dfs), è necessario creare un altro endpoint privato gestito secondario usando l'opzione Archiviazione BLOB di Azure (con un URI BLOB) per assicurarsi che il codice fsspec/adlfs interno possa connettersi usando l'interfaccia BlobServiceClient.
• Nel caso in cui l'endpoint privato gestito secondario non sia configurato correttamente, verrà visualizzato un messaggio di errore simile a ServiceRequestError: Impossibile connettersi all'host [storageaccountname].blob.core.windows.net:443 ssl:True [Nome o servizio non noto]

Nota

Se si crea un servizio collegato usando un'identità gestita come metodo di autenticazione, assicurarsi che il file MSI dell'area di lavoro abbia il ruolo collaboratore ai dati BLOB Archiviazione del contenitore montato.

Dopo aver creato correttamente il servizio collegato, è possibile montare facilmente il contenitore nel pool di Spark usando il codice Python seguente:

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

Nota

Potrebbe essere necessario importare mssparkutils se non è disponibile:

from notebookutils import mssparkutils 

Parametri di montaggio:

• fileCacheTimeout: i BLOB verranno memorizzati nella cache nella cartella temporanea locale per 120 secondi per impostazione predefinita. Durante questo periodo, blobfuse non verificherà se il file è aggiornato o meno. È possibile impostare il parametro per modificare il timeout predefinito. Quando più client modificano contemporaneamente i file, per evitare incoerenze tra file locali e remoti, è consigliabile abbreviare il tempo della cache o persino modificarlo su 0 e ottenere sempre i file più recenti dal server.
• timeout: il timeout dell'operazione di montaggio è 120 secondi per impostazione predefinita. È possibile impostare il parametro per modificare il timeout predefinito. Quando sono presenti troppi executor o quando si verifica il timeout del montaggio, è consigliabile aumentare il valore.
• scope: il parametro di ambito viene usato per specificare l'ambito del montaggio. Il valore predefinito è "job". Se l'ambito è impostato su "processo", il montaggio è visibile solo al cluster corrente. Se l'ambito è impostato su "area di lavoro", il montaggio è visibile a tutti i notebook nell'area di lavoro corrente e il punto di montaggio viene creato automaticamente se non esiste. Aggiungere gli stessi parametri all'API di smontaggio per smontare il punto di montaggio. Il montaggio a livello di area di lavoro è supportato solo per l'autenticazione del servizio collegato.

È possibile usare questi parametri come segue:

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

Non è consigliabile montare una cartella radice, indipendentemente dal metodo di autenticazione usato.

Montare tramite token di firma di accesso condiviso o chiave dell'account

Oltre al montaggio tramite un servizio collegato, mssparkutils supporta il passaggio esplicito di una chiave dell'account o di un token di firma di accesso condiviso (SAS) come parametro per montare la destinazione.

Per motivi di sicurezza, è consigliabile archiviare le chiavi dell'account o i token di firma di accesso condiviso in Azure Key Vault (come illustrato nello screenshot di esempio seguente). È quindi possibile recuperarli usando l'API mssparkutil.credentials.getSecret . Per altre informazioni, vedere Gestire le chiavi dell'account di archiviazione con Key Vault e l'interfaccia della riga di comando di Azure (legacy).

Ecco il codice di esempio:

from notebookutils import mssparkutils  

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

Nota

Per motivi di sicurezza, non archiviare le credenziali nel codice.

Accedere ai file nel punto di montaggio usando l'API mssparkutils fs

Lo scopo principale dell'operazione di montaggio è consentire ai clienti di accedere ai dati archiviati in un account di archiviazione remoto usando un'API del file system locale. È anche possibile accedere ai dati usando l'API mssparkutils fs con un percorso montato come parametro. Il formato del percorso usato qui è leggermente diverso.

Si supponga di aver montato il contenitore mycontainer/test Data Lake Archiviazione Gen2 usando l'API di montaggio. Quando si accede ai dati usando un'API del file system locale, il formato del percorso è simile al seguente:

/synfs/{jobId}/test/{filename}

È consigliabile usare un mssparkutils.fs.getMountPath() per ottenere il percorso accurato:

path = mssparkutils.fs.getMountPath("/test") # equals to /synfs/{jobId}/test

Quando si vuole accedere ai dati usando l'API mssparkutils fs , il formato del percorso è simile al seguente:

synfs:/{jobId}/test/{filename}

È possibile osservare che synfs viene usato come schema in questo caso, anziché come parte del percorso montato.

I tre esempi seguenti illustrano come accedere a un file con un percorso del punto di montaggio usando mssparkutils fs. Negli esempi è 49 un ID processo Spark ottenuto dalla chiamata mssparkutils.env.getJobId()a .

• Elencare le directory:

  mssparkutils.fs.ls("synfs:/49/test") 
  

• Leggere il contenuto del file:

  mssparkutils.fs.head("synfs:/49/test/myFile.txt") 
  

• Creare una directory:

  mssparkutils.fs.mkdirs("synfs:/49/test/newdir") 
  

Accedere ai file nel punto di montaggio usando l'API di lettura Spark

È possibile specificare un parametro per accedere ai dati tramite l'API di lettura Spark. Il formato del percorso è lo stesso quando si usa l'API mssparkutils fs :

synfs:/{jobId}/test/{filename}

Leggere un file da un account di archiviazione di Data Lake Archiviazione Gen2 montato

Nell'esempio seguente si presuppone che sia già stato montato un account di archiviazione Data Lake Archiviazione Gen2 e quindi si legge il file usando un percorso di montaggio:

%%pyspark 

df = spark.read.load("synfs:/49/test/myFile.csv", format='csv') 
df.show() 

Nota

Quando si monta l'archiviazione usando un servizio collegato, è consigliabile impostare in modo esplicito la configurazione del servizio collegato Spark prima di usare lo schema synfs per accedere ai dati. Per informazioni dettagliate, vedere Archiviazione di ADLS Gen2 con i servizi collegati.

Leggere un file da un account di Archiviazione BLOB montato

Se è stato montato un account di Archiviazione BLOB e si vuole accedervi usando mssparkutils o l'API Spark, è necessario configurare in modo esplicito il token di firma di accesso condiviso tramite la configurazione di Spark prima di provare a montare il contenitore usando l'API di montaggio:

1. Per accedere a un account blob Archiviazione usando mssparkutils o l'API Spark dopo un montaggio di trigger, aggiornare la configurazione di Spark come illustrato nell'esempio di codice seguente. È possibile ignorare questo passaggio se si vuole accedere alla configurazione di Spark solo usando l'API file locale dopo il montaggio.

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

2. Creare il servizio myblobstorageaccountcollegato e montare l'account Archiviazione BLOB usando il servizio collegato:

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

3. Montare il contenitore BLOB Archiviazione e quindi leggere il file usando un percorso di montaggio tramite l'API file locale:

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

4. Leggere i dati dal contenitore BLOB montato Archiviazione tramite l'API di lettura Spark:

   %%spark
   // mount blob storage container and then read file using mount path
   val df = spark.read.text("synfs:/49/test/myFile.txt")
   df.show()
   

Smontare il punto di montaggio

Usare il codice seguente per smontare il punto di montaggio (/test in questo esempio):

mssparkutils.fs.unmount("/test") 

Limitazioni note

• La mssparkutils fs help funzione non ha ancora aggiunto la descrizione relativa alla parte di montaggio/smontaggio.

• Il meccanismo di smontaggio non è automatico. Al termine dell'esecuzione dell'applicazione, per smontare il punto di montaggio per rilasciare lo spazio su disco, è necessario chiamare in modo esplicito un'API di smontaggio nel codice. In caso contrario, il punto di montaggio sarà ancora presente nel nodo al termine dell'esecuzione dell'applicazione.

• Il montaggio di un account di archiviazione di Data Lake Archiviazione Gen1 non è attualmente supportato.

Passaggi successivi

• Introduzione ad Azure Synapse Analytics
• Monitorare l'area di lavoro di Synapse
• Introduzione alle utilità di Microsoft Spark