Upload a block blob with Python

2025-04-12

В этой статье показано, как загрузить объект Blob с помощью клиентской библиотеки хранилища Azure для Python. You can upload data to a block blob from a file path, a stream, a binary object, or a text string. You can also upload blobs with index tags.

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

Требования

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

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

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

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

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

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

pip install azure-storage-blob azure-identity

Add import statements

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

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

Авторизация

The authorization mechanism must have the necessary permissions to upload a blob. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role Storage Blob Data Contributor or higher. Дополнительные сведения см. в руководстве по авторизации для 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 объекта. Дополнительные сведения о создании клиентских объектов и управлении ими см. в статье "Создание клиентских объектов и управление ими", взаимодействующих с ресурсами данных.

Upload data to a block blob

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

upload_blob

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

Примечание.

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

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

The following example uploads a file to a block blob using a BlobClient object:

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)

Upload a block blob from a stream

The following example creates random bytes of data and uploads a BytesIO object to a block blob using a BlobClient object:

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")

Upload a block blob with index tags

The following example uploads a block blob with index tags:

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)

Upload a block blob with configuration options

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

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

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

max_block_size - The maximum chunk size for uploading a block blob in chunks. По умолчанию — 4 МиБ.
max_single_put_size — Если размер большого двоичного объекта меньше или равен max_single_put_size, большой двоичный объект отправляется с одним Put Blob запросом. Если размер объекта данных больше max_single_put_size или неизвестен, объект данных загружается частями с использованием Put Block и фиксируется с помощью Put Block List. Defaults to 64 MiB.

Дополнительные сведения об ограничениях размера передачи для хранилища 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.

Set a blob's access tier on upload

You can set a blob's access tier on upload by passing the standard_blob_tier keyword argument to 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)

Setting the access tier is only allowed for block blobs. You can set the access tier for a block blob to Hot, Cool, Cold, or Archive. Чтобы задать уровень Coldдоступа, необходимо использовать минимальную версию клиентской библиотеки 12.15.0.

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

Upload a block blob by staging blocks and committing

Вы можете иметь больший контроль над тем, как разделяются загрузки на блоки, вручную управляя отдельными блоками данных. When all of the blocks that make up a blob are staged, you can commit them to Blob Storage.

Use the following method to create a new block to be committed as part of a blob:

stage_block

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

commit_block_list

The following example reads data from a file and stages blocks to be committed as part of a blob:

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:

Add the following import statements:

import asyncio

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

Добавьте код для запуска программы с помощью asyncio.run. This function runs the passed coroutine, main() in our example, and manages the asyncio event loop. Coroutines are declared with the async/await syntax. In this example, the main() coroutine first creates the top level BlobServiceClient using async with, then calls the method that uploads the 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())
```
Add code to upload the blob. В следующем примере загружается блоб с локального пути файла с помощью объекта 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:

Put Blob (REST API)
Put Block (REST API)

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

См. также

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