Разработка Azure Files с помощью Python

Узнайте, как разрабатывать приложения Python, использующие Azure Files для хранения данных. Azure Files — это управляемая служба общих файлов в облаке. Он обеспечивает полностью управляемые файловые ресурсы, доступные через протоколы, соответствующие отраслевому стандарту, такие как блок сообщений сервера (SMB) и система сетевых файлов (NFS). Azure Files также предоставляет REST API для программного доступа к общим папкам.

В этой статье вы узнаете о различных подходах к разработке с помощью Azure Files в Python и о том, как выбрать подход, который лучше всего соответствует потребностям вашего приложения. Вы также узнаете, как создать базовое консольное приложение, которое взаимодействует с Azure Files ресурсами.

Сведения о разработке приложений Python с помощью Azure Files

Azure Files предлагает несколько способов для Python разработчиков для доступа к данным и управления ресурсами в Azure Files. Следующая таблица перечисляет подходы, описывает, как они работают, и предоставляет рекомендации о том, когда использовать каждый из них.

Подход Принцип работы Когда следует использовать
Стандартные библиотеки ввода-вывода файлов Использует вызовы API уровня ОС через файловые хранилища Azure, подключаемые с помощью SMB или NFS. При подключении общей папки с помощью SMB/NFS можно использовать библиотеки ввода-вывода файлов для языка программирования или платформы, например os и io для Python. У вас есть бизнес-приложения с существующим кодом, использующим стандартный файловый ввод-вывод, и вы не хотите переписывать код для работы с файловым хранилищем Azure.
FileREST API Напрямую вызывает конечные точки HTTPS для взаимодействия с данными, хранящимися в Azure Files. Обеспечивает программное управление ресурсами файлового обмена. Azure SDK предоставляет клиентскую библиотеку File Shares (azure-storage-file-share), которая строится на основе API FileREST и позволяет взаимодействовать с операциями API FileREST, используя знакомые парадигмы языка программирования Python. Вы создаете облачные службы и приложения с дополнительными значениями для клиентов, и вы хотите использовать расширенные функции, недоступные через библиотеки ввода-вывода Python файлов.
Поставщик ресурсов хранилища REST API Использует Azure Resource Manager (ARM) для управления учетными записями хранения и общими папками. Выполняет вызов конечных точек REST API для различных операций управления ресурсами. Вашему приложению или службе необходимо выполнять задачи управления ресурсами, такие как создание, удаление или обновление учетных записей хранения или файловых ресурсов.

Общие сведения об этих подходах см. в разделе Overview разработки приложений с помощью Azure Files.

В этой статье основное внимание уделяется работе с ресурсами Azure Files с помощью следующих подходов:

Предпосылки

Настройка проекта

В этом разделе описывается подготовка проекта для работы с Azure Files.

В каталоге проекта установите пакеты в зависимости от потребностей приложения с помощью pip install команды. Этот пример демонстрирует, как установить клиентская библиотека для Azure File Shares, клиентская библиотека для управления хранилищами и библиотека Azure Identity. Пакет azure-identity необходим для подключения без пароля к службам Azure.

pip install azure-identity
pip install azure-storage-file-share
pip install azure-mgmt-resource
pip install azure-mgmt-storage

Откройте файл кода и добавьте необходимые инструкции импорта.

Если вы планируете использовать библиотеки Python os и io, добавьте следующее в файл .py:

import os
import io

Если вы планируете использовать клиентную библиотеку общих папок Azure Storage, добавьте следующую команду в файл .py:

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareClient, ShareDirectoryClient, ShareFileClient

Если вы планируете использовать библиотеки управления Azure Storage, добавьте следующее в файл .py:

from azure.identity import DefaultAzureCredential
from azure.mgmt.resource import ResourceManagementClient
from azure.mgmt.storage import StorageManagementClient

Работа с Azure Files с помощью библиотек ввода-вывода Python файлов

Стандартные библиотеки ввода-вывода файлов являются наиболее распространенным способом доступа к ресурсам Azure Files и работы с ними. Когда вы монтируете общий ресурс, используя SMB или NFS, ваша операционная система перенаправляет запросы API для локальной файловой системы. Этот подход позволяет использовать стандартные библиотеки ввода-вывода файлов, такие как os или io, для взаимодействия с файлами и каталогами в общей папке.

