Lista blobar med .NET

Den här artikeln visar hur man listar blobs genom att använda Azure Storage-klientbiblioteket för .NET.

Förutsättningar

• Azure-prenumeration – skapa en kostnadsfritt
• Azure Storage-konto – skapa ett lagringskonto
• Senaste .NET SDK för operativsystemet. Se till att hämta SDK:t och inte körmiljön.

Konfigurera din miljö

Om du inte har ett befintligt projekt visar det här avsnittet hur du konfigurerar ett projekt för att arbeta med Azure Blob Storage-klientbiblioteket för .NET. Stegen omfattar paketinstallation, tillägg av using direktiv och skapande av ett auktoriserat klientobjekt. Mer information finns i Kom igång med Azure Blob Storage och .NET.

Installera paket

Från projektkatalogen installerar du paket för Azure Blob Storage- och Azure Identity-klientbiblioteken med hjälp av dotnet add package kommandot . Azure.Identity-paketet behövs för lösenordslösa anslutningar till Azure-tjänster.

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

Lägga till using direktiv

Lägg till dessa using direktiv överst i kodfilen:

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

Vissa kodexempel i den här artikeln kan kräva ytterligare using direktiv.

Skapa ett klientobjekt

Om du vill ansluta en app till Blob Storage skapar du en instans av BlobServiceClient. I följande exempel visas hur du skapar ett klientobjekt med hjälp av DefaultAzureCredential för auktorisering:

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

    return client;
}

Du kan registrera en tjänstklient för beroendeinmatning i en .NET-app.

Du kan också skapa klientobjekt för specifika containrar eller blobar. Mer information om hur du skapar och hanterar klientobjekt finns i Skapa och hantera klientobjekt som interagerar med dataresurser.

Auktorisering

Auktoriseringsmekanismen måste ha de behörigheter som krävs för att lista en blob. För auktorisation med Microsoft Entra ID (rekommenderas) behöver du Azure RBAC:s inbyggda roll Storage Blob Data Reader eller högre. Mer information finns i auktoriseringsvägledningen för REST-API (List Blobs).

Om alternativ för att lista blobbar

När du listar blobar från koden kan du ange ett antal alternativ för att hantera hur resultaten returneras från Azure Storage. Du kan ange hur många resultat som ska returneras i varje resultatuppsättning och sedan hämta efterföljande uppsättningar. Du kan ange ett prefix för att returnera blobar vars namn börjar med det tecknet eller strängen. Du kan lista blobs i en platt liststruktur eller hierarkiskt. En hierarkisk lista returnerar blobar som om de vore ordnade i mappar.

Om du vill lista blobarna i ett lagringskonto anropar du någon av följande metoder:

• BlobContainerClient.GetBlobs
• BlobContainerClient.GetBlobsAsync
• BlobContainerClient.GetBlobsByHierarchy
• BlobContainerClient.GetBlobsByHierarchyAsync

Hantera hur många resultat som returneras

Som standard returnerar en liståtgärd upp till 5 000 resultat åt gången, men du kan ange antalet resultat som du vill att varje listningsåtgärd ska returnera. Exemplen som presenteras i den här artikeln visar hur du returnerar resultat på sidor. Mer information om sidnumreringsbegrepp finns i Sidnumrering med Azure SDKs för .NET.

Filtrera resultat med ett prefix

Om du vill filtrera listan över blobar anger du en sträng för parametern prefix . Prefixsträngen kan innehålla ett eller flera tecken. Azure Storage returnerar sedan endast de blobar vars namn börjar med prefixet.

Returnera metadata

Du kan returnera blobmetadata med resultatet genom att ange metadatavärdet för BlobTraits-uppräkningen .

Flat listning jämfört med hierarkisk lista

Blobar i Azure Storage är ordnade i ett platt paradigm snarare än ett hierarkiskt paradigm (som ett klassiskt filsystem). Du kan dock ordna blobar i virtuella kataloger för att efterlikna en mappstruktur. En virtuell katalog utgör en del av blobens namn och indikeras av avgränsartecknet.

