Einführung in die Mount/Unmount-APIs in Azure Synapse Analytics

Das Azure Synapse Studio-Team hat zwei neue Mount/Unmount-APIs im Microsoft Spark Utilities- (mssparkutils) Paket erstellt. Sie können diese APIs verwenden, um Remotespeicher (Azure Blob Storage oder Azure Data Lake Storage Gen2) an alle funktionierenden Knoten (Treiberknoten oder Arbeiterknoten) anzuhängen. 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 Einführung in Microsoft Spark-Hilfsprogramme.

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

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

Speicher einbinden

In diesem Abschnitt wird als Beispiel veranschaulicht, wie Sie Data Lake Storage Gen2 Schritt für Schritt einbinden. Das Einbinden von Blob Storage 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-Mount-Vorgang: linkedService, accountKeyund 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 den verknüpften Dienst erfolgreich erstellt haben, können Sie den Container ganz einfach mit dem folgenden Python-Code 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 empfehlen wir, Kontoschlüssel oder SAS-Token in Azure Key Vault zu speichern (wie im folgenden Beispiel gezeigt). Sie können sie dann mithilfe der mssparkutil.credentials.getSecret-API abrufen. Weitere Informationen finden Sie unter Verwalten von Speicherkontoschlüsseln mit Key Vault und der Azure-Befehlszeilenschnittstelle (Legacy).

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.

Angenommen, 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 Sie dann 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 in einem eingebundenen Blob Storage-Konto

Wenn Sie ein Blob Storage-Konto eingebunden haben und dann über mssparkutils oder die Spark-API darauf zugreifen möchten, müssen Sie das SAS-Token zunächst explizit über die Spark-Konfiguration konfigurieren, bevor Sie den Container mithilfe der Bereitstellungs-API einbinden können.

1. Um auf ein Blob Storage-Konto mithilfe von mssparkutils oder der Spark API nach einem Trigger-Mount 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 binden 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. Binden Sie den Blob Storage-Container ein und lesen Sie dann die Datei mithilfe des Bereitstellungspfads über die lokale Datei-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 zurzeit nicht unterstützt.

Nächste Schritte

• Erste Schritte mit Azure Synapse Analytics
• Überwachen Ihres Synapse-Arbeitsbereichs
• Einführung in Microsoft Spark-Hilfsprogramme