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

• .NET
• Java
• JavaScript
• Python
• Go

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

Сведения о отправке больших двоичных объектов с помощью асинхронных 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

Авторизация

Механизм авторизации должен иметь необходимые разрешения для отправки большого двоичного объекта. Для авторизации с помощью идентификатора Microsoft Entra (рекомендуется), требуется встроенный участник данных хранилища 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

Этот метод создает новый большой двоичный объект из источника данных с автоматическим блокированием, что означает, что источник данных может быть разделен на небольшие блоки и отправлен. Чтобы выполнить отправку, клиентская библиотека может использовать либо 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-объектов см. в разделе "Целевые объекты масштабирования" для хранилища 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:

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

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

2. Добавьте код для запуска программы с помощью 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())
   

3. Добавьте код для отправки БОЛЬШОго двоичного объекта. В следующем примере передается большой двоичный объект из локального пути к файлу 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)

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

• Справочная документация по клиентской библиотеке
• Исходный код клиентской библиотеки
• Пакет (PyPi)

См. также

• Управление данными больших двоичных объектов Azure и их поиск с помощью тегов индекса больших двоичных объектов
• Использование тегов индекса BLOB-объектов для управления и поиска данных на Хранилище BLOB-объектов Azure

Связанный контент

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