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

В этой статье показано, как перечислить объекты BLOB с помощью клиентской библиотеки Azure Storage для 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

Authorization

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

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

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

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

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

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

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

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

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

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

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

Если вы назовете большие двоичные объекты с помощью разделителя, вы можете перечислить большие двоичные объекты иерархически. Для иерархической операции перечисления Azure Storage возвращает все виртуальные каталоги и объекты 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'}

Note

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

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

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

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

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

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

Note

Моментальные снимки BLOB-объектов нельзя отображать в рамках иерархической операции списка.

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

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

Resources

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

Примеры кода

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

Операции REST API

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

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

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

См. также

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

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

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

Last updated on 2025-10-08

Поделиться через

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

Prerequisites

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

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

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

Authorization

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

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

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

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

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

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

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

Resources

Примеры кода

Операции REST API

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

См. также

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

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

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