Om du vill organisera blobar i virtuella kataloger använder du ett avgränsartecken i blobnamnet. Standardtecken för avgränsare är ett snedstreck (/), men du kan ange valfritt tecken som avgränsare.

Om du namnger dina blobar med en avgränsare kan du välja att lista blobar hierarkiskt. För en hierarkisk listningsåtgärd returnerar Azure Storage alla virtuella kataloger och blobbar under det överordnade objektet. Du kan anropa listningsåtgärden rekursivt för att korsa hierarkin, ungefär som du skulle gå igenom ett klassiskt filsystem programmatiskt.

Använd en platt lista

Som standard returnerar en liståtgärd blobar i en platt lista. I en platt lista är blobbar inte organiserade i en virtuell katalog.

Följande exempel listar blobsen i den angivna behållaren genom att använda en platt listning, med en valfri segmentstorlek angiven, och skriver blobnamnet till ett konsolfönster.

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

Exempelutdata liknar:

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

Använda en hierarkisk lista

När du anropar en liståtgärd hierarkiskt returnerar Azure Storage de virtuella katalogerna och blobarna på den första nivån i hierarkin.

För att lista blobs hierarkiskt, anropa BlobContainerClient.GetBlobsByHierarchy eller BlobContainerClient.GetBlobsByHierarchyAsync-metoden .

Följande exempel listar blobsen i den angivna behållaren genom att använda en hierarkisk listning, med en valfri segmentstorlek angiven, och skriver blobnamnet till konsolfönstret.

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

Exempelutdata liknar:

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

Visa blobversioner eller ögonblicksbilder

Om du vill visa en lista över blobversioner eller ögonblicksbilder anger du parametern BlobStates med fältet Version eller Ögonblicksbild. Tjänsten returnerar versioner och ögonblicksbilder från äldsta till nyaste.

Följande kodexempel visar hur du listar blobversioner.

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

Listablobbar i Apache Arrow-format (förhandsvisning)

Denna funktion bygger på det befintliga List Blobs API:et. Istället för att använda standard-XML använder den det kompakta, kolumnarformade Apache Arrow-formatet som svarsformat på tråden. Du aktiverar det genom att ställa in ett enda alternativ i containerlisting-anropet. .NET SDK avkodar Apache Arrow bakom kulisserna och returnerar fortfarande samma BlobItem objekt. Denna metod förbättrar listningskapaciteten och minskar klientsidans CPU vid uppräkning av stora containrar. Det bevarar det responsavtal som applikationer är beroende av.

För att begära Apache Arrow-formaterade resultat, ställ in egenskapen ResponseFormat för GetBlobsOptions till StorageResponseFormat.Arrow och skicka sedan alternativen till BlobContainerClient.GetBlobs-överbelastningen som accepterar GetBlobsOptions. När du använder Apache Arrow-utgången kan du också ställa in StartFrom och EndBefore egenskaperna för att styra intervallet av vägar som returneras.

Följande exempel listar blobsen i en container och begär resultaten i Apache Arrow-format:

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

Resurser

För att lära dig mer om hur man listar blobs genom att använda Azure Blob Storage-klientbiblioteket för .NET, se följande resurser.

REST API-åtgärder

Azure SDKs för .NET innehåller bibliotek som bygger ovanpå Azure REST API. Genom att använda dessa bibliotek kan du interagera med REST API-operationer via välkända .NET-paradigm. Klientbiblioteksmetoderna för att visa blobar använder följande REST API-åtgärd:

• Lista blobar (REST API)

Klientbiblioteksresurser

• Referensdokumentation för klientbibliotek
• Källkod för klientbibliotek
• Package (NuGet)

Se även

• Räkna upp blobresurser
• Blobversionshantering

Relaterat innehåll

• Den här artikeln är en del av utvecklarguiden för Blob Storage för .NET. Mer information finns i den fullständiga listan över utvecklarguideartiklar i Skapa din .NET-app.