Wyświetlanie listy obiektów blob za pomocą języka Python

Ten artykuł pokazuje, jak wymieniać bloby za pomocą biblioteki klienta Azure Storage dla Python.

Aby dowiedzieć się więcej o wymienianiu blobów za pomocą asynchronicznych API, zobacz Lista blobów asynchronicznie.

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Python. Aby uzyskać więcej informacji, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i Python.

Aby pracować z przykładami kodu w tym artykule, wykonaj następujące kroki, aby skonfigurować projekt.

Instalowanie pakietów

Zainstaluj następujące pakiety przy użyciu polecenia pip install:

pip install azure-storage-blob azure-identity

Dodaj instrukcje importu

Dodaj następujące instrukcje import:

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

Autoryzacja

Mechanizm autoryzacji musi mieć niezbędne uprawnienia do wyświetlania listy obiektów blob. Aby uzyskać autoryzację z Microsoft Entra ID (zalecane), potrzebujesz wbudowanej roli Azure RBAC Storage Blob Data Reader lub wyższej. Aby dowiedzieć się więcej, zapoznaj się z wytycznymi dotyczącymi autoryzacji dla List Blobs (interfejsu API REST).

Tworzenie obiektu klienta

Aby połączyć aplikację z Blob Storage, utwórz wystąpienie BlobServiceClient. W poniższym przykładzie pokazano, jak utworzyć obiekt klienta przy użyciu DefaultAzureCredential autoryzacji:

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

Można również tworzyć obiekty klienta dla określonych kontenerów lub obiektów blob, bezpośrednio lub poprzez obiekt BlobServiceClient. Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Opcje wyświetlania listy obiektów blob — informacje

Gdy wyświetlasz listę obiektów blob w kodzie, możesz określić wiele opcji, które kontrolują sposób zwracania wyników przez usługę Azure Storage. Możesz określić liczbę wyników, które mają być zwracane w każdym zestawie wyników, a następnie pobrać kolejne zestawy. Można określić prefiks do zwracania obiektów blob, których nazwy zaczynają się od tego znaku lub ciągu. Możesz wymieniać bloby w płaskiej strukturze lub hierarchicznie. Hierarchiczna lista zwraca obiekty blob tak, jak są zorganizowane w folderach.

Aby wymienić plamy w kontenerze za pomocą płaskiej listy, wywołaj jedną z następujących metod:

  • ContainerClient.list_blobs (wraz z nazwą, opcjonalnie uwzględniając metadane, tagi i inne informacje skojarzone z każdym obiektem blob)
  • ContainerClient.list_blob_names (zwraca tylko nazwę obiektu blob)

Aby wymienić bloby w kontenerze za pomocą hierarchicznej listy, wywołaj następującą metodę:

Filtrowanie wyników za pomocą prefiksu

Aby przefiltrować listę obiektów blob, podaj ciąg dla argumentu związanego ze słowem kluczowym name_starts_with. Ciąg prefiksu może zawierać co najmniej jeden znak. Azure Storage zwraca tylko te bloby, których nazwy zaczynają się od tego prefiksu.

Lista płaska a lista hierarchiczna

Obiekty blob w usłudze Azure Storage są zorganizowane w modelu płaskim, a nie w modelu hierarchicznym (np. klasycznym systemie plików). Możesz jednak organizować bloby w wirtualne katalogi , aby naśladować strukturę folderów. Katalog wirtualny jest częścią nazwy obiektu typu blob i jest określany za pomocą znaku rozdzielającego.

Aby zorganizować obiekty blob w katalogi wirtualne, użyj znaku oddzielającego w nazwie obiektu blob. Domyślny znak ogranicznika to ukośnik (/), ale można określić dowolny znak jako ogranicznik.

Jeśli nazywasz swoje bloby za pomocą separatora, możesz wybrać hierarchiczną listę bloków. W przypadku operacji hierarchicznego listowania usługa Azure Storage zwraca wszystkie katalogi wirtualne i obiekty blob znajdujące się pod obiektem nadrzędnym. Operację wyświetlania listy można wywołać rekursywnie, aby przejść przez hierarchię, podobnie jak w przypadku programowego przechodzenia przez klasyczny system plików.

Używanie listy płaskiej

Domyślnie operacja wyświetlania listy zwraca obiekty blob w płaskiej liście. W płaskiej liście, obiekty typu blob nie są zorganizowane według katalogu wirtualnego.

Poniższy przykład przedstawia plamy w określonym kontenerze przy użyciu płaskiego listingu:

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

Przykładowe dane wyjściowe są podobne do następujących:

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

Możesz także określić opcje filtrowania wyników listy lub wyświetlania większej ilości informacji. W poniższym przykładzie wymieniono obiekty blob i tagi blobów.

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']}")

Przykładowe dane wyjściowe są podobne do następujących:

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'}

Uwaga

Pokazane przykładowe dane wyjściowe zakładają, że masz konto magazynu z przestrzenią nazw płaską. Jeśli włączysz funkcję hierarchicznej przestrzeni nazw dla swojego konta pamięciowego, katalogi nie są wirtualne. Zamiast tego są konkretnymi, niezależnymi obiektami. W związku z tym katalogi są wyświetlane na liście jako obiekty blob o zerowej długości.

