Отправка блочного BLOB-объекта с помощью Python

Статья
11/16/2023

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

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

Необходимые компоненты

В этой статье предполагается, что у вас уже есть проект, настроенный для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для Python. Сведения о настройке проекта, включая установку пакета, добавление import инструкций и создание авторизованного клиентского объекта, см. в статье "Начало работы с Хранилище BLOB-объектов Azure и Python".
Сведения об использовании асинхронных API в коде см. в разделе " Асинхронное программирование ".
Механизм авторизации должен иметь разрешения для выполнения операции отправки. Дополнительные сведения см. в руководстве по авторизации для следующих операций REST API:
- вставка большого двоичного объекта;
- Put Block

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

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

upload_blob

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

Отправка блочного 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-объекта из потока

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

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-объектов.

Для операций отправки можно также передать 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.

Настройка уровня доступа большого двоичного объекта при отправке

Уровень доступа большого двоичного объекта можно задать для отправки, передав standard_blob_tier аргумент ключевое слово в upload_blob. служба хранилища Azure предлагает различные уровни доступа, чтобы вы могли хранить данные БОЛЬШИХ двоичных объектов в наиболее экономичном режиме на основе того, как он используется.

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

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можно задать для , Coldили CoolArchive. Чтобы задать уровень 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)

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

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

Выполните следующие действия, чтобы отправить большой двоичный объект с помощью асинхронных 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, а затем вызывает метод, который отправляет большой двоичный объект. Обратите внимание, что использовать только клиент верхнего уровня, так как другие клиенты, созданные из него, используют 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 см. в следующих ресурсах.

Операции REST API

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

Вставка большого двоичного объекта (REST API)
Put Block (REST API)

Примеры кода

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

Share via