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

Клиентская библиотека службы Azure DataLake для Python — версия 12.14.0

  • Статья

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

Этот пакет предварительной версии для Python включает поддержку API ADLS 2-го поколения, доступную в пакете SDK для службы хранилища. В том числе:

  1. Новые операции на уровне каталога (создание, переименование, удаление) для учетной записи хранения с поддержкой иерархического пространства имен (HNS). Для учетных записей с поддержкой HNS операции переименования и перемещения являются атомарными.
  2. Операции, связанные с разрешениями (получение и установка списков управления доступом) для учетных записей с поддержкой иерархического пространства имен (HNS).

Исходный код | Пакет (PyPi) | Пакет (Conda) | Справочная документация по | APIДокументация по продукту | Образцы

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

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

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

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

pip install azure-storage-file-datalake --pre

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

Если вы хотите создать учетную запись хранения, можно использовать портал 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

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

Аутентификация клиента

Взаимодействие с хранилищем DataLake начинается с экземпляра класса DataLakeServiceClient. Вам потребуется существующая учетная запись хранения, ее URL-адрес и учетные данные для создания экземпляра объекта клиента.

Получение учетных данных

Чтобы проверить подлинность клиента, можно несколькими способами:

  1. Использование строки маркера SAS
  2. Использование общего ключа доступа учетной записи
  3. Использование учетных данных маркера из azure.identity

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

Вы можете опустить учетные данные, если URL-адрес учетной записи уже содержит маркер SAS.

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

После подготовки URL-адреса учетной записи и учетных данных можно создать DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

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

Хранилище DataLake предлагает четыре типа ресурсов:

  • учетная запись хранения;
  • Файловая система в учетной записи хранения
  • Каталог в файловой системе
  • Файл в файловой системе или в каталоге

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

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

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

Клиенты

Пакет SDK хранилища DataLake предоставляет четыре разных клиента для взаимодействия со службой DataLake:

  1. DataLakeServiceClient — этот клиент взаимодействует со службой DataLake на уровне учетной записи. Он предоставляет операции по извлечению и настройке свойств учетной записи, а также перечислению, созданию и удалению файловой системы в учетной записи. Для операций, связанных с определенной файловой системой, каталогом или файлом, клиенты для этих сущностей также можно получить с помощью get_file_clientфункций , get_directory_client или get_file_system_client .
  2. FileSystemClient — этот клиент представляет взаимодействие с определенной файловой системой, даже если эта файловая система еще не существует. Он предоставляет операции по созданию, удалению или настройке файловых систем, а также включает операции для перечисления путей в файловой системе, отправки и удаления файлов или каталогов в файловой системе. Для операций, связанных с определенным файлом, клиент также можно получить с помощью get_file_client функции . Для операций, связанных с определенным каталогом, клиент можно получить с помощью get_directory_client функции .
  3. DataLakeDirectoryClient — этот клиент представляет взаимодействие с определенным каталогом, даже если этот каталог еще не существует. Он предоставляет операции создания, удаления, переименования, получения свойств и задания свойств.
  4. DataLakeFileClient — этот клиент представляет взаимодействие с определенным файлом, даже если этот файл еще не существует. Он предоставляет операции с файлами для добавления данных, очистки данных, удаления, создания и чтения файлов.
  5. DataLakeLeaseClient — этот клиент представляет взаимодействие аренды с FileSystemClient, DataLakeDirectoryClient или DataLakeFileClient. Он предоставляет операции по приобретению, продлению, освобождению, изменению и прерыванию аренды ресурсов.

Примеры

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

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

Создайте DataLakeServiceClient, используя строка подключения к учетной записи хранения Azure.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

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

Отправьте файл в файловую систему.

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

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

Скачайте файл из файловой системы.

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

Перечисление путей

Выведите список путей в файловой системе.

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

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

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

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

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

  • retry_total (int): общее количество разрешенных повторных попыток. Имеет приоритет над другими счетчиками. retry_total=0 Передайте, если вы не хотите повторять запросы. Значение по умолчанию равно 10.
  • retry_connect (int): количество ошибок, связанных с подключением, для выполнения повторных попыток. Значение по умолчанию — 3.
  • retry_read (int): количество повторов при ошибках чтения. Значение по умолчанию — 3.
  • retry_status (int): количество повторных попыток при выполнении недопустимых кодов состояния. Значение по умолчанию — 3.
  • retry_to_secondary (логическое значение) — указывает, следует ли повторно выполнять запрос в дополнительный, если это возможно. Это должно быть включено только для учетных записей 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}

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

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

Клиенты DataLake Storage вызывают исключения, определенные в Azure Core.

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

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

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

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

import sys
import logging
from azure.storage.filedatalake import DataLakeServiceClient

# Create a logger for the 'azure.storage.filedatalake' SDK
logger = logging.getLogger('azure.storage')
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 = DataLakeServiceClient.from_connection_string("your_connection_string", logging_enable=True)

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

service_client.list_file_systems(logging_enable=True)

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

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

Начните работу с примерами Azure DataLake.

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

  • datalake_samples_access_control.py — Примеры распространенных задач хранилища DataLake:

    • Настройка файловой системы
    • Создание каталога
    • Установка и получение управления доступом для каталога
    • Создание файлов в каталоге
    • Установка и получение контроля доступа для каждого файла
    • Удаление файловой системы

  • datalake_samples_upload_download.py — Примеры распространенных задач хранилища DataLake:

    • Настройка файловой системы
    • Создать файл
    • Добавление данных в файл
    • Запись данных в файл
    • Скачивание отправленных данных
    • Удаление файловой системы

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

Таблица для сопоставления API ADLS 1-го поколения с ADLS 2-го поколения. Более подробную документацию rest по Data Lake Storage 2-го поколения см. в документации по Data Lake Storage 2-го поколения по docs.microsoft.com.

Участие

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

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

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