Клиентская библиотека общей папки службы хранилища Azure для Python

Статья
11/07/2023

Хранилище общих папок Azure предлагает полностью управляемые общие папки в облаке, которые доступны по стандартному отраслевому протоколу SMB. Общие ресурсы службы файлов Azure можно одновременно подключить к облачным или локальным развертываниям Windows, Linux и macOS. Кроме того, общие ресурсы службы "Файлы Azure" можно кэшировать на серверах Windows Server с помощью службы "Синхронизация файлов Azure" для быстрого доступа из расположения, где используются данные.

Файловые ресурсы Azure можно использовать следующим образом.

Замена или дополнение локальных файловых серверов
Приложения lift-and-shift
Упрощение облачной разработки с помощью общих параметров приложения, общей папки диагностики и средств разработки, тестирования и отладки

Начало работы

Предварительные требования

Для использования этого пакета требуется Python 3.7 или более поздней версии. Дополнительные сведения см. на странице политики поддержки версий пакета Azure SDK для Python.
Для использования этого пакета необходимо иметь подписку Azure и учетную запись хранения Azure .

Установка пакета

Установите клиентую библиотеку файлового ресурса службы хранилища Azure для Python с помощью pip:

pip install azure-storage-file-share

Создание учетной записи хранения

Если вы хотите создать учетную запись хранения, можно использовать портал Azure, Azure PowerShell или Azure CLI:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Создание клиента

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

from azure.storage.fileshare import ShareServiceClient

service = ShareServiceClient(account_url="https://<my-storage-account-name>.file.core.windows.net/", credential=credential)

Поиск URL-адреса учетной записи

URL-адрес службы файлов учетной записи хранения можно найти с помощью портала Azure, Azure PowerShell или Azure CLI:

# Get the file service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.file"

Типы учетных данных

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

Чтобы использовать маркер подписанного URL-адреса (SAS), укажите маркер в виде строки. Если URL-адрес учетной записи содержит маркер SAS, опустите параметр учетных данных. Вы можете создать маркер SAS на портале Azure в разделе "Подписанный URL-адрес" или использовать одну из generate_sas() функций для создания маркера SAS для учетной записи хранения, общей папки или файла:
```
from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)
```
Чтобы использовать общий ключ учетной записи хранения (ключ учетной записи или ключ доступа), укажите ключ в виде строки. Его можно найти на портале Azure в разделе "Ключи доступа" или с помощью следующей команды Azure CLI:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Используйте ключ в качестве параметра учетных данных для проверки подлинности клиента:
```
from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")
```

Создание клиента из строка подключения

В зависимости от варианта использования и метода авторизации вы можете инициализировать экземпляр клиента с помощью строка подключения хранилища, а не указывать URL-адрес учетной записи и учетные данные отдельно. Для этого передайте строка подключения хранилища в метод класса клиентаfrom_connection_string:

from azure.storage.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.from_connection_string(conn_str=connection_string)

Строка подключения учетной записи хранения можно найти на портале Azure в разделе "Ключи доступа" или с помощью следующей команды CLI:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Основные понятия

Служба общих папок Azure состоит из следующих компонентов:

Сама учетная запись хранения
Общая папка в учетной записи хранения
Необязательная иерархия каталогов в общей папке
Файл в общей папке, размер которого может составлять до 1 ТиБ.

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

Асинхронные клиенты

Эта библиотека включает полный асинхронный API, поддерживаемый в Python 3.5 и более поздних версий. Чтобы использовать его, необходимо сначала установить асинхронный транспорт, например aiohttp. Дополнительные сведения см. в документации по azure-core .

Асинхронные клиенты и учетные данные должны быть закрыты, если они больше не нужны. Эти объекты являются диспетчерами асинхронного контекста и определяют асинхронные close методы.

Клиенты

Для взаимодействия с различными компонентами службы файловых ресурсов предоставляются четыре разных клиента:

