Загрузка блочного blob-объекта с помощью Python

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

Сведения о отправке больших двоичных объектов с помощью асинхронных API см. в статье "Отправка больших двоичных объектов" асинхронно.

Требования

Подписка Azure — создайте бесплатную учетную запись.
Учетная запись хранения Azure — создайте такую учетную запись.
Python 3.8+

Настройка среды

Если у вас нет существующего проекта, в этом разделе показано, как настроить проект для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для Python. Дополнительные сведения см. в статье «Начало работы с хранилищем BLOB-объектов Azure и Python».

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

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

Установите следующие пакеты с помощью pip install:

pip install azure-storage-blob azure-identity

Добавьте инструкции импорта

Добавьте следующие утверждения import :

import io
import os
import uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobBlock, BlobClient, StandardBlobTier

Авторизация

Механизм авторизации должен иметь необходимые разрешения для отправки объекта blob. Для авторизации с помощью идентификатора Microsoft Entra (рекомендуется) требуется встроенная роль управления доступом на основе ролей (RBAC) Сотрудник данных BLOB-объектов хранилища или более высокая. Дополнительные сведения см. в руководстве по авторизации для Put Blob (REST API) и Put Block (REST API).

Создание клиентского объекта

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

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

Можно также создавать клиентские объекты для конкретных контейнеров или блобов как напрямую, так и из BlobServiceClient объекта. Дополнительные сведения о создании клиентских объектов и управлении ими см. в статье "Создание клиентских объектов и управление ими", взаимодействующих с ресурсами данных.

Отправка данных в блочный BLOB-объект

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

upload_blob

Этот метод создает новый BLOB из источника данных с автоматическим разбиением на части, что означает, что данные могут быть разделены на более мелкие фрагменты и загружены. Чтобы выполнить загрузку, клиентская библиотека может использовать либо Put Blob, либо серию вызовов Put Block, за которыми следует Put Block List. Это поведение зависит от общего размера объекта и способа установки параметров передачи данных.

Примечание.

Клиентские библиотеки службы хранилища Azure не поддерживают одновременную запись в один блоб. Если приложению требуется несколько процессов записи в один и тот же блоб, следует реализовать стратегию управления параллелизмом, чтобы обеспечить предсказуемое взаимодействие. Дополнительные сведения о стратегиях параллелизма см. в статье Управление параллелизмом в хранилище BLOB-объектов.

Загрузите блочный объект из локального пути к файлу

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

def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

Загрузите блочный BLOB-объект из потока

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

def upload_blob_stream(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    input_stream = io.BytesIO(os.urandom(15))
    blob_client.upload_blob(input_stream, blob_type="BlockBlob")

Отправка двоичных данных в блочный BLOB-объект

В следующем примере двоичные данные передаются в блочный BLOB-объект с помощью BlobClient объекта:

def upload_blob_data(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    data = b"Sample data for blob"

    # Upload the blob data - default blob type is BlockBlob
    blob_client.upload_blob(data, blob_type="BlockBlob")

Отправка блочного BLOB-объекта с тегами индекса

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

def upload_blob_tags(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    sample_tags = {"Content": "image", "Date": "2022-01-01"}
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, tags=sample_tags)

Отправка блочного BLOB-объекта с параметрами конфигурации

При загрузке блоба можно определить параметры конфигурации клиентской библиотеки. Эти параметры можно настроить для повышения производительности, повышения надежности и оптимизации затрат. В следующих примерах кода показано, как определить параметры конфигурации для отправки как на уровне метода, так и на уровне клиента при создании экземпляра BLOBClient. Эти параметры также можно настроить для экземпляра ContainerClient или экземпляра BlobServiceClient.

Указание параметров передачи данных для отправки

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

max_block_size — максимальный размер фрагмента для отправки блочного двоичного объекта. По умолчанию — 4 МиБ.
max_single_put_size — Если размер большого двоичного объекта меньше или равен max_single_put_size, большой двоичный объект отправляется с одним Put Blob запросом. Если размер объекта данных больше max_single_put_size или неизвестен, объект данных загружается частями с использованием Put Block и фиксируется с помощью Put Block List. По умолчанию используется 64 МиБ.

Дополнительные сведения об ограничениях размера передачи для хранилища BLOB-объектов см. в разделе "Целевые объекты масштабирования" для хранилища BLOB-объектов.

Для операций отправки можно также передать max_concurrency аргумент при вызове upload_blob. Этот аргумент определяет максимальное количество параллельных подключений, которые можно использовать, когда размер блочного объекта превышает 64 МиБ.

В следующем примере кода показано, как указать параметры передачи данных при создании BlobClient объекта и как передать данные с помощью этого клиентского объекта. Значения, указанные в этом примере, не предназначены для рекомендации. Чтобы правильно настроить эти значения, необходимо учитывать конкретные потребности приложения.

def upload_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for upload
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_block_size=1024*1024*4, # 4 MiB
        max_single_put_size=1024*1024*8 # 8 MiB
    )
    
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, max_concurrency=2)