Рассмотрите возможность использования библиотек ввода-вывода Python, если вашему приложению это требуется.

  • Совместимость с приложениями: Идеально подходит для бизнес-приложений с существующим кодом, который уже использует библиотеки ввода-вывода Python файлов. Чтобы приложение работало с общей папкой Azure, вам не нужно переписать код.
  • Простота использования: Библиотеки ввода-вывода Python хорошо известны разработчикам и легко используются. Ключевое предложение Azure Files заключается в том, что он предоставляет собственные API файловой системы через SMB и NFS.

В этом разделе описано, как использовать библиотеки ввода-вывода Python файлов для работы с Azure Files ресурсами.

Для получения дополнительной информации и примеров, обратитесь к следующим ресурсам:

  • библиотеки Python для операций ввода-вывода файла: os и io

Подключить общий доступ к файлам

Чтобы использовать Python-библиотеки для ввода-вывода файлов, необходимо сначала подключить общую папку. Смотрите следующие ресурсы, чтобы получить руководство по подключению файловой системы с использованием SMB или NFS.

В этой статье мы используем следующий путь для ссылки на подключенную общую папку SMB на Windows:

file_share_path = "Z:\\file-share"

Пример. Подключение к общей папке и перечисление каталогов с помощью библиотек ввода-вывода Python файлов

Пример кода ниже показывает, как подключиться к общей папке и вывести список каталогов в этой папке.

import os

def enumerate_directories(path):
    try:
        # Get all directories in the specified path
        dirs = [d for d in os.listdir(path) if os.path.isdir(os.path.join(path, d))]
        
        # Print each directory name
        for dir_name in dirs:
            print(f"{dir_name}")
            
        print(f"{len(dirs)} directories found.")
    except (PermissionError, FileNotFoundError, OSError) as ex:
        print(f"Error: {ex}")

#Example usage
file_share_path = "Z:\\file-share"
enumerate_directories(file_share_path)

Пример: Запись в файл в общем доступе с помощью библиотек ввода-вывода файлов Python

Пример кода ниже показывает, как записывать и добавлять текст в файл:

import os

def write_to_file(file_share_path, file_name):
    # First line of text with platform-appropriate line ending
    text_to_write = "First line" + os.linesep
    
    # Combine the file share path and filename
    file_path = os.path.join(file_share_path, file_name)
    
    # Write initial text to file (overwrites if file exists)
    with open(file_path, 'w') as file:
        file.write(text_to_write)
    
    # Text to append
    text_to_append = ["Second line", "Third line"]
    
    # Append lines to the file
    with open(file_path, 'a') as file:
        file.write(os.linesep.join(text_to_append) + os.linesep)

# Example usage
file_share_path = "Z:\\file-share"
write_to_file(file_share_path, "test.txt")

Пример. Перечисление списков управления доступом к файлам с помощью библиотек ввода-вывода Python

В следующем примере кода показано, как перечислить базовые списки управления доступом (ACL) для файла:

import os
import stat

def enumerate_file_acls(file_path):
    try:
        # Get file stats
        file_stat = os.stat(file_path)
        
        # Get permissions in octal format
        permissions_octal = oct(stat.S_IMODE(file_stat.st_mode))
        
        print(f"File: {file_path}")
        print(f"Permissions (octal): {permissions_octal}")
        
        # Interpret permissions in a human-readable format
        permissions = ""
        permissions += "r" if file_stat.st_mode & stat.S_IRUSR else "-"
        permissions += "w" if file_stat.st_mode & stat.S_IWUSR else "-"
        permissions += "x" if file_stat.st_mode & stat.S_IXUSR else "-"
        permissions += "r" if file_stat.st_mode & stat.S_IRGRP else "-"
        permissions += "w" if file_stat.st_mode & stat.S_IWGRP else "-" 
        permissions += "x" if file_stat.st_mode & stat.S_IXGRP else "-"
        permissions += "r" if file_stat.st_mode & stat.S_IROTH else "-"
        permissions += "w" if file_stat.st_mode & stat.S_IWOTH else "-"
        permissions += "x" if file_stat.st_mode & stat.S_IXOTH else "-"
        
        print(f"Permissions (symbolic): {permissions}")
        
        print(f"Owner ID: {file_stat.st_uid}")
        print(f"Group ID: {file_stat.st_gid}")
        print("Note: For detailed Windows ACLs, you may need a specialized library.")
        
    except FileNotFoundError:
        print(f"Error: File '{file_path}' not found.")
    except PermissionError:
        print(f"Error: Permission denied for '{file_path}'.")
    except Exception as e:
        print(f"Error: {e}")

# Example usage
file_share_path = "Z:\\file-share"
file_name = "test.txt"
file_path = os.path.join(file_share_path, file_name)

