Клиентская библиотека BLOB-объектов службы хранилища Azure для Python — версия 12.19.0

Статья
11/07/2023

Хранилище BLOB-объектов Azure — это решение корпорации Майкрософт для хранения объектов в облаке. Хранилище BLOB-объектов оптимизировано для хранения больших объемов неструктурированных данных, например текстовых или двоичных данных.

Хранилище BLOB-объектов идеально подходит для следующих целей:

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

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

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

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

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

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

pip install azure-storage-blob

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

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

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

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

from azure.storage.blob import BlobServiceClient

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

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

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

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

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

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

Чтобы использовать учетные данные маркера Azure Active Directory (AAD), укажите экземпляр нужного типа учетных данных, полученных из библиотеки azure-identity . Например, для проверки подлинности клиента можно использовать DefaultAzureCredential .

Для этого требуется некоторая начальная настройка:
- Установка azure-identity
- Регистрация нового приложения AAD и предоставление разрешений на доступ к службе хранилища Azure
- Предоставление доступа к данным BLOB-объектов Azure с помощью RBAC на портале Azure
- Задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET
Используйте возвращенные учетные данные маркера для проверки подлинности клиента:
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```
Чтобы использовать маркер подписанного URL-адреса (SAS), укажите маркер в виде строки. Если URL-адрес учетной записи содержит маркер SAS, опустите параметр учетных данных. Вы можете создать маркер SAS на портале Azure в разделе "Подписанный URL-адрес" или использовать одну из generate_sas() функций для создания маркера SAS для учетной записи хранения, контейнера или большого двоичного объекта:
```
from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, 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)
)

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

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Используйте ключ в качестве параметра учетных данных для проверки подлинности клиента:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
Если вы используете настраиваемый URL-адрес (то есть URL-адрес не в этом формате <my_account_name>.blob.core.windows.net), создайте экземпляр клиента, используя указанные ниже учетные данные:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
Чтобы использовать анонимный общий доступ на чтение, просто опустите параметр учетных данных.

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

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

from azure.storage.blob import BlobServiceClient

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

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

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

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

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

Сама учетная запись хранения
Контейнер в учетной записи хранения
Большой двоичный объект в контейнере

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

Клиенты

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

BlobServiceClient — этот клиент представляет взаимодействие с самой учетной записью хранения Azure и позволяет получить предварительно настроенные экземпляры клиента для доступа к контейнерам и BLOB-объектам внутри. Он предоставляет операции по получению и настройке свойств учетной записи, а также перечислению, созданию и удалению контейнеров в учетной записи. Чтобы выполнить операции с определенным контейнером или большим двоичным объектом, получите клиент с помощью get_container_client методов или get_blob_client .
ContainerClient — этот клиент представляет взаимодействие с определенным контейнером (который еще не должен существовать) и позволяет получить предварительно настроенные экземпляры клиента для доступа к большим двоичным объектам внутри. Он предоставляет операции по созданию, удалению или настройке контейнера и включает операции по перечислению, отправке и удалению больших двоичных объектов в нем. Чтобы выполнить операции с определенным BLOB-объектом в контейнере, получите клиент с помощью get_blob_client метода .
BlobClient — этот клиент представляет взаимодействие с определенным BLOB-объектом (который еще не должен существовать). Он предоставляет операции для отправки, скачивания, удаления и создания моментальных снимков большого двоичного объекта, а также конкретных операций для каждого типа BLOB-объекта.
BlobLeaseClient — этот клиент представляет взаимодействие аренды с ContainerClient или BlobClient. Он предоставляет операции по приобретению, продлению, освобождению, изменению и прерыванию аренды указанного ресурса.

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

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

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

Типы BLOB-объектов

После инициализации клиента можно выбрать один из разных типов BLOB-объектов:

Блочные BLOB-объекты хранят текстовые и двоичные данные примерно до 4,75 ТиБ. Блочные BLOB-объекты состоят из блоков данных, которыми можно управлять по отдельности.
Добавочные BLOB-объекты состоят из блоков, как и блочные, но оптимизированы для операций добавления. Добавление BLOB-объектов идеально подходит для таких сценариев, как ведение журнала данных с виртуальных машин
Страничные BLOB-объекты используются для хранения файлов прямого доступа объемом до 8 ТиБ. Страничные BLOB-объекты хранят файлы виртуальных жестких дисков (VHD) и служат дисками для виртуальных машин Azure

