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

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

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

Prerequisites

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

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

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

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

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

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

pip install azure-storage-blob azure-identity

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

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

import io
import os
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient

Authorization

Механизм авторизации должен иметь необходимые разрешения для выполнения операции скачивания. Для авторизации с помощью Microsoft Entra ID (рекомендуется) требуется встроенная роль Azure RBAC Storage Blob Data Reader или выше. Дополнительные сведения см. в руководстве по авторизации для получения BLOB-объектов (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 объекта. Дополнительные сведения о создании клиентских объектов и управлении ими см. в статье "Создание клиентских объектов и управление ими", взаимодействующих с ресурсами данных.

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

Для загрузки блоба можно использовать следующий метод:

BlobClient.download_blob

Метод download_blob возвращает объект StorageStreamDownloader . Во время скачивания клиентские библиотеки разбивают запрос на скачивание на блоки, где каждый блок загружается с отдельным запросом на Get Blob. Это поведение зависит от общего размера блоба и от того, как установлены параметры передачи данных.

Загрузка по пути к файлу

В следующем примере объект blob загружается по заданному пути к файлу.

def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob()
        sample_blob.write(download_stream.readall())

Скачивание в поток

В следующем примере выполняется загрузка блоба в поток. В этом примере StorageStreamDownloader.read_into загружает содержимое blob в поток и возвращает количество считанных байтов.

def download_blob_to_stream(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # readinto() downloads the blob contents to a stream and returns the number of bytes read
    stream = io.BytesIO()
    num_bytes = blob_client.download_blob().readinto(stream)
    print(f"Number of bytes: {num_bytes}")

Загрузка объекта BLOB по частям

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

def download_blob_chunks(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # This returns a StorageStreamDownloader
    stream = blob_client.download_blob()
    chunk_list = []

    # Read data in chunks to avoid loading all into memory at once
    for chunk in stream.chunks():
        # Process your data (anything can be done here - 'chunk' is a byte array)
        chunk_list.append(chunk)

Загрузка в строку

В следующем примере содержимое BLOB-файла скачивается в виде текста. В этом примере encoding параметр необходим для readall() возврата строки, в противном случае он возвращает байты:

def download_blob_to_string(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # encoding param is necessary for readall() to return str, otherwise it returns bytes
    downloader = blob_client.download_blob(max_concurrency=1, encoding='UTF-8')
    blob_text = downloader.readall()
    print(f"Blob contents: {blob_text}")

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

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

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

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

max_chunk_get_size — максимальный размер блока, используемый для скачивания большого двоичного объекта. По умолчанию — 4 МиБ.
max_single_get_size — максимальный размер большого двоичного объекта для скачивания в одном вызове. Если общий размер большого двоичного объекта превышается max_single_get_size, остальные данные большого двоичного объекта скачиваются в блоках. По умолчанию — 32 МиБ.

Для операций загрузки можно также передать max_concurrency аргумент при вызове download_blob. Этот аргумент определяет максимальное количество параллельных подключений для операции скачивания.

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

def download_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for download
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_single_get_size=1024*1024*32, # 32 MiB
        max_chunk_get_size=1024*1024*4 # 4 MiB
    )

    with open(file=os.path.join(r'file_path', 'file_name'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob(max_concurrency=2)
        sample_blob.write(download_stream.readall())

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

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

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

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

import asyncio

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

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

if __name__ == '__main__':
    asyncio.run(main())
```
Добавьте код для загрузки BLOB. В следующем примере BLOB скачивается в локальный файл по указанному пути с помощью объекта BlobClient. Код совпадает с синхронным примером, за исключением того, что метод объявляется с async ключевым словом, а await ключевое слово используется при вызове download_blob метода.
```
async def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = await blob_client.download_blob()
        data = await download_stream.readall()
        sample_blob.write(data)
```

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

Resources

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

Примеры кода

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

Операции REST API

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

Получение BLOB-объекта (REST API)

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

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

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

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

Last updated on 2025-10-09