enumerate_file_acls(file_path)

Работа с данными Azure Files с помощью клиентской библиотеки общих папок для Python

API FileREST предоставляет программный доступ к Azure Files. Это позволяет вам вызывать HTTPS-эндпоинты для выполнения операций с файловыми хранилищами, каталогами и файлами. API FileREST разработан для обеспечения высокой масштабируемости и продвинутых функций, которые могут быть недоступны через родные протоколы. Azure SDK предоставляет клиентские библиотеки, такие как клиентская библиотека общих папок для Python, которая основана на API FileREST.

Рассмотрите возможность использования FileREST API и клиентской библиотеки File Share, если вашему приложению требуется:

  • Расширенные функции: Получите доступ к операциям и функциям, которые недоступны через родные протоколы.
  • Пользовательская облачная интеграция: пользовательские службы, такие как резервное копирование, антивирус или управление данными, которые взаимодействуют напрямую с Azure Files.
  • Оптимизация производительности: Используйте преимущества производительности в масштабных сценариях, применяя операции канала данных.

API FileREST моделирует Azure Files как иерархию ресурсов и рекомендуется для выполнения операций на уровне каталога или файла. Следует отдавать предпочтение REST API поставщика ресурсного хранилища для операций, выполняемых на уровне файлового сервиса или файлового ресурса.

В этом разделе вы узнаете, как использовать клиентскую библиотеку для работы с ресурсами Azure Files.

Для получения дополнительной информации и примеров, обратитесь к следующим ресурсам:

Авторизация доступа и создание клиента

Чтобы подключить приложение к Azure Files, создайте объект ShareClient. Этот объект является отправной точкой для работы с ресурсами Azure Files. Приведенные ниже примеры кода показывают, как создать объект ShareClient, используя различные механизмы авторизации.

Для авторизации с помощью Microsoft Entra ID необходимо использовать учетную запись безопасности. Тип необходимого идентификатора безопасности зависит от того, где запускается ваше приложение. Используйте эту таблицу в качестве справочника.

Где выполняется приложение Принцип безопасности Руководство
Локальный компьютер (разработка и тестирование) Принципал службы Чтобы узнать, как зарегистрировать приложение, настроить группу Microsoft Entra, назначить роли и сконфигурировать переменные среды, см. в разделе Авторизация доступа с помощью учетных записей служб разработчиков
Локальный компьютер (разработка и тестирование) Удостоверение пользователя Сведения о настройке группы Microsoft Entra, назначении ролей и входе в Azure см. в статье Authorize access с помощью учетных данных разработчика
Размещено в Azure Манажируемая идентичность Чтобы узнать, как включить управляемое удостоверение и назначить роли, см. статью Authorize access from Azure-hosted apps using a managed identity
Размещенные вне Azure (например, локальные приложения) Принципал службы Сведения о регистрации приложения, назначении ролей и настройке переменных среды см. в статье "Авторизация доступа из локальных приложений с помощью субъекта-службы приложений"

Чтобы работать с примерами кода в этой статье, назначьте встроенную роль Azure RBAC Storage File Data Privileged Contributor субъекту безопасности. Эта роль предоставляет полный доступ на чтение, запись, изменение ACL и удаление всех данных в ресурсах для всех настроенных учетных записей хранилища, независимо от уровня разрешений NTFS для файлов и каталогов. Дополнительные сведения см. в разделе Доступ к файловым ресурсам Azure с помощью Microsoft Entra ID и OAuth в Azure Files через REST API.

Авторизация доступа с помощью DefaultAzureCredential

Простой и безопасный способ авторизации доступа и подключения к Azure Files заключается в получении маркера OAuth путем создания экземпляра DefaultAzureCredential. Затем вы можете использовать этот учетный данные, чтобы создать объект ShareClient.

Следующий пример создает объект ShareClient, авторизованный с использованием DefaultAzureCredential, затем создает объект ShareDirectoryClient для работы с каталогом в общей папке.

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareClient

account_name = "<account-name>"
share_name = "<share-name>"

# Create the share client using DefaultAzureCredential
share_client = ShareClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=share_name,
    credential=DefaultAzureCredential(),
    # When using a token credential, you MUST specify a token_intent
    token_intent='backup'
)

# Get a reference to a directory in the share
directory_client = share_client.get_directory_client("sample-directory")