Дополнительные сведения о настройке параметров передачи данных см. в разделе "Настройка производительности" для отправки и скачивания с помощью Python.

Установка уровня доступа объекта BLOB при загрузке

Можно задать уровень доступа бинарного объекта при загрузке, передав standard_blob_tier аргумент ключевого слова в upload_blob. Служба хранилища Azure предлагает различные уровни доступа, чтобы вы могли хранить данные BLOB наиболее экономичным способом в зависимости от того, как они используются.

В следующем примере кода показано, как задать уровень доступа при загрузке объекта.

def upload_blob_access_tier(self, blob_service_client: BlobServiceClient, container_name: str, blob_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    
    #Upload blob to the cool tier
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, standard_blob_tier=StandardBlobTier.COOL)

Установка уровня доступа разрешена только для блочных блобов. Вы можете установить уровень доступа для блочного blob на Hot, Cool, Cold или Archive. Чтобы задать уровень Coldдоступа, необходимо использовать минимальную версию клиентской библиотеки 12.15.0.

Дополнительные сведения о уровнях доступа см. в обзоре уровней доступа.

Загрузить блочный BLOB путем поэтапной загрузки и фиксации блоков

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

Используйте следующий метод, чтобы создать новый блок для фиксации в составе большого двоичного объекта:

stage_block

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

commit_block_list

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

def upload_blocks(self, blob_container_client: ContainerClient, local_file_path: str, block_size: int):
    file_name = os.path.basename(local_file_path)
    blob_client = blob_container_client.get_blob_client(file_name)

    with open(file=local_file_path, mode="rb") as file_stream:
        block_id_list = []

        while True:
            buffer = file_stream.read(block_size)
            if not buffer:
                break

            block_id = uuid.uuid4().hex
            block_id_list.append(BlobBlock(block_id=block_id))

            blob_client.stage_block(block_id=block_id, data=buffer, length=len(buffer))

        blob_client.commit_block_list(block_id_list)

Асинхронная загрузка блобов

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

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

Добавьте в файл следующие операторы импорта:

import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient

Добавьте код для запуска программы с помощью asyncio.run. Эта функция запускает переданную корутину, в нашем примере, main(), и управляет циклом событий asyncio. Корутины объявляются с помощью синтаксиса async/await. В этом примере main() корутина сначала создает верхний уровень BlobServiceClient с помощью async with, а затем вызывает метод, который загружает BLOB. Обратите внимание, что только клиент верхнего уровня должен использовать async with, так как другие клиенты, созданные из него, используют тот же пул подключений.
```
async def main():
    sample = BlobSamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        await sample.upload_blob_file(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())
```
Добавьте код для загрузки двоичного объекта. В следующем примере загружается блоб с локального пути файла с помощью объекта ContainerClient. Код совпадает с синхронным примером, за исключением того, что метод объявляется с async ключевым словом, а await ключевое слово используется при вызове upload_blob метода.
```
async def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = await container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)
```

С помощью этой базовой настройки вы можете реализовать другие примеры в этой статье в качестве корутин с помощью синтаксиса async/await.

Ресурсы

Дополнительные сведения о отправке BLOB-объектов с помощью клиентской библиотеки Хранилище BLOB-объектов Azure для Python см. в следующих ресурсах.

Примеры кода

Просмотр примеров синхронного или асинхронного кода из этой статьи (GitHub)

Операции REST API

Пакет SDK Azure для Python содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API с помощью знакомых парадигм Python. Методы клиентской библиотеки для отправки больших двоичных объектов используют следующие операции REST API:

Размещение большого двоичного объекта (REST API)
Put Block (REST API - интерфейс прикладного программирования REST)

Ресурсы клиентской библиотеки

См. также

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

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-10-08