Sdílet prostřednictvím

Stažení objektu blob pomocí .NET

  • Článek

Tento článek ukazuje, jak stáhnout objekt blob pomocí klientské knihovny Azure Storage pro .NET. Data objektů blob si můžete stáhnout do různých cílů, včetně místní cesty k souboru, datového proudu nebo textového řetězce. Můžete také otevřít datový proud objektů blob a číst z něj.

Požadavky

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řidání using direktiv

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 vytvořit objekt klienta pro DefaultAzureCredential 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 injektáž 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 provedení operace stahování. K autorizaci pomocí Microsoft Entra ID (doporučeno) potřebujete integrovanou roli Storage Blob Data Reader služby Azure RBAC nebo vyšší. Další informace najdete v pokynech pro autorizaci k získání objektu blob (REST API).

Stažení objektu blob

Ke stažení objektu blob můžete použít některou z následujících metod:

Můžete také otevřít datový proud pro čtení z objektu blob. Stream stáhne objekt blob pouze při čtení datového proudu. Můžete použít kteroukoli z těchto metod:

Stažení do cesty k souboru

Následující příklad stáhne objekt blob do místní cesty k souboru. Pokud zadaný adresář neexistuje, vyvolá kód výjimku DirectoryNotFoundException. Pokud soubor již existuje localFilePath, při následném stahování se ve výchozím nastavení přepíše.

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

Stažení do streamu

Následující příklad stáhne objekt blob vytvořením objektu Stream a následným stažením do tohoto datového proudu. Pokud zadaný adresář neexistuje, vyvolá kód výjimku DirectoryNotFoundException.

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Stažení do řetězce

Následující příklad předpokládá, že objekt blob je textový soubor a stáhne objekt blob do řetězce:

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

Stažení ze streamu

Následující příklad stáhne objekt blob čtením ze streamu:

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

Stažení objektu blob bloku s možnostmi konfigurace

Při stahování objektu blob můžete definovat možnosti konfigurace klientské knihovny. Tyto možnosti je možné ladit, aby se zlepšil výkon a zvýšil spolehlivost. Následující příklady kódu ukazují, jak použít BlobDownloadToOptions k definování možností konfigurace při volání metody stahování. Všimněte si, že stejné možnosti jsou k dispozici pro BlobDownloadOptions.

Určení možností přenosu dat při stahování

Hodnoty v StorageTransferOptions můžete nakonfigurovat tak, aby se zlepšil výkon operací přenosu dat. Následující příklad kódu ukazuje, jak nastavit hodnoty a StorageTransferOptions zahrnout možnosti jako součást BlobDownloadToOptions instance. Hodnoty uvedené v této ukázce nejsou určené jako doporučení. Pokud chcete tyto hodnoty správně vyladit, musíte zvážit konkrétní potřeby vaší aplikace.

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

Další informace o ladění možností přenosu dat najdete v tématu Ladění výkonu pro nahrávání a stahování.

Zadání možností ověření přenosu při stahování

Můžete zadat možnosti ověření přenosu, které vám pomůžou zajistit, že se data stáhnou správně a nebudou během přenosu manipulována. Možnosti ověření přenosu je možné definovat na úrovni klienta pomocí Objektů blobClientOptions, které používají možnosti ověřování pro všechny metody volané z instance BlobClient .

Můžete také přepsat možnosti ověřování přenosu na úrovni metody pomocí BlobDownloadToOptions. Následující příklad kódu ukazuje, jak vytvořit BlobDownloadToOptions objekt a zadat algoritmus pro generování kontrolního součtu. Kontrolní součet pak služba použije k ověření integrity dat staženého obsahu.

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

Následující tabulka ukazuje dostupné možnosti pro algoritmus kontrolního součtu, jak je definováno storageChecksumAlgorithm:

Jméno Hodnota Popis
Automaticky 0 Doporučený způsob: Umožňuje knihovně zvolit algoritmus. Různé verze knihoven můžou zvolit různé algoritmy.
Nic 0 Žádný vybraný algoritmus. Nevypočítávejte kontrolní součty ani nepožadujte.
MD5 2 Standardní hashovací algoritmus MD5
StorageCrc64 3 Vlastní 64bitová verze CRC služby Azure Storage

Zdroje informací

Další informace o tom, jak stáhnout objekty blob pomocí klientské knihovny služby Azure Blob Storage pro .NET, najdete v následujících zdrojích informací.

Ukázky kódu

Operace rozhraní REST API

Sada Azure SDK pro .NET obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat .NET. Metody klientské knihovny pro stahování 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.