Если вы точно знаете, какой тип учетных данных используется для проверки подлинности пользователей, вы можете получить маркер OAuth с помощью других классов в клиентской библиотеке Azure Identity для Python. Эти классы являются производными от класса TokenCredential .

Чтобы узнать больше о каждом из этих механизмов авторизации, см. Выберите, как авторизовать доступ к данным файла.

Пример: Копирование файлов с использованием клиентской библиотеки File Shares

Вы можете копировать файлы внутри общего ресурса или между общими ресурсами, используя следующий метод:

Вы можете скопировать файл в конечный блоб, используя следующий метод из объекта BlobClient.

Следующий пример кода показывает, как скопировать файл в файл в другой файловой области:

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareFileClient

# Define storage account parameters
account_name = "<account-name>"
src_share_name = "src-file-share"
dest_share_name = "dest-file-share"
src_file_path = "src/path/to/file"
dest_file_path = "dest/path/to/file"

# Create token credential
token_credential = DefaultAzureCredential()

# Create source file client
src_file_client = ShareFileClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=src_share_name,
    file_path=src_file_path,
    credential=token_credential,
    token_intent='backup'
)

# Create destination file client
dest_file_client = ShareFileClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=dest_share_name,
    file_path=dest_file_path,
    credential=token_credential,
    token_intent='backup'
)

# Copy the file from the source share to the destination share
copy_operation = dest_file_client.start_copy_from_url(src_file_client.url)

Пример: Аренда файла с использованием клиентской библиотеки File Shares

Процесс аренды файла создает его блокировку, управляемую Azure через идентификатор аренды. Аренда предоставляет механизм для координации доступа к файлам через несколько клиентов в распределённой системе. Договор аренды на файл предоставляет исключительный доступ для записи и удаления. Чтобы узнать больше о состояниях и действиях аренды, см. Файл аренды.

Следующий пример кода показывает, как создать клиента аренды, получить аренду на файл с бесконечным сроком действия и освободить аренду.

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareFileClient, ShareLeaseClient

# Define storage account parameters
account_name = "<account-name>"
share_name = "sample-file-share"
file_path = "path/to/file"

# Create a DefaultAzureCredential for authentication
token_credential = DefaultAzureCredential()

# Create a ShareFileClient
file_client = ShareFileClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=share_name,
    file_path=file_path,
    credential=token_credential,
    token_intent='backup'
)

# Get a lease client for the file
lease_client = ShareLeaseClient(file_client)

# Acquire an infinite duration lease on the file
lease_info = lease_client.acquire()

# Do something with the file while it's leased
# ...

# Release the lease
lease_client.release()

При использовании как SMB, так и FileREST API, имейте в виду, что FileREST API использует арендаторы для управления блокировками файлов, тогда как SMB использует блокировки файловой системы, управляемые операционной системой. Чтобы узнать больше об управлении взаимодействиями блокировки файлов между SMB и FileREST API, смотрите Управление блокировками файлов.

Пример: Создание и перечисление снимков общего доступа с использованием библиотеки клиента File Shares

Снимки общего доступа — это копии общего ресурса файла в определенный момент времени только для чтения. Вы можете создать снимок общего файлового ресурса, а затем использовать этот снимок для доступа к данным в общем ресурсе на момент создания снимка. Вы также можете перечислить все снимки в общем доступе к файлам и удалить снимки общего ресурса.

В следующем примере кода показано, как создать моментальный снимок общего ресурса, перечислить моментальные снимки в общей папке и пройти по корневому каталогу в моментальном снимке общего ресурса:

from azure.storage.fileshare import ShareServiceClient, ShareDirectoryClient

def list_root_directory_snapshot(root_dir: ShareDirectoryClient):
    for item in root_dir.list_directories_and_files():
        if item["is_directory"]:
            print(f"Directory in snapshot: {item['name']}")
        else:
            print(f"File in snapshot: {item['name']}")

# Connection string with account key (required for share snapshots)
connection_string = "<connection-string>"

# Create service and share clients
share_service_client = ShareServiceClient.from_connection_string(connection_string)
share_name = "sample-file-share"
share_client = share_service_client.get_share_client(share_name)

# Create a snapshot
snapshot_info = share_client.create_snapshot()
print(f"Snapshot created: {snapshot_info['snapshot']}")

# List snapshots in a share
for share_item in share_service_client.list_shares(include_snapshots=True):
    if share_item["snapshot"]:
        print(f"Share: {share_item['name']} (Snapshot: {share_item['snapshot']})")

