Einführung in datei mount/unmount APIs in Azure Synapse Analytics

Das Azure Synapse Studio-Team hat zwei neue Bereitstellungs-/Entmount-APIs im Paket Microsoft Spark Utilities (mssparkutils) erstellt. Sie können diese APIs verwenden, um Remotespeicher (Azure Blob Storage, Azure Data Lake Storage Gen2 oder Azure Dateifreigabe) an alle Arbeitsknoten (Treiberknoten und Arbeitsknoten) anzufügen. Wenn der Speicher vorhanden ist, können Sie die lokale Datei-API verwenden, um auf Daten zuzugreifen, als ob sie im lokalen Dateisystem gespeichert ist. Weitere Informationen finden Sie unter Introduction to Microsoft Spark Utilities.

Der Artikel zeigt, wie Sie Mount/Unmount-APIs in Ihrem Arbeitsbereich verwenden. Sie lernen Folgendes:

• Bereitstellen von Data Lake Storage Gen2, Blob Storage oder Azure Dateifreigabe
• Zugreifen auf Dateien unter einem Bereitstellungspunkt über die lokale Dateisystem-API.
• Zugreifen auf Dateien unter einem Bereitstellungspunkt über die mssparkutils fs-API.
• Zugreifen auf Dateien unter einem Bereitstellungspunkt über die Spark-Lese-API.
• Aufheben der Einbindung eines Bereitstellungspunkts

Speicher einbinden

In diesem Abschnitt wird veranschaulicht, wie Sie Data Lake Storage Gen2 Schritt für Schritt als Beispiel bereitstellen. Die Montage Blob Storage und Azure Dateifreigabe funktioniert ähnlich.

Im Beispiel wird davon ausgegangen, dass Sie über ein Data Lake Storage Gen2 Konto mit dem Namen storegen2 verfügen. Das Konto verfügt über einen Container mit dem Namen mycontainer, den Sie für /test in Ihrem Spark-Pool bereitstellen möchten.

Zum Einbinden des Containers namens mycontainer muss mssparkutils zuerst überprüfen, ob Sie über die Berechtigung zum Zugreifen auf den Container verfügen. Derzeit unterstützt Azure Synapse Analytics drei Authentifizierungsmethoden für den Trigger-Bereitstellungsvorgang: linkedService, accountKey und sastoken.

Einbinden mithilfe eines verknüpften Dienstes (empfohlen)

Es wird empfohlen, eine Trigger-Bereitstellung über einen verknüpften Dienst zu erstellen. Diese Methode verhindert Sicherheitslecks, da mssparkutils selbst keine Geheimnis- oder Authentifizierungswerte speichert. Stattdessen ruft mssparkutils immer Authentifizierungswerte vom verknüpften Dienst ab, um Blob-Daten aus einem Remotespeicher anzufordern.

Sie können einen verknüpften Dienst für Data Lake Storage Gen2 oder Blob Storage erstellen. Derzeit unterstützt Azure Synapse Analytics zwei Authentifizierungsmethoden, wenn Sie einen verknüpften Dienst erstellen:

• Erstellen eines verknüpften Diensts mithilfe eines Kontoschlüssels

  

• Erstellen eines verknüpften Diensts mithilfe einer vom System zugewiesenen verwalteten Identität

  

Nachdem Sie einen verknüpften Dienst erfolgreich erstellt haben, können Sie den Container mithilfe des folgenden Python Codes auf einfache Weise in Ihren Spark-Pool einbinden:

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

from notebookutils import mssparkutils 

Einbindungsparameter:

• fileCacheTimeout: Blobs werden standardmäßig 120 Sekunden lang im lokalen temporären Ordner zwischengespeichert. Während dieser Zeit prüft BlobFuse nicht, ob die Datei aktuell ist. Der Parameter kann so festgelegt werden, dass die Standardtimeoutzeit geändert wird. Wenn mehrere Clients gleichzeitig Dateien ändern, empfiehlt es sich, die Cachezeit zu verkürzen oder sogar auf 0 zu ändern und immer die neuesten Dateien vom Server abzurufen, um Inkonsistenzen zwischen lokalen Dateien und Remotedateien zu vermeiden.
• Timeout: Das Timeout des Einbindungsvorgangs beträgt standardmäßig 120 Sekunden. Der Parameter kann so festgelegt werden, dass die Standardtimeoutzeit geändert wird. Wenn zu viele Executors vorhanden sind oder bei der Einbindung ein Timeout auftritt, empfiehlt es sich, den Wert zu erhöhen.
• scope: Der scope-Parameter wird verwendet, um den Einbindungsbereich anzugeben. Der Standardwert ist „job“. Wenn der Bereich auf „job“ festgelegt ist, ist die Einbindung nur für den aktuellen Cluster sichtbar. Ist der Bereich auf „workspace“ festgelegt, ist die Einbindung für alle Notebooks im aktuellen Arbeitsbereich sichtbar, und der Bereitstellungspunkt wird automatisch erstellt, sofern er nicht vorhanden ist. Fügen Sie der API zum Aufheben der Einbindung dieselben Parameter hinzu, um die Einbindung des Bereitstellungspunkts aufzuheben. Die Einbindung auf Arbeitsbereichsebene wird nur für die verknüpfte Dienstauthentifizierung unterstützt.

Sie können diese Parameter wie folgt verwenden:

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

Einbinden über SAS-Token (Shared Access Signature) oder Kontoschlüssel

Zusätzlich zur Einbindung über einen verknüpften Dienst unterstützt mssparkutils die explizite Übergabe eines Kontoschlüssels oder eines SAS-Tokens (Shared Access Signature) als Parameter zum Einbinden des Ziels.

