Azure Synapse Analytics 中文件掛載/卸載 API 簡介

Azure Synapse Studio 團隊在 Microsoft Spark Utilities （mssparkutils）套件中建立了兩個新的掛載/卸載 API。你可以利用這些 API 將遠端儲存（Azure Blob 儲存體、Azure Data Lake Storage Gen2 或 Azure File Share）附加到所有工作節點（驅動節點和工作節點）。記憶體就緒之後，您可以使用本機檔案 API 來存取數據，就像儲存在本機檔系統中一樣。欲了解更多資訊，請參見Microsoft火花工具導論。

本文說明如何在工作區中使用掛接/卸除 API。您將了解：

如何掛載 Data Lake Storage Gen2、Blob 儲存體或 Azure 檔案分享。
如何透過本機文件系統 API 存取裝入點下的檔案。
如何使用 API 存取裝入點 mssparkutils fs 下的檔案。
如何使用 Spark 讀取 API 存取裝入點下的檔案。
如何卸除裝入點。

警告

Azure Data Lake Storage Gen1 儲存不被支援。你可以先依照 Azure Data Lake Storage Gen1 到 Gen2 的遷移指引遷移到 Data Lake Storage Gen2，再使用 mount API。

掛接儲存體

本節將示範如何逐步安裝 Data Lake Storage Gen2 作為範例。掛載 Blob 儲存體和 Azure 檔案共享的運作方式類似。

這個例子假設你有一個Data Lake Storage Gen2帳號，名叫 storegen2。帳戶有一個名為的容器，您想要在Spark集區中掛接至mycontainer該容器/test。

Data Lake Storage Gen2儲存帳號截圖。

若要掛接名為 mycontainer的容器， mssparkutils 首先必須檢查您是否具有存取容器的許可權。目前，Azure Synapse Analytics 支援三種觸發掛載操作的認證方法：linkedService、accountKey 以及 sastoken。

使用連結服務掛接（建議）

我們建議透過連結服務掛接觸發程式。此方法可避免安全性外泄，因為 mssparkutils 不會儲存任何秘密或驗證值本身。相反地， mssparkutils 一律從鏈接服務擷取驗證值，以向遠端記憶體要求 Blob 數據。

鏈接服務的螢幕快照。

你可以為 Data Lake Storage Gen2 或 Blob 儲存體建立連結服務。目前，Azure Synapse Analytics 在建立連結服務時支援兩種認證方法：

使用帳戶金鑰建立連結服務
使用系統指派的受控識別建立連結服務

重要

如果上述連結服務 to Azure Data Lake Storage Gen2 使用 managed 私有端點（搭配 dfs URI），那麼我們需要用 Azure Blob 儲存體建立另一個次要管理的私有端點選項（搭配 blob URI）以確保內部 fsspec/adlfs 程式碼能透過 BlobServiceClient 介面連接。
如果次要受控私人端點未正確設定，則會看到類似 ServiceRequestError 的錯誤訊息：無法連線到主機 [storageaccountname].blob.core.windows.net：443 ssl：True [名稱或服務未知]

使用 Blob 端點建立 ADLS Gen2 記憶體受控私人端點的螢幕快照。

注意

如果您使用受控識別作為驗證方法來建立連結服務，請確定工作區 MSI 檔案具有掛接容器的記憶體 Blob 數據參與者角色。

成功建立連結服務後，你可以使用以下 Python 程式碼輕鬆將容器掛載到 Spark 池中：

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

注意

如果無法使用，您可能需要匯入 mssparkutils：

from notebookutils import mssparkutils

無論您使用哪一種驗證方法，我們不建議您掛接根資料夾。

裝載參數：

fileCacheTimeout: Blobs 預設會在本機暫存資料夾中快取 120 秒。在此期間，blobfuse 不會檢查檔案是否為最新狀態。參數可以設定為變更預設逾時時間。當多個用戶端同時修改檔案時，為了避免本機和遠端檔案之間的不一致，建議您縮短快取時間，甚至將其變更為 0，並且一律從伺服器取得最新的檔案。
timeout：裝載作業逾時預設為120秒。參數可以設定為變更預設逾時時間。當執行程式太多或掛接逾時時，建議增加值。
scope：scope 參數是用來指定掛接的範圍。預設值為「job」。如果範圍設定為「作業」，則只有目前的叢集才能看到掛接。如果範圍設定為「工作區」，則目前工作區中的所有筆記本都可以看到掛接，如果不存在，就會自動建立裝入點。將相同的參數新增至卸除 API 以取消掛接裝入點。僅支援連結服務驗證的工作區層級掛接。

