Перечисление блобов с помощью Python

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

Чтобы узнать о перечислении BLOB-объектов с помощью асинхронных API, см. Асинхронное перечисление BLOB-объектов.

Prerequisites

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

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

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

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

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

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

pip install azure-storage-blob azure-identity

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

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobPrefix

Авторизация

Механизм авторизации должен иметь необходимые разрешения для отображения объекта BLOB. Для авторизации через 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)

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

Сведения о параметрах перечисления BLOB-объектов

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

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

ContainerClient.list_blobs (вместе с именем, по желанию, включают метаданные, теги и другую информацию, связанную с каждым blob-ом)
ContainerClient.list_blob_names (возвращается только имя blob)

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

ContainerClient.walk_blobs (вместе с именем, по желанию, включают метаданные, теги и другую информацию, связанную с каждым блобом)

Фильтрация результатов с префиксом

Чтобы отфильтровать список блобов, укажите строку для аргумента ключевого слова name_starts_with. Строка префикса может содержать один или несколько символов. служба хранилища Azure возвращает только те blobs, имена которых начинаются с этого префикса.

Плоский список и иерархический список

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

Чтобы организовать блобы в виртуальные директории, используйте символ разделителя в имени блоба. Символ разделителя по умолчанию является косой чертой (/), но можно указать любой символ в качестве разделителя.

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

Использование плоского списка

По умолчанию операция перечисления возвращает большие двоичные объекты в неструктурированном списке. В плоском списке бинарные данные не организованы по виртуальному каталогу.

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

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

Пример выходных данных аналогичен следующему:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

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

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

Пример выходных данных аналогичен следующему:

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

Примечание

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

Альтернативный вариант перечисления при работе с иерархическим пространством имен см. в разделе "Список содержимого каталога" (Azure Data Lake Storage).

Использование иерархического списка

При иерархическом вызове операции перечисления служба хранилища Azure возвращает виртуальные каталоги и блобы на первом уровне иерархии.

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

ContainerClient.walk_blobs

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

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

Пример выходных данных аналогичен следующему:

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

Примечание

Снимки blob нельзя перечислять в иерархической операции списка.

Перечислить объекты типа BLOB асинхронно

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

Следуйте следующим шагам для перечисления blob-ов с помощью асинхронных API:

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

import asyncio

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

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

if __name__ == '__main__':
    asyncio.run(main())
```
Добавьте код для перечисления BLOB. Следующий пример кода перечисляет blobs с использованием плоского листинга. Код совпадает с синхронным примером, за исключением того, что метод объявлен с помощью async ключевого слова и async for используется при вызове list_blobs метода.
```
async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    async for blob in container_client.list_blobs():
        print(f"Name: {blob.name}")
```

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

Список blobs в формате Apache Arrow (предварительный просмотр)

Important

Список блобов в формате Apache Arrow сейчас находится в PREVIEW. Для этого сценария требуется бета-версия (предпросмотр) клиентской библиотеки Хранилище BLOB-объектов Azure для Python (например, azure-storage-blobверсия 12.31.0b1 или более поздняя версия). Предварительные версии функций предоставляются без соглашения об уровне обслуживания и не рекомендуется для рабочих нагрузок. Некоторые функции могут не поддерживаться или иметь ограниченные возможности. Дополнительные сведения см. в статье Дополнительные условия использования предварительных версий Microsoft Azure.

Эта возможность основана на существующем List Blobs API. Вместо стандартного XML в качестве формата ответов при передаче по сети используется компактный колоночный формат Apache Arrow. Это включается установкой одного параметра в запросе на получение списка контейнеров. Python SDK расшифровывает Apache Arrow за кулисами и всё равно возвращает те же BlobProperties объекты. Такой подход повышает производительность при получении списка и снижает нагрузку на ЦП на стороне клиента при перечислении содержимого больших контейнеров. Он сохраняет контракт на ответ, на который опираются заявки.

Предупреждение

Получение списка BLOB-объектов в формате Apache Arrow не поддерживается в учетных записях хранения с включенным иерархическим пространством имен (Azure Data Lake Storage).

Чтобы запросить результаты в формате Apache Arrow, установите response_format аргумент ключевого слова на "arrow" когда вы вызываете ContainerClient.list_blobs или ContainerClient.list_blob_names. При использовании вывода Apache Arrow вы также можете задать именованные аргументы start_from и end_before для управления диапазоном возвращаемых путей.

Примечание

Для использования response_format="arrow" требуется установка пакета nanoarrow .

В следующем примере перечислены blob-и в контейнере и запрашиваются результаты в формате Apache Arrow:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

Ресурсы

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

Примеры кода

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

Операции REST API

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

Перечень бинарных объектов (блобов) (REST API)

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

См. также

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

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

Были ли сведения на этой странице полезными?

Last updated on 2026-08-27

Перечисление блобов с помощью Python

Prerequisites

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

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

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

Авторизация

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

Сведения о параметрах перечисления BLOB-объектов

Фильтрация результатов с префиксом

Плоский список и иерархический список

Использование плоского списка

Использование иерархического списка

Перечислить объекты типа BLOB асинхронно

Список blobs в формате Apache Arrow (предварительный просмотр)

Ресурсы

Примеры кода

Операции REST API

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

См. также

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

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

Дополнительные ресурсы