Примеры

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

Создание контейнера
Отправка большого двоичного объекта
Скачивание большого двоичного объекта
Перечисление больших двоичных объектов

Обратите внимание, что перед отправкой или загрузкой большого двоичного объекта необходимо создать контейнер.

Создание контейнера

Создайте контейнер, из которого можно отправлять или скачивать большие двоичные объекты.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

Отправка большого двоичного объекта с помощью асинхронного клиента

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Отправка большого двоичного объекта

Отправка большого двоичного объекта в контейнер

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Отправка большого двоичного объекта с помощью асинхронного клиента

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Скачивание большого двоичного объекта

Скачивание большого двоичного объекта из контейнера

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

Асинхронное скачивание большого двоичного объекта

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Перечисление больших двоичных объектов

Вывод списка больших двоичных объектов в контейнере

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

Асинхронный список больших двоичных объектов

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

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

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

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

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

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.

Конфигурация шифрования

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

require_encryption (логическое значение). Если задано значение True, будет принудительно шифровать объекты и расшифровывать их.
encryption_version (str): указывает используемую версию шифрования. Текущие параметры — или '2.0''1.0' , а значение по умолчанию — '1.0'. Версия 1.0 является устаревшей, поэтому настоятельно рекомендуется использовать версию 2.0.
key_encryption_key (объект). Предоставленный пользователем ключ-шифрование-ключ. Экземпляр должен реализовывать следующие методы:
- wrap_key(key)--обертывает указанный ключ с помощью алгоритма по выбору пользователя.
- get_key_wrap_algorithm()--возвращает алгоритм, используемый для оболочки указанного симметричного ключа.
- get_kid()--возвращает строковый идентификатор ключа для этого ключа шифрования ключа.
key_resolver_function (вызываемый): предоставленный пользователем сопоставитель ключей. Использует строку kid для возврата ключа шифрования ключа, реализующего интерфейс, определенный выше.

Другая конфигурация клиента или каждой операции

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

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

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

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

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

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

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

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

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

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

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

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

import sys
import logging
from azure.storage.blob import BlobServiceClient

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

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

service_client.get_service_stats(logging_enable=True)

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

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

Начните работу с примерами blob-объектов.

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

blob_samples_container_access_policy.py (асинхронная версия) — примеры настройки политик Доступа:
- Настройка политики доступа для контейнера
blob_samples_hello_world.py (асинхронная версия) — примеры распространенных задач больших двоичных объектов хранилища:
- Настройка контейнера
- Создание блока, страницы или добавочного BLOB-объекта
- Отправка больших двоичных объектов
- Скачивание больших двоичных объектов
- удаление больших двоичных объектов.
blob_samples_authentication.py (асинхронная версия) — примеры проверки подлинности и создания клиента:
- Из строка подключения
- Из общего ключа доступа
- Из маркера подписанного URL-адреса
- Из Active Directory
blob_samples_service.py (асинхронная версия) — примеры взаимодействия со службой BLOB-объектов:
- Получение данных об учетной записи
- Получение и задание свойств службы
- Получение статистики службы
- Создание, перечисление и удаление контейнеров
- Получение клиента большого двоичного объекта или контейнера
blob_samples_containers.py (асинхронная версия) — примеры взаимодействия с контейнерами:
- Создание контейнера и удаление контейнеров
- Настройка метаданных для контейнеров
- Получение свойств контейнера
- Получение аренды контейнера
- Настройка политики доступа для контейнера
- Отправка, перечисление и удаление BLOB-объектов в контейнере
- Получение клиента BLOB-объекта для взаимодействия с определенным BLOB-объектом
blob_samples_common.py (асинхронная версия) — примеры, общие для всех типов BLOB-объектов:
- Создание моментального снимка
- Удаление snapshot большого двоичного объекта
- Обратимое удаление большого двоичного объекта
- Отмена удаления большого двоичного объекта
- Получение аренды большого двоичного объекта
- Копирование большого двоичного объекта из URL-адреса
blob_samples_directory_interface.py — примеры взаимодействия с хранилищем BLOB-объектов, как если бы это был каталог в файловой системе:
- Копирование (отправка или скачивание) одного файла или каталога
- Вывод списка файлов или каталогов на одном уровне или рекурсивно
- Удаление одного файла или рекурсивное удаление каталога

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

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

Участие

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

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

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