ShareServiceClient — этот клиент представляет взаимодействие с самой учетной записью хранения Azure и позволяет получить предварительно настроенные экземпляры клиента для доступа к общим папкам. Он предоставляет операции по извлечению и настройке свойств службы, а также перечислению, созданию и удалению общих папок в учетной записи. Чтобы выполнить операции с определенной общей папкой, получите клиент с помощью get_share_client метода .
ShareClient — этот клиент представляет взаимодействие с определенной общей папкой (которая еще не существует) и позволяет получить предварительно настроенные экземпляры клиента для доступа к каталогам и файлам в них. Он предоставляет операции по созданию, удалению, настройке или созданию моментальных снимков общей папки, а также включает операции по созданию и перечислению содержимого каталогов в ней. Чтобы выполнить операции с определенным каталогом или файлом, получите клиент с помощью get_directory_client методов или get_file_client .
ShareDirectoryClient — этот клиент представляет взаимодействие с определенным каталогом (который еще не должен существовать). Он предоставляет операции для создания, удаления или перечисления содержимого немедленного или вложенного подкаталога, а также включает операции по созданию и удалению файлов в нем. Для операций, связанных с определенным подкаталогом или файлом, клиент для этой сущности также можно получить с помощью get_subdirectory_client функций и get_file_client .
ShareFileClient — этот клиент представляет взаимодействие с определенным файлом (который еще не должен существовать). Он предоставляет операции по отправке, скачиванию, созданию, удалению и копированию файла.

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

Примеры

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

Создание общей папки
Отправка файла
Скачивание файла
Вывод списка содержимого каталога

Создание общей папки для хранения файлов

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

Создание общей папки с помощью асинхронного клиента

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

Отправка файла

Отправка файла в общую папку

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

Асинхронная отправка файла

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

Скачивание файла

Скачивание файла из общей папки

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

Асинхронное скачивание файла

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

Вывод списка содержимого каталога

Вывод списка всех каталогов и файлов в родительском каталоге

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

Асинхронный вывод списка содержимого каталога

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

Дополнительная настройка

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

Конфигурация политики повторных попыток

Используйте следующие аргументы ключевое слово при создании экземпляра клиента для настройки политики повторных попыток:

retry_total (int): общее количество разрешенных повторных попыток. Имеет приоритет над другими счетчиками. retry_total=0 Передайте, если вы не хотите повторять запросы. Значение по умолчанию равно 10.
retry_connect (int): количество ошибок, связанных с подключением, для выполнения повторных попыток. Значение по умолчанию — 3.
retry_read (int): количество повторных попыток при чтении ошибок. Значение по умолчанию — 3.
retry_status (int): количество повторных попыток с использованием недопустимых кодов состояния. Значение по умолчанию — 3.
retry_to_secondary (bool): следует ли повторить запрос в дополнительный, если это возможно. Это должно быть включено только для учетных записей RA-GRS, и могут обрабатываться потенциально устаревшие данные. По умолчанию — False.

Другая конфигурация клиента / на операцию

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

Аргументы ключевое слово клиента:

connection_timeout (int): количество секунд, в течение которых клиент будет ожидать установления подключения к серверу. Значение по умолчанию — 20 секунд.
read_timeout (int): количество секунд, в течение которых клиент будет ожидать ответа от сервера между последовательными операциями чтения. Это время ожидания на уровне сокета, на который не влияет общий размер данных. Время ожидания чтения на стороне клиента будет автоматически повторяться. Значение по умолчанию — 60 секунд.
transport (Любой): предоставленный пользователем транспорт для отправки HTTP-запроса.

Аргументы ключевое слово для каждой операции:

raw_response_hook (вызываемый): данный обратный вызов использует ответ, возвращенный службой.
raw_request_hook (вызываемый): данный обратный вызов использует запрос перед отправкой в службу.
client_request_id (str): необязательный идентификатор запроса, указанный пользователем.
user_agent (str): добавляет пользовательское значение в заголовок агента пользователя, отправляемый вместе с запросом.
logging_enable (bool): включает ведение журнала на уровне DEBUG. Значение по умолчанию — False. Можно также передать на уровне клиента, чтобы включить его для всех запросов.
logging_body (bool): включает ведение журнала текста запроса и ответа. Значение по умолчанию — False. Можно также передать на уровне клиента, чтобы включить его для всех запросов.
headers (dict): передать пользовательские заголовки в качестве пар "ключ — значение". Например, headers={'CustomValue': value}