Aby uzyskać alternatywną opcję wyświetlania listy podczas pracy z hierarchiczną przestrzenią nazw, zobacz List directory contents (Azure Data Lake Storage).

Używanie listy hierarchicznej

Kiedy wywołujesz operację listowania hierarchicznie, Azure Storage zwraca katalogi wirtualne i obiekty blob na pierwszym poziomie hierarchii.

Aby wyświetlić hierarchicznie listę obiektów blob, użyj następującej metody:

W poniższym przykładzie wymieniono obiekty blob w określonym kontenerze przy użyciu listy hierarchicznej:

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

Przykładowe dane wyjściowe są podobne do następujących:

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

Uwaga

Migawek blobów nie można wyświetlić w operacji listowania hierarchicznego.

Wymienianie obiektów blob asynchronicznie

Biblioteka klienta usługi Azure Blob Storage dla języka Python obsługuje asynchroniczne wyświetlanie listy obiektów blob. Aby dowiedzieć się więcej na temat wymagań dotyczących konfiguracji projektu, zobacz Programowanie asynchroniczne.

Wykonaj poniższe kroki, aby wyświetlić obiekty blob przy użyciu asynchronicznych interfejsów API:

  1. Dodaj następujące instrukcje importowania:

    import asyncio

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

  2. Dodaj kod do uruchomienia programu, używając asyncio.run. Funkcja ta wykonuje przekazaną korurutinę, main() w tym przykładzie, i zarządza pętlą asyncio zdarzeń. Koroutine są deklarowane za pomocą składni async/await. W tym przykładzie korutyna main() najpierw tworzy najwyższy poziom BlobServiceClient za pomocą async with, a następnie wywołuje metodę, która wymienia bloby. Tylko klient najwyższego poziomu musi używać async with, ponieważ inni klienci utworzeni na jego podstawie współużytkują tę samą pulę połączeń.

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

  3. Dodaj kod, aby wyświetlić listę blobów. Poniższy przykład kodu zawiera listę blobów za pomocą płaskiego listingu. Kod jest taki sam jak w przykładzie synchronicznym, z tą różnicą, że metoda jest deklarowana za pomocą async słowa kluczowego i async for używana podczas wywoływania metody 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}")

Gdy masz już tę podstawową konfigurację, możesz zaimplementować inne przykłady z tego artykułu w postaci korutyn, używając składni async/await.

Lista blobów w formacie Apache Arrow (podgląd)

Ważna

Wyświetlanie listy obiektów blob w formacie Apache Arrow jest obecnie w WERSJI ZAPOZNAWCZEJ. W takim przypadku wymagana jest wersja beta (podgląd) biblioteki klienta Azure Blob Storage dla Python (na przykład azure-storage-blobwersja 12.31.0b1 lub nowsza). Funkcje w wersji zapoznawczej są udostępniane bez umowy dotyczącej poziomu usług i nie są zalecane w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Ta funkcja opiera się na istniejącym List Blobs API. Zamiast używać domyślnego XML, używa kompaktowego, kolumnowego formatu Apache Arrow jako formatu odpowiedzi na przewodzie. Włączasz tę funkcję, ustawiając pojedynczą opcję w wywołaniu listowania kontenerów. Python SDK dekoduje Apache Arrow za kulisami i nadal zwraca te same BlobProperties obiekty. Takie podejście poprawia przepustowość listowania i zmniejsza ilość procesora po stronie klienta podczas wyliczania dużych kontenerów. Zachowuje kontrakt odpowiedzi, od którego zależą aplikacje.

Warning

Wyświetlanie blobów w formacie Apache Arrow nie jest obsługiwane na kontach pamięci masowej, które mają włączoną hierarchiczną przestrzeń nazw (Azure Data Lake Storage).

Aby zażądać wyników w formacie Apache Arrow, podczas wywoływania ContainerClient.list_blobs lub ContainerClient.list_blob_names ustaw argument słowa kluczowego response_format na "arrow". Korzystając z wyjścia Apache Arrow, możesz także ustawić argumenty start_from i end_before słowa kluczowe, aby kontrolować zakres zwracanych ścieżek.

Uwaga

Używanie response_format="arrow" wymaga zainstalowania pakietu nanoarrow .

Poniższy przykład wyświetla listę obiektów blob w kontenerze i żąda wyników w formacie 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)

Zasoby

Aby dowiedzieć się więcej o tym, jak wyświetlać bloby za pomocą biblioteki klienta Azure Blob Storage dla Python, zobacz następujące zasoby.

Przykłady kodu

Operacje interfejsu API REST

Azure SDK dla Python zawiera biblioteki budujące się na Azure REST API. Korzystając z tych bibliotek, możesz wchodzić w interakcje z operacjami API REST za pomocą znanych paradygmatów Python. Metody biblioteki klienta do wyświetlania listy obiektów blob używają następującej operacji interfejsu API REST:

Zasoby biblioteki klienta

Zobacz też

Powiązana zawartość

  • Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla języka Python. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji w języku Python.
  • Last updated on