Подключение и отключение файла NotebookUtils для Fabric

NotebookUtils поддерживает монтирование и размонтирование файлов с помощью пакета служебных программ Microsoft Spark. Вы можете использовать API mount, unmount, getMountPath(), mounts() для подключения удаленного хранилища (ADLS 2-го поколения, Хранилище Blob Azure, OneLake) ко всем узлам (основному и рабочим узлам). После установки точки подключения хранилища используйте локальный API файлов для доступа к данным, как будто он хранится в локальной файловой системе.

Операции монтирования особенно полезны в следующих случаях.

• Работа с библиотеками, ожидающими локальных путей к файлам.
• Требуется согласованная семантика файловой системы в облачном хранилище.
• Эффективный доступ к ярлыкам OneLake (S3/GCS).
• Создайте переносимый код, который работает с несколькими серверными службами хранилища.

Справочник по API

В следующей таблице перечислены доступные API подключения.

Методы аутентификации

Операции подключения поддерживают несколько методов проверки подлинности. Выберите метод на основе типов хранилища и требований к безопасности.

Токен Microsoft Entra (по умолчанию и рекомендуется)

Аутентификация токенов Microsoft Entra использует идентификацию исполнителя блокнота, будь то пользователь или субъект-службы. В вызове подключения не требуются явные учетные данные, что делает его наиболее безопасным. Используйте этот параметр для подключения Lakehouse и хранилища рабочей области Fabric.

# Mount using Microsoft Entra token (no credentials needed)
notebookutils.fs.mount(
    "abfss://mycontainer@mystorageaccount.dfs.core.windows.net",
    "/mydata"
)

Ключ учетной записи

Используйте ключ учетной записи, если учетная запись хранения не поддерживает проверку подлинности Microsoft Entra или при доступе к внешнему или стороннему хранилищу. Сохраните ключи учетной записи notebookutils.credentials.getSecret в Azure Key Vault и извлеките их через API.

# Retrieve account key from Azure Key Vault
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"accountKey": accountKey}
)

Токен параметра подписи общего доступа (SAS)

Используйте маркер подписанного URL-адреса (SAS) для доступа с ограниченным временем и ограниченными правами доступа. Этот параметр полезен, если необходимо предоставить временный доступ внешним сторонам. Храните маркеры SAS в Azure Key Vault.

# Retrieve SAS token from Azure Key Vault
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"sasToken": sasToken}
)

Подключение учетной записи ADLS 2-го поколения

В следующем примере показано, как подключить Azure Data Lake Storage 2-го поколения. Подключение хранилища BLOB и файлового ресурса Azure осуществляется аналогично.

В этом примере предполагается, что у вас есть одна учетная запись Data Lake Storage Gen2 с именем storegen2, в которой есть контейнер mycontainer, который вы хотите подключить к /test в сеансе Spark вашего блокнота.

Чтобы подключить контейнер с именем mycontainer, NotebookUtils сначала необходимо проверить, есть ли у вас разрешение на доступ к контейнеру. В настоящее время Fabric поддерживает три метода проверки подлинности для операции монтирования триггера: токен Microsoft Entra (по умолчанию), accountKey и sasToken.

По соображениям безопасности сохраните ключи учетной записи или маркеры SAS в Azure Key Vault (как показано на следующем снимке экрана). Затем их можно получить с помощью API notebookutils.credentials.getSecret. Дополнительные сведения об Azure Key Vault см. в статье "Сведения о ключах управляемой учетной записи хранения Azure Key Vault".

Пример кода для метода accountKey :

# get access token for keyvault resource
# You can also use the full audience, such as https://vault.azure.net.
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

Пример кода для sasToken:

# get access token for keyvault resource
# You can also use the full audience, such as https://vault.azure.net.
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"sasToken":sasToken}
)

Параметры монтирования

Поведение монтирования можно настроить с помощью следующих необязательных параметров в карте extraConfigs.

• fileCacheTimeout: по умолчанию блобы кэшируются в локальной папке temp в течение 120 секунд. В течение этого времени blobfuse не проверяет, обновлен ли файл. Этот параметр можно задать для изменения времени ожидания по умолчанию. Если несколько клиентов одновременно изменяют файлы, чтобы избежать несоответствий между локальными и удаленными файлами, сократите время кэша или установите его на 0, чтобы всегда получать последние файлы с сервера.
• время ожидания: время ожидания операции подключения составляет 30 секунд по умолчанию. Этот параметр можно задать для изменения времени ожидания по умолчанию. Когда количество исполнителей превышает норму или истекает тайм-аут монтирования, увеличьте значение.

Эти параметры можно использовать следующим образом:

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