Устранение неполадок

Общие сведения

Клиенты файлов хранилища вызывают исключения, определенные в Azure Core.

Этот список можно использовать для ссылки на перехват вызванных исключений. Чтобы получить конкретный код ошибки исключения, используйте error_code атрибут , т. е exception.error_code. .

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и неотредактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable :

import sys
import logging
from azure.storage.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = ShareServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Аналогичным образом с помощью параметра logging_enable можно включить подробное журналирование для отдельной операции (даже если этот режим не включен в клиенте):

service_client.get_service_properties(logging_enable=True)

Дальнейшие действия

Больше примеров кода

Начните работу с примерами общих папок.

В репозитории GitHub пакета SDK для Python доступно несколько примеров пакета SDK для общих папок хранилища. В этих примерах приведен пример кода для дополнительных сценариев, часто встречающихся при работе с общей папкой хранилища:

file_samples_hello_world.py (асинхронная версия) — примеры, приведенные в этой статье:
- Создание клиента
- Создание общей папки
- Отправка файла
file_samples_authentication.py (асинхронная версия) — примеры проверки подлинности и создания клиента:
- Из строка подключения
- Из общего ключа доступа
- Из маркера подписанного URL-адреса
file_samples_service.py (асинхронная версия) — примеры взаимодействия со службой файлов:
- Получение и задание свойств службы
- Создание, перечисление и удаление общих папок
- Получение клиента общей папки
file_samples_share.py (асинхронная версия) — примеры взаимодействия с общими папками:
- Создание моментального снимка общего ресурса
- Настройка квоты и метаданных общего ресурса
- Перечисление каталогов и файлов
- Получение каталога или файлового клиента для взаимодействия с определенной сущностью
file_samples_directory.py (асинхронная версия) — примеры взаимодействия с каталогами:
- Создание каталога и добавление файлов
- Создание и удаление подкаталогов
- Получение клиента подкаталога
file_samples_client.py (асинхронная версия) — примеры взаимодействия с файлами:
- Создание, отправка, скачивание и удаление файлов
- Копирование файла из URL-адреса

Дополнительная документация

Более подробную документацию по хранилищу файлового ресурса Azure см. в документации по хранилищу общих папок Azure на docs.microsoft.com.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

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

Начало работы

Предварительные требования

Установка пакета

Создание учетной записи хранения

Создание клиента

Поиск URL-адреса учетной записи

Типы учетных данных

Создание клиента из строка подключения

Основные понятия

Асинхронные клиенты

Клиенты

Примеры

Отправка файла

Скачивание файла

Вывод списка содержимого каталога

Дополнительная настройка

Конфигурация политики повторных попыток

Другая конфигурация клиента / на операцию

Устранение неполадок

Общие сведения

Ведение журнала

Дальнейшие действия

Больше примеров кода

Дополнительная документация

Участие

Дополнительные ресурсы

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

Клиентская библиотека общей папки службы хранилища Azure для Python — версия 12.15.0

Начало работы

Предварительные требования

Установка пакета

Создание учетной записи хранения

Создание клиента

Поиск URL-адреса учетной записи

Типы учетных данных

Создание клиента из строка подключения

Основные понятия

Асинхронные клиенты

Клиенты

Примеры

создание файлового ресурса;

Отправка файла

Скачивание файла

Вывод списка содержимого каталога

Дополнительная настройка

Конфигурация политики повторных попыток

Другая конфигурация клиента / на операцию

Устранение неполадок

Общие сведения

Ведение журнала

Дальнейшие действия

Больше примеров кода

Дополнительная документация

Участие

Дополнительные ресурсы