使用 .NET 上傳 Blob

• .NET
• Java
• JavaScript
• Python
• Go

本文說明如何使用適用於 .NET 的 Azure 儲存體用戶端程式庫來上傳 Blob。 您可以從檔案路徑、資料流、二進位物件或文字字串將資料上傳至區塊 Blob。 您也可以開啟 Blob 串流並寫入到該串流，或在區塊中上傳大型 Blob。

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• 適用於您作業系統的最新 .NET SDK。 請務必取得 SDK，而不是執行階段。

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫。 這些步驟包括封裝安裝、新增 using 指示詞，以及建立已授權的用戶端物件。 如需詳細資訊，請參閱 開始使用 Azure Blob 儲存體和 .NET。

安裝套件

從您的專案目錄中，使用 dotnet add package 命令安裝 Azure Blob 儲存體和 Azure 身分識別客戶端程式庫的套件。 需要 Azure.Identity 套件才能對 Azure 服務進行無密碼連線。

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

新增 using 指示詞

將這些 using 指示詞新增至程式碼檔案頂端：

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

本文中的某些程式碼範例可能需要其他using指示詞。

建立用戶端物件

若要將應用程式連線至 Blob 儲存體，請建立 BlobServiceClient類別的執行個體。 下列範例示範如何使用 DefaultAzureCredential 來建立用戶端物件以進行授權：

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

    return client;
}

您可以在 .NET 應用程式中註冊相依性插入的服務用戶端。

您也可以為特定容器或 Blob 建立客戶端物件。 若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

授權

授權機制必須具有上傳 Blob 的必要權限。 如需使用 Microsoft Entra ID 授權 (建議使用)，您需要 Azure RBAC 內建角色儲存體 Blob 資料參與者或更高權限。 若要深入了解，請參閱放置 Blob (REST API) 和放置區塊 (REST API)的授權指引。

將資料上傳至區塊 Blob

您可以使用下列其中一種方法，將資料上傳至區塊 Blob：

• 上傳
• UploadAsync

使用這些上傳方法時，用戶端程式庫可能會呼叫 Put Blob 或一系列 Put Block 呼叫，後面接著放置區塊清單。 此行為取決於物件的整體大小，以及設定資料傳輸選項的方式。

若要在 Blob 儲存體開啟串流並寫入該串流，請使用下列其中一種方法：

• OpenWrite
• OpenWriteAsync

從本機檔案路徑上傳區塊 Blob

下列範例會從本機檔案路徑上傳區塊 Blob：

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

從資料流上傳區塊 Blob

下列範例會藉由建立串流物件並上傳串流來上傳區塊 Blob。

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

從 BinaryData 物件上傳區塊 Blob

下列範例會從 BinaryData 物件上傳區塊 Blob。

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

從字串上傳區塊 Blob

下列範例會從字串上傳區塊 Blob：

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

上傳至 Blob 儲存體中的串流

您可以在 Blob 儲存體開啟串流，並將寫入。 下列範例會在 Blob 儲存體中建立 zip 檔案，並將檔案寫入其中。 一次只有一個檔案位於記憶體中，而不是在本機記憶體中組建 zip 檔案。

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

使用設定選項上傳區塊 Blob

您可以在上傳 Blob 時定義用戶端程式庫設定選項。 這些選項也可進行調整，以改善效能、增強可靠性，並將成本最佳化。 下列程式碼範例示範如何在呼叫上傳方法時，使用 BlobUploadOptions 來定義設定選項。

指定資料傳輸在上傳時的選項

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

public static async Task UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

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

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

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

指定上傳時的傳輸驗證選項

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

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

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

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

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

注意

如果要求中指定的總和檢查碼不符合服務計算的總和檢查碼，上傳作業就會失敗。 使用預設重試原則時，不會重試作業。 在 .NET 中，會擲回 RequestFailedException，並帶有狀態碼 400 和錯誤碼 Md5Mismatch 或 Crc64Mismatch，取決於使用的​​演算法。

使用索引標記上傳

Blob 索引標記會使用索引鍵/值標記屬性，將儲存體帳戶中的資料分類。 這些標記會自動編製索引，並公開為可搜尋的多維度索引，以便輕鬆地尋找資料。 您可以將標籤新增至 BlobUploadOptions 執行個體，並將該執行個體傳遞至 UploadAsync 方法。

下列範例會使用索引標籤上傳區塊 Blob：

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

設定 Blob 在上傳時的存取層

您可以使用 BlobUploadOptions 類別在 Blob 上傳時設定存取層。 下列程式碼範例顯示如何在上傳 Blob 時設定存取層：

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

只有區塊 Blob 才能設定存取層。 您可以將區塊 Blob 的存取層設定為 Hot、Cool、Cold 或 Archive。 若要將存取層設定為 Cold，您必須最少使用用戶端程式庫版本 12.15.0。

若要深入了解存取層，請參閱存取層概觀。

使用暫存區塊和認可上傳區塊 Blob

您可以手動暫存個別資料區塊，以進一步控制如何將上傳項目分割成區塊。 當組成 Blob 的所有區塊都暫存時，您可以將這些區塊認可至 Blob 儲存體。 您可以使用此方法，藉由平行上傳區塊來增強效能。

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

資源

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

程式碼範例

• 檢視本文中的程式碼範例 (GitHub) (英文)

REST API 操作

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

• 放置 Blob (REST API)
• 放置區塊 (REST API)

另請參閱

• 上傳和下載的效能微調。
• 使用 Blob 索引標籤來管理及尋找 Azure Blob 資料
• 使用 Blob 索引標籤來管理和尋找 Azure Blob 儲存體上的資料

相關內容

• 本文是適用於 .NET 的 Blob 儲存體開發人員指南的一部分。 若要深入了解，請參閱位於建置 .NET 應用程式的開發人員指南文章完整清單。