Seznam blobů pomocí .NET

Tento článek ukazuje, jak zobrazit bloby pomocí klientské knihovny Azure Storage pro .NET.

Prerequisites

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro .NET. Kroky zahrnují instalaci balíčku, přidání using direktiv a vytvoření autorizovaného objektu klienta. Podrobnosti najdete v tématu Začínáme se službou Azure Blob Storage a .NET.

Instalace balíčků

Z adresáře projektu nainstalujte balíčky pro klientské knihovny Azure Blob Storage a Azure Identity pomocí dotnet add package příkazu. Balíček Azure.Identity je potřeba pro připojení bez hesla ke službám Azure.

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

Přidejte using direktivy

Na začátek souboru kódu přidejte tyto using direktivy:

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

Některé příklady kódu v tomto článku mohou vyžadovat další using direktivy.

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient. Následující příklad ukazuje, jak pomocí DefaultAzureCredential vytvořit objekt klienta pro autorizaci.

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

    return client;
}

Klienta služby můžete zaregistrovat pro injektování závislostí v aplikaci .NET.

Můžete také vytvořit klientské objekty pro konkrétní kontejnery nebo objekty blob. Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k výpisu objektu blob. Pro autorizaci s Microsoft Entra ID (doporučené) potřebujete vestavěnou roli Storage Blob Data Reader v Azure RBAC nebo vyšší. Další informace najdete v pokynech k autorizaci pro výpis objektů Blob (REST API).

Informace o možnostech výpisu objektů blob

Když ve svém kódu vypisujete objekty blob, můžete určit řadu možností, jak spravovat návrat výsledků ze služby Azure Storage. Můžete zadat počet výsledků, které se mají vrátit v každé sadě výsledků, a pak načíst následující sady. Můžete zadat předponu pro vrácení objektů blob, jejichž názvy začínají tímto znakem nebo řetězcem. Objekty blob můžete vypsat jako plochý seznam nebo hierarchicky. Hierarchický výpis zobrazuje objekty typu blob, jako by byly uspořádané ve složkách.

Pokud chcete vytvořit seznam objektů blob v účtu úložiště, použijte jednu z následujících metod:

Správa počtu vrácených výsledků

Ve výchozím nastavení vrátí operace výpisu najednou až 5 000 výsledků, ale můžete zadat počet výsledků, které má každá operace výpisu vrátit. Příklady uvedené v tomto článku ukazují, jak vrátit výsledky na stránkách. Další informace o konceptech stránkování najdete v tématu Stránkování pomocí sady Azure SDK pro .NET.

Filtrování výsledků pomocí předpony

Pokud chcete filtrovat seznam objektů blob, zadejte řetězec pro parametr prefix. Řetězec předpony může obsahovat jeden nebo více znaků. Azure Storage pak vrátí pouze objekty blob, jejichž názvy začínají danou předponou.

Vrácení metadat

Metadata objektů blob můžete vrátit ve výsledcích zadáním hodnoty Metadata pro výčet BlobTraits.

Plochý výpis versus hierarchický výpis

Objekty blob ve službě Azure Storage jsou uspořádané do plochého paradigmatu místo hierarchického paradigmatu (jako je klasický systém souborů). Objekty blob ale můžete uspořádat do virtuálních adresářů , abyste napodobili strukturu složek. Virtuální adresář tvoří část názvu objektu blob a je označen znakem oddělovače.

Pokud chcete objekty blob uspořádat do virtuálních adresářů, použijte v názvu objektu blob znak oddělovače. Výchozí znak oddělovače je lomítko (/), ale jako oddělovač můžete zadat libovolný znak.

Pokud objekty blob pojmenujete pomocí oddělovače, můžete se rozhodnout, jestli chcete objekty blob vypsat hierarchicky. Pro hierarchickou operaci výpisu vrátí Azure Storage všechny virtuální adresáře a blobové objekty pod nadřazeným objektem. Operaci výpisu můžete volat rekurzivně a procházet hierarchii podobně jako při procházení klasického systému souborů prostřednictvím kódu programu.

Použití plochého výpisu

Operace výpisu ve výchozím nastavení vrací objekty blob v plochém výpisu. V plochém výpisu nejsou blobs uspořádané podle virtuálního adresáře.