# List directories and files in a share snapshot
snapshot_timestamp = snapshot_info["snapshot"]
share_snapshot = share_service_client.get_share_client(share_name, snapshot=snapshot_timestamp)
root_dir = share_snapshot.get_directory_client("")

list_root_directory_snapshot(root_dir)

Примечание.

Токены OAuth, такие как полученные при использовании DefaultAzureCredential, не разрешены для операций с плоскостью данных на уровне общего доступа к файлам. Чтобы работать со снапшотами общего доступа, объект клиента должен быть авторизован с использованием ключа учетной записи. Объект ShareClient, созданный в этом примере кода, использует connection string, который включает ключ учетной записи.

Хранение ключей учетных записей или строк подключения представляет собой угрозу безопасности. Их следует использовать только в том случае, если проверка подлинности "Microsoft Entra" недоступна. Дополнительные сведения о безопасном авторизации доступа к хранилищу см. в статье Authorize access to data in Azure Storage.

Управление ресурсами Azure Files с помощью библиотек управления Azure Storage

Библиотеки управления Azure Storage основаны на REST API поставщика ресурсов Azure Storage. Поставщик ресурсов Azure Storage — это служба на основе Azure Resource Manager и поддерживает как декларативные (шаблоны), так и императивные (прямые вызовы API). REST API поставщика ресурсов Azure Storage предоставляет программный доступ к ресурсам Azure Storage, включая общие папки. Azure SDK предоставляет библиотеки управления, которые создаются на основе REST API поставщика ресурсов Azure Storage.

Рекомендуется использовать библиотеки управления для операций, выполняемых на уровне файлового сервиса или файлового обмена. В этом разделе описано, как использовать библиотеки управления Azure Storage для управления Azure Files ресурсами.

Пример. Создание общей папки с помощью библиотеки управления Azure Storage

В следующем примере кода показано, как создать объект ArmClient верхнего уровня, зарегистрировать поставщика ресурсов хранилища в подписке и создать общую папку с помощью библиотеки управления Azure Storage:

from azure.identity import DefaultAzureCredential
from azure.mgmt.resource import ResourceManagementClient, SubscriptionClient
from azure.mgmt.storage import StorageManagementClient
from azure.mgmt.storage.models import FileShare

# Create the credential for authentication
credential = DefaultAzureCredential()

# Define variables
subscription_id = "<subscription-id>"
resource_group_name = "<resource-group-name>"
storage_account_name = "<storage-account-name>"
share_name = "sample-file-share"

# Create clients
resource_client = ResourceManagementClient(credential, subscription_id)
subscription_client = SubscriptionClient(credential)
storage_client = StorageManagementClient(credential, subscription_id)

# Register Microsoft.Storage resource provider, if not already registered
provider = resource_client.providers.get('Microsoft.Storage')
if provider.registration_state == "NotRegistered":
    resource_client.providers.register('Microsoft.Storage')

# Create a file share
file_share = storage_client.file_shares.create(
    resource_group_name=resource_group_name,
    account_name=storage_account_name,
    share_name=share_name,
    file_share=FileShare(
        share_quota=1  # Share size in GiB
        # Add other file share properties here
    )
)

Свойства общей папки можно настроить с помощью FileShare класса. В предыдущем примере показано, как задать share_quota свойство. Дополнительные сведения см. в справочнике по классу StorageManagementClient .

Примечание.

Для выполнения операции регистрации требуются разрешения для следующего действия Azure RBAC: Microsoft.Storage/register/action. Это разрешение включено в предопределенные роли Contributor и Owner.

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

Приведенный ниже пример кода показывает, как перечислить файловые ресурсы и снимки в учетной записи хранения.

from azure.identity import DefaultAzureCredential
from azure.mgmt.storage import StorageManagementClient

# Create the credential for authentication
credential = DefaultAzureCredential()

# Define variables
subscription_id = "<subscription-id>"
resource_group_name = "<resource-group-name>"
storage_account_name = "<storage-account-name>"
expand = "snapshots"  # Include snapshots in the response

# Create storage management client
storage_client = StorageManagementClient(credential, subscription_id)

# List all file shares with their snapshots
file_shares = storage_client.file_shares.list(
    resource_group_name=resource_group_name,
    account_name=storage_account_name,
    expand=expand
)

# Iterate over the file shares and print them along with any snapshots
for share in file_shares:
    print(f"Resource name: {share.name}")
    if share.snapshot_time:
        print(f"Snapshot: {share.snapshot_time}")

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

Дополнительные сведения о разработке с помощью Azure Files см. в следующих ресурсах:

  • Last updated on