Aus Sicherheitsgründen wird empfohlen, verwaltete Identitäten und Microsoft Entra Authentifizierung anstelle von Kontoschlüsseln oder SAS-Token zu verwenden, wenn möglich. Wenn Sie Kontoschlüssel verwenden müssen, speichern Sie sie in Azure Key Vault (wie im folgenden Beispiel gezeigt). Sie können sie dann mithilfe der mssparkutil.credentials.getSecret-API abrufen. Weitere Informationen finden Sie unter Authorize access to data in Azure Storage.

Sehen Sie sich den Beispielcode an:

from notebookutils import mssparkutils  

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

Zugreifen auf Dateien unter dem Bereitstellungspunkt mithilfe der mssparktuils fs-API

Der Hauptzweck des Einbindungsvorgangs ist, Kunden den Zugriff auf Daten zu ermöglichen, die in einem Remotespeicherkonto gespeichert sind, indem sie eine lokale Dateisystem-API verwenden. Sie können auch auf die Daten zugreifen, indem Sie die mssparkutils fs-API mit einem bereitgestellten Pfad als Parameter verwenden. Das hier verwendete Pfadformat weicht davon etwas ab.

Vorausgesetzt, Sie haben den Data Lake Storage Gen2 Container mycontainer mithilfe der Bereitstellungs-API in /test bereitgestellt. Beim Zugriff auf die Daten über eine lokale Dateisystem-API:

• Für Spark-Versionen kleiner als oder gleich 3.3 ist /synfs/{jobId}/test/{filename}das Pfadformat.
• Bei Spark-Versionen größer als oder gleich 3.4 ist /synfs/notebook/{jobId}/test/{filename}das Pfadformat.

Es wird empfohlen, über mssparkutils.fs.getMountPath() den genauen Pfad abzurufen:

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

Wenn Sie mithilfe der mssparkutils fs API auf die Daten zugreifen möchten, ist das Pfadformat wie folgt: synfs:/notebook/{jobId}/test/{filename} Wie Sie sehen können, wird in diesem Fall synfs anstelle eines Teils des Pfads des Bereitstellungspfads als Schema verwendet. Natürlich können Sie auch das lokale Dateisystemschema verwenden, um auf die Daten zuzugreifen. Beispiel: file:/synfs/notebook/{jobId}/test/{filename}.

In den folgenden drei Beispielen wird gezeigt, wie Sie mithilfe eines Bereitstellungspunktpfads mit mssparkutils fs auf eine Datei zugreifen.

• Auflisten von Verzeichnissen:

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

• Lesen von Dateiinhalten:

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

• Erstellen eines Verzeichnisses:

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

Zugreifen auf Dateien unter einem Bereitstellungspunkt über die Spark-Lese-API

Sie können einen Parameter bereitstellen, um über die Spark-Lese-API auf die Daten zuzugreifen. Das Pfadformat hier ist identisch, wenn Sie die mssparkutils fs API verwenden.

Lesen einer Datei aus einem bereitgestellten Data Lake Storage Gen2 Speicherkonto

Im folgenden Beispiel wird davon ausgegangen, dass ein Data Lake Storage Gen2 Speicherkonto bereits bereitgestellt wurde, und anschließend die Datei mithilfe eines Bereitstellungspfads lesen:

%%pyspark 

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

Lesen einer Datei aus einem bereitgestellten Blob Storage Konto

Wenn Sie ein Blob Storage Konto bereitgestellt haben und mithilfe von mssparkutils oder der Spark-API darauf zugreifen möchten, müssen Sie das SAS-Token explizit über Spark-Konfiguration konfigurieren, bevor Sie versuchen, den Container mithilfe der Bereitstellungs-API zu bereitstellen:

1. Um mithilfe von mssparkutils oder der Spark-API nach einer Trigger-Bereitstellung auf ein Blob Storage Konto zuzugreifen, aktualisieren Sie die Spark-Konfiguration wie im folgenden Codebeispiel gezeigt. Sie können diesen Schritt umgehen, wenn Sie nach der Bereitstellung nur mithilfe der lokalen Datei-API auf die Spark-Konfiguration zugreifen möchten.

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

2. Erstellen Sie den verknüpften Dienst myblobstorageaccount, und stellen Sie das Blob Storage Konto mithilfe des verknüpften Diensts ein:

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

3. Mount the Blob Storage container, and then read the file by using a mount path through the local file API:

       # 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. Lesen Sie die Daten aus dem bereitgestellten Blob Storage-Container über die Spark-Lese-API:

   %%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()
   

Aufheben des Bereitstellungspunkts

Verwenden Sie den folgenden Code, um Ihren Bereitstellungspunkt (/test in diesem Beispiel) aufzuheben:

mssparkutils.fs.unmount("/test") 

Bekannte Einschränkungen

• Der Mechanismus für die Aufhebung der Bereitstellung ist nicht automatisch. Wenn die Ausführung der Anwendung beendet ist, müssen, Sie, um den Bereitstellungspunkt aufzuheben, um den Speicherplatz freizugeben, explizit eine Unmount-API in Ihrem Code aufrufen. Andernfalls ist der Bereitstellungspunkt weiterhin im Knoten vorhanden, nachdem die Anwendungsausführung beendet wurde.

• Das Einbinden eines Data Lake Storage Gen1 Speicherkontos wird derzeit nicht unterstützt.

Nächste Schritte

• Get started with Azure Synapse Analytics
• Überwachen Ihres Synapse-Arbeitsbereichs
• Introduction to Microsoft Spark Utilities