Поделиться через

Разработайте с помощью Python для «Azure Files»

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

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

Применимо к

Модель управления Модель выставления счетов Уровень медиа Избыточность Малый и средний бизнес (SMB) Сетевая файловая система (NFS)
Microsoft.Storage Настроенная версия 2 HDD (стандартный) Локальное (LRS) Да Нет
Microsoft.Storage Настроенная версия 2 HDD (стандартный) Зона (ZRS) Да Нет
Microsoft.Storage Настроенная версия 2 HDD (стандартный) Гео (GRS) Да Нет
Microsoft.Storage Настроенная версия 2 HDD (стандартный) GeoZone (GZRS) Да Нет
Microsoft.Storage Настроенная версия v1 SSD (премиум) Локальное (LRS) Да Нет
Microsoft.Storage Настроенная версия v1 SSD (премиум) Зона (ZRS) Да Нет
Microsoft.Storage Оплата по мере использования HDD (стандартный) Локальное (LRS) Да Нет
Microsoft.Storage Оплата по мере использования HDD (стандартный) Зона (ZRS) Да Нет
Microsoft.Storage Оплата по мере использования HDD (стандартный) Гео (GRS) Да Нет
Microsoft.Storage (Хранилище Microsoft) Оплата по мере использования HDD (стандартный) GeoZone (GZRS) Да Нет

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

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

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

Для получения общей информации об этих подходах см. Обзор разработки приложений с Azure Files.

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

Предпосылки

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

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

В каталоге проекта установите пакеты в зависимости от потребностей приложения с помощью pip install команды. В следующем примере показано, как установить клиентская библиотека общих папок Azure, клиентская библиотека управления хранилищами и библиотека удостоверений Azure. Пакет 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, добавьте в файл .py следующую команду:

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

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

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

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

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

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

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

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

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

  • Библиотеки Python для операций ввода-вывода файлов: ос и 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 с помощью клиентской библиотеки общих папок для Python

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

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

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

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

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

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

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

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

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

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

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

Авторизация доступа с помощью 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 для 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, созданный в этом примере кода, использует строку подключения, которая включает ключ учетной записи.

Хранение ключей учетных записей или строк подключения представляет собой угрозу безопасности. Вы должны использовать их только тогда, когда проверка подлинности Microsoft Entra недоступна. Чтобы узнать больше о безопасном хранении ключей учетных записей в Azure Key Vault, см. Информация о ключах учетных записей хранения, управляемых Azure Key Vault.

Управление ресурсами 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 для управления ресурсами 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, ознакомьтесь со следующими ресурсами: