Wyświetlanie listy obiektów blob przy użyciu platformy .NET

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

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 platformy .NET. Kroki obejmują instalację pakietu, dodawanie using dyrektyw i tworzenie autoryzowanego obiektu klienta. Aby uzyskać szczegółowe informacje, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i .NET.

Instalowanie pakietów

Z katalogu projektu zainstaluj pakiety bibliotek klienckich Azure Blob Storage i Azure Identity za pomocą polecenia dotnet add package. Pakiet Azure.Identity jest wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Dodaj dyrektywy using

Dodaj te using dyrektywy na początku pliku kodu:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Niektóre przykłady kodu w tym artykule mogą wymagać dodatkowych using dyrektyw.

Tworzenie obiektu klienta

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

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Możesz zarejestrować klienta usługi do wstrzykiwania zależności w aplikacji .NET.

Można również tworzyć obiekty klienta dla określonych kontenerów lub obiektów blob. 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.

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, zobacz wskazówki dotyczące autoryzacji dla operacji List Blobs (interfejs API REST).

Informacje o opcjach wyświetlania listy obiektów blob

Gdy wyświetlasz listę obiektów blob w kodzie, możesz określić szereg opcji określających 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. Lista hierarchiczna zwraca obiekty blob tak, jakby były zorganizowane w foldery.

Aby wyświetlić listę obiektów blob na koncie magazynu, wywołaj jedną z następujących metod:

Zarządzanie liczbą zwracanych wyników

Domyślnie operacja wyświetlania listy zwraca maksymalnie 5000 wyników jednocześnie, ale można określić liczbę wyników, które mają zostać zwrócone przez każdą operację listy. W przykładach przedstawionych w tym artykule pokazano, jak zwracać wyniki na stronach. Aby dowiedzieć się więcej na temat pojęć dotyczących stronicowania, zobacz Pagination with the Azure SDK for .NET (Stronicowanie przy użyciu zestawu Azure SDK dla platformy .NET).

Filtrowanie wyników za pomocą prefiksu

Aby przefiltrować listę obiektów blob, określ ciąg parametru prefix . Ciąg prefiksu może zawierać co najmniej jeden znak. Następnie usługa Azure Storage zwraca tylko obiekty blob, których nazwy zaczynają się od tego prefiksu.

Zwracanie metadanych

Metadane obiektu blob można zwrócić wraz z wynikami, określając wartość Metadata dla wyliczenia BlobTraits.

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żna jednak organizować obiekty blob w katalogach wirtualnych , aby naśladować strukturę folderów. Katalog wirtualny stanowi część nazwy obiektu Blob i jest oznaczony znakiem separatora.

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

Jeśli nadasz swoim obiektom blob nazwy z użyciem ogranicznika, możesz wyświetlać obiekty blob hierarchicznie. W przypadku operacji wyświetlania listy hierarchicznej usługa Azure Storage zwraca 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 listowania zwraca obiekty blob w postaci płaskiej listy. W płaskiej liście, obiekty typu blob nie są zorganizowane według katalogu wirtualnego.

Poniższy przykład wymienia bloby w określonym kontenerze za pomocą płaskiego listingu, z opcjonalnym określonym rozmiarem segmentu, i zapisuje nazwę blobu w oknie konsoli.

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

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

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Uwaga

Przedstawione przykładowe dane wyjściowe zakładają, że masz konto magazynu z płaską przestrzenią nazw. 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

Gdy wywołasz operację wyliczania hierarchicznie, usługa Azure Storage zwróci katalogi wirtualne i obiekty blob na pierwszym poziomie hierarchii.

Aby hierarchicznie wypisać bloby, wywołaj metodę BlobContainerClient.GetBlobsByHierarchy lub metodę BlobContainerClient.GetBlobsByHierarchyAsync .

Poniższy przykład wyświetla bloby w określonym kontenerze za pomocą listowania hierarchicznego, z opcjonalnie określonym rozmiarem segmentu, i zapisuje nazwę blobu w oknie konsoli.

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

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

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

Uwaga

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

Wyświetlanie listy wersji obiektów blob lub migawek

Aby wyświetlić listę wersji obiektów blob lub migawek, określ parametr BlobStates z polem Wersja lub Migawka . Usługa zwraca wersje i migawki od najstarszych do najnowszych.

Poniższy przykład kodu pokazuje, jak wyświetlić listę wersji obiektów blob.

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

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 potrzebna jest wersja beta (podglądowa) biblioteki klienta Azure Blob Storage dla .NET (na przykład Azure.Storage.Blobswersja 12.30.0-beta.1 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. SDK .NET dekoduje Apache Arrow za kulisami i nadal zwraca te same BlobItem 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, ustaw właściwość ResponseFormat obiektu GetBlobsOptions na StorageResponseFormat.Arrow, a następnie przekaż te opcje do przeciążenia BlobContainerClient.GetBlobs, przyjmującego parametr GetBlobsOptions. Korzystając z formatu wyjściowego Apache Arrow, możesz także ustawić właściwości StartFrom i EndBefore, aby kontrolować zakres zwracanych ścieżek.

Poniższy przykład wyświetla listę obiektów blob w kontenerze i żąda wyników w formacie Apache Arrow:

using Azure.Storage;
using Azure.Storage.Blobs.Models;

GetBlobsOptions options = new GetBlobsOptions
{
    Prefix = "FolderA/",
    ResponseFormat = StorageResponseFormat.Arrow
};

foreach (BlobItem blobItem in containerClient.GetBlobs(options))
{
    Console.WriteLine("Blob name: " + blobItem.Name);
}

Zasoby

Aby dowiedzieć się więcej o tym, jak wymieniać bloby za pomocą biblioteki klienta Azure Blob Storage dla .NET, zobacz następujące materiały.

Operacje interfejsu API REST

Azure SDK dla .NET zawiera biblioteki budujące się na Azure REST API. Dzięki tym bibliotekom możesz wchodzić w interakcje z operacjami API REST za pomocą znanych paradygmatów .NET. 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 platformy .NET. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji platformy .NET.
  • Last updated on