使用 .NET 下載 Blob

  • 發行項

本文說明如何使用適用於 .NET 的 Azure 儲存體用戶端程式庫來下載 Blob。 您可以將 Blob 資料下載到各種目的地，包括本機檔案路徑、串流或文字字串。 您也可以開啟 Blob 串流並從中讀取。

必要條件

  • 本文假設您已有專案設定好要使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫。 若要了解設定專案的相關事宜 (包括套件安裝、新增 using 個指示詞以及建立授權的用戶端物件)，請參閱開始使用 Azure Blob 儲存體和 .NET。
  • 授權機制必須具有執行下載作業的權限。 若要深入了解，請參閱下列 REST API 作業的授權指導：

下載 Blob

您可以使用下列任一方法來下載 Blob：

您也可以開啟串流以讀取 Blob。 串流只會下載讀取來源的 Blob。 您可以使用下列其中一種方法：

下載至檔案路徑

下列範例將 Blob 下載至本機檔案路徑。 如果指定的目錄不存在，程式碼會擲回 DirectoryNotFoundException。 如果檔案已存在於 localFilePath，則後續下載期間會根據預設覆寫該檔案。

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

下載至串流

下列範例下載 Blob 的方式為建立 Stream 物件，然後下載至該串流。 如果指定的目錄不存在，程式碼會擲回 DirectoryNotFoundException。

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

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

下載至字串

下列範例假設 Blob 是文字檔，並將 Blob 下載至字串：

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

從資料流下載

下列範例下載 Blob 的方式為讀取串流：

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

使用設定選項下載區塊 Blob

您可以在下載 Blob 時定義用戶端程式庫設定選項。 這些選項也可進行調整，以改善效能及增強可靠性。 下列程式碼範例示範如何在呼叫下載方法時，使用 BlobDownloadToOptions 定義設定選項。 請注意，BlobDownloadOptions 也適用於相同選項。

指定下載時的資料傳輸選項

您可以在 StorageTransferOptions 中設定值，以改善資料傳輸作業的效能。 下列程式碼範例示範如何設定 StorageTransferOptions 的值，並在 BlobDownloadToOptions 執行個體中包含選項。 此範例中提供的值並非旨在作為建議。 若要正確調整這些值，您必須考慮應用程式的特定需求。

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

若要深入了解微調資料傳輸選項，請參閱上傳和下載的效能微調。

指定下載時的傳輸驗證選項

您可以指定傳輸驗證選項，協助確保資料已正確下載，且傳輸期間未遭到竄改。 您可以使用 BlobClientOptions 在用戶端層級定義傳輸驗證選項，其會將驗證選項套用至從 BlobClient 執行個體呼叫的所有方法。

您也可以使用 BlobDownloadToOptions 在方法層級覆寫傳輸驗證選項。 下列程式碼範例示範如何建立 BlobDownloadToOptions 物件，並指定用於產生總和檢查碼的演算法。 然後，服務會使用總和檢查碼來驗證下載內容的資料完整性。

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

下表顯示總和檢查碼演算法的可用選項，如 StorageChecksumAlgorithm 所定義：

名稱 數值 描述
自動 0 建議使用。 允許程式庫選擇演算法。 不同的程式庫版本可能會選擇不同的演算法。
無 1 未選取演算法。 請勿計算或要求總和檢查碼。
MD5 2 標準 MD5 雜湊演算法。
StorageCrc64 3 Azure 儲存體自訂 64 位元 CRC。

資源

若要深入了解如何使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫下載 Blob，請參閱下列資源。

REST API 操作

適用於 .NET 的 Azure SDK 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 .NET 範例與 REST API 作業進行互動。 用來下載 Blob 的用戶端程式庫方法會使用下列 REST API 作業：

程式碼範例

用戶端程式庫資源

另請參閱