Následující příklad uvádí bloby ve specifikovaném kontejneru pomocí plochého seznamu, s volitelnou specifikovanou velikostí segmentu, a zapisuje název blobu do okna konzole.

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

Ukázkový výstup je podobný následujícímu:

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

Poznámka

Zobrazený ukázkový výstup předpokládá, že máte účet úložiště s plochým oborem názvů. Pokud povolíte funkci hierarchického jmenného prostoru pro svůj úložný účet, adresáře nejsou virtuální. Místo toho jsou to konkrétní, nezávislé objekty. V důsledku toho se adresáře v seznamu zobrazují jako objekty blob nulové délky.

Alternativní možnost výpisu při práci s hierarchickým oborem názvů najdete v tématu Výpis obsahu adresáře (Azure Data Lake Storage).

Použití hierarchického výpisu

Při hierarchickém volání operace výpisu obsahu vrátí Azure Storage virtuální adresáře a objekty blob na první úrovni hierarchie.

Pro hierarchický seznam blobů volejte BlobContainerClient.GetBlobsByHierarchy nebo BlobContainerClient.GetBlobsByHierarchyAsync metodu.

Následující příklad uvádí bloby ve specifikovaném kontejneru pomocí hierarchického seznamu, s volitelnou specifikovanou velikostí segmentu, a zapisuje název blobu do okna konzole.

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

Ukázkový výstup je podobný následujícímu:

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

Poznámka

Snímky blobů nelze vypsat v operaci hierarchického výpisu.

Výpis verzí nebo snímků blobů

Pokud chcete zobrazit seznam verzí nebo snímků objektů blob, zadejte parametr BlobStates s polem Version nebo Snapshot . Služba vrací verze a snímky od nejstarších po nejnovší.

Následující příklad kódu ukazuje, jak zobrazit seznam verzí objektů 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;
    }
}

Seznam blobů ve formátu Apache Arrow (náhled)

Important

Seznam blobů ve formátu Apache Arrow je momentálně v PREVIEWS. Tento scénář vyžaduje beta (preview) verzi klientské knihovny Azure Blob Storage pro .NET (například Azure.Storage.Blobs12.30.0-beta.1 nebo novější preview verzi). Funkce ve verzi Preview jsou poskytovány bez smlouvy o úrovni služeb a nedoporučuje se pro produkční úlohy. Některé funkce nemusí být podporovány nebo mohou mít omezené schopnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Tato schopnost je postavena na existujícím List Blobs API. Místo výchozího XML používá kompaktní, sloupcový formát Apache Arrow jako formát odpovědi na drátu. Povolíte to nastavením jedné možnosti při volání výpisu kontejnerů. .NET SDK dekóduje Apache Arrow v pozadí a stále vrací stejné BlobItem objekty. Tento přístup zlepšuje propustnost výpisů a snižuje CPU na straně klienta při enumeraci velkých kontejnerů. Zachovává kontrakt odpovědi, na který aplikace spoléhají.

Warning

Seznamování blobů ve formátu Apache Arrow není podporováno na úložných účtech, které mají povolený hierarchický jmenný prostor (Azure Data Lake Storage).

Chcete-li požádat o výsledky ve formátu Apache Arrow, nastavte vlastnost ResponseFormat v GetBlobsOptions na StorageResponseFormat.Arrow a potom tyto možnosti předejte přetížené metodě BlobContainerClient.GetBlobs, která přijímá GetBlobsOptions. Při použití výstupu Apache Arrow můžete také nastavit StartFrom vlastnosti a EndBefore tak, aby kontrolovaly rozsah vrácených cest.

Následující příklad uvádí bloby v kontejneru a požaduje výsledky ve formátu 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);
}

Zdroje

Chcete-li se dozvědět více o tom, jak zobrazit bloby pomocí klientské knihovny Azure Blob Storage pro .NET, podívejte se na následující zdroje.

Operace rozhraní REST API

Azure SDK pro .NET obsahuje knihovny, které se staví na Azure REST API. Použitím těchto knihoven můžete komunikovat s operacími REST API prostřednictvím známých .NET paradigmat. Metody klientské knihovny pro výpis objektů blob používají následující operaci rozhraní REST API:

Prostředky klientské knihovny

Viz také

Související obsah

  • Tento článek je součástí příručky pro vývojáře služby Blob Storage pro .NET. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace .NET.
  • Last updated on