您可以使用這些參數，如下所示：

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

透過共用存取簽章權杖或帳戶密鑰裝載

除了透過連結服務掛接， mssparkutils 還支援明確傳遞帳戶密鑰或共用存取簽章（SAS）令牌作為掛接目標的參數。

出於安全考量，我們建議盡可能使用管理身份和 Microsoft Entra 認證，而非帳號金鑰或 SAS 令牌。如果你必須使用帳號金鑰，請將它們存放在 Azure Key Vault（如下範例截圖所示）。接著，您可以使用 API 來擷取它們 mssparkutil.credentials.getSecret 。欲了解更多資訊，請參閱授權存取資料，Azure 儲存體。

此螢幕快照顯示儲存在金鑰保存庫中的秘密。

以下是範例程式碼：

from notebookutils import mssparkutils  

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

注意

基於安全性考慮，請勿將認證儲存在程序代碼中。

使用 mssparkutils fs API 存取裝入點下的檔案

掛接作業的主要目的是讓客戶使用本機文件系統 API 來存取儲存在遠端記憶體帳戶中的數據。您也可以使用 mssparkutils fs API 搭配掛接路徑做為參數來存取數據。這裡使用的路徑格式稍有不同。

假設你已經用掛載 API 掛載了 Data Lake Storage Gen2 容器的 mycontainer 到 /test。透過本機檔案系統 API 存取資料時：

對於小於或等於 3.3 的 Spark 版本，路徑格式為 /synfs/{jobId}/test/{filename}。
對於大於或等於 3.4 的 Spark 版本，路徑格式為 /synfs/notebook/{jobId}/test/{filename}。

我們建議使用 mssparkutils.fs.getMountPath() 來取得正確的路徑：

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

注意

當您使用 workspace 範圍掛接記憶體時，裝入點會在資料夾下 /synfs/workspace 建立。您需要使用 mssparkutils.fs.getMountPath("/test", "workspace") 來取得正確的路徑。

當您想要使用 mssparkutils fs API 存取資料時，路徑格式如下所示： synfs:/notebook/{jobId}/test/{filename}。在此案例中，您可以看到 synfs 這是用來作為架構，而不是掛接路徑的一部分。當然，您也可以使用本機文件系統架構來存取數據。例如： file:/synfs/notebook/{jobId}/test/{filename} 。

下列三個範例示範如何使用存取具有裝入點路徑 mssparkutils fs的檔案。

列出目錄：

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

讀取檔案內容：

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

建立目錄：

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

使用 Spark 讀取 API 存取裝入點下的檔案

您可以提供參數，以透過Spark讀取API存取數據。當您使用 mssparkutils fs API 時，這裡的路徑格式會相同。

從掛載的 Data Lake Storage Gen2 儲存帳號讀取檔案

以下範例假設 Data Lake Storage Gen2 的儲存帳號已經掛載好，然後你透過掛載路徑讀取該檔案：

%%pyspark 

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

注意

當您使用連結服務掛接記憶體時，應該一律先明確設定 spark 連結服務組態，再使用 synfs 架構來存取數據。如需詳細資訊，請參閱具有連結服務的 ADLS Gen2 記憶體。

從掛載的 Blob 儲存體帳號讀取檔案

如果你掛載了一個Blob 儲存體帳號，想用 mssparkutils 或 Spark API 存取，你需要先透過 Spark 設定明確設定 SAS 令牌，才能嘗試用掛載 API 掛載容器：

若要使用 mssparkutils 或觸發掛載後使用 Spark API 存取 Blob 儲存體帳號，請如以下程式碼範例所示更新 Spark 設定。如果您想要只在掛接之後使用本機檔案 API 來存取 Spark 組態，則可以略過此步驟。
```
blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") 

spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token) 
```

建立連結服務 myblobstorageaccount，並使用連結服務掛載 Blob 儲存體帳號：

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

掛載 Blob 儲存體容器，然後透過本地檔案 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())

透過 Spark 讀取 API 從已掛載的 Blob 儲存體容器讀取資料：

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

卸載入點

使用下列程式代碼來卸載入點（/test 在此範例中為）：

mssparkutils.fs.unmount("/test")

已知的限制

卸除機制不是自動的。當應用程式執行完成時，若要卸載裝入點以釋放磁碟空間，您必須在程式代碼中明確呼叫卸除 API。否則，在應用程式執行完成之後，裝載點仍會存在於節點中。
目前不支援掛載 Data Lake Storage Gen1 儲存帳號。

下一步

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-06-01