Рекомендации по настройке кэша

Выберите значение времени ожидания кэша на основе шаблона доступа:

Шаблон нулевого кэша

При одновременном изменении файлов несколькими клиентами используйте конфигурацию нулевого кэша, чтобы всегда получать последнюю версию с сервера.

# For scenarios with multiple clients modifying files
# Use zero cache to always fetch the latest from the server
notebookutils.fs.mount(
    "abfss://shared@account.dfs.core.windows.net",
    "/shared_data",
    {"fileCacheTimeout": 0}
)

Установить Lakehouse

Подключение Lakehouse поддерживает только проверку подлинности маркера Microsoft Entra. Пример кода для подключения Lakehouse к /<mount_name>:

notebookutils.fs.mount( 
 "abfss://<workspace_name>@onelake.dfs.fabric.microsoft.com/<lakehouse_name>.Lakehouse", 
 "/<mount_name>"
)

Доступ к файлам в точке подключения с помощью API notebookutils fs

Используйте операции подключения, если требуется получить доступ к данным в удаленном хранилище через локальный API файловой системы. Вы также можете получить доступ к подключенным данным с помощью notebookutils.fs API с подключенным путем, но формат пути отличается.

Предположим, что вы подключили контейнер Data Lake Storage 2-го поколения mycontainer к /test с помощью API подключения. При доступе к данным с помощью локального API файловой системы формат пути выглядит следующим образом:

/synfs/notebook/{sessionId}/test/{filename}

Если вы хотите получить доступ к данным с помощью notebookutils fs API, используйте getMountPath() для получения точного пути:

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

• Список каталогов.

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

• Прочитайте содержимое файла.

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

• Создайте каталог.

  notebookutils.fs.mkdirs(f"file://{notebookutils.fs.getMountPath('/test')}/newdir")
  

Доступ к файлам под точкой подключения через локальный путь

Файлы можно считывать и записывать в точке подключения с помощью стандартной файловой системы. В следующем примере Python показан этот шаблон:

#File read
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "r") as f:
    print(f.read())
#File write
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "w") as f:
    print(f.write("dummy data"))

Проверка существующих точек подключения

Используйте API для проверки всех существующих сведений о точке notebookutils.fs.mounts() подключения:

notebookutils.fs.mounts()

Проверьте, существует ли точка монтирования перед монтированием

existing_mounts = notebookutils.fs.mounts()
mount_point = "/mydata"

if any(m.mountPoint == mount_point for m in existing_mounts):
    print(f"Mount point {mount_point} already exists")
else:
    notebookutils.fs.mount(
        "abfss://container@account.dfs.core.windows.net",
        mount_point
    )
    print("Mount created successfully")

Отмонтировать точку монтирования

Используйте следующий код, чтобы отключить точку подключения (/test в этом примере):

notebookutils.fs.unmount("/test")

Рабочий процесс монтирования-процесса-отмонтирования

Для надежного управления ресурсами оберните операции монтажа в try/finally блоке, чтобы обеспечить очистку, даже если возникает ошибка.

def process_with_mount(source_uri, mount_point):
    """Complete workflow: mount, process, unmount."""
    
    try:
        # Step 1: Check if already mounted
        existing = notebookutils.fs.mounts()
        if any(m.mountPoint == mount_point for m in existing):
            print(f"Already mounted at {mount_point}")
        else:
            notebookutils.fs.mount(source_uri, mount_point)
            print(f"Mounted {source_uri} at {mount_point}")
        
        # Step 2: Process data using local file system
        mount_path = notebookutils.fs.getMountPath(mount_point)
        
        with open(f"{mount_path}/data/input.txt", "r") as f:
            data = f.read()
        
        processed = data.upper()
        
        with open(f"{mount_path}/output/result.txt", "w") as f:
            f.write(processed)
        
        print("Processing complete")
        
    finally:
        # Step 3: Always unmount to release resources
        notebookutils.fs.unmount(mount_point)
        print(f"Unmounted {mount_point}")

process_with_mount(
    "abfss://mycontainer@mystorage.dfs.core.windows.net",
    "/temp_mount"
)

Известные ограничения

• Подключения — это конфигурации уровня задания. Используйте API mounts, чтобы проверить, существует ли точка монтирования или доступна ли она.
• Отключение не происходит автоматически. Когда приложение завершит работу, вызовите API отключения в коде, чтобы освободить место на диске. В противном случае точка подключения остается на узле после завершения выполнения приложения.
• Подключение учетной записи хранения ADLS 1-го поколения не поддерживается.

Связанный контент

• NotebookUtils для Fabric
• Служебные программы файловой системы NotebookUtils