使用 .NET 上傳 Blob
本文說明如何使用適用於 .NET 的 Azure 儲存體用戶端程式庫來上傳 Blob。 您可以從檔案路徑、資料流、二進位物件或文字字串將資料上傳至區塊 Blob。 您也可以開啟 Blob 串流並寫入到該串流,或在區塊中上傳大型 Blob。
必要條件
設定您的環境
如果您沒有現有的專案,本節將說明如何設定專案以使用適用於 .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 的必要許可權。 如需具有 Microsoft Entra ID 的授權(建議),您需要 Azure RBAC 內建角色 記憶體 Blob 數據參與者 或更高版本。 若要深入瞭解,請參閱放置 Blob(REST API) 和放置區塊 (REST API) 的授權指引。
將資料上傳至區塊 Blob
您可以使用下列其中一種方法,將資料上傳至區塊 Blob:
使用這些上傳方法時,用戶端程式庫可能會呼叫 Put Blob 或一系列 Put Block 呼叫,後面接著放置區塊清單。 此行為取決於物件的整體大小,以及設定資料傳輸選項的方式。
若要在 Blob 儲存體開啟串流並寫入該串流,請使用下列其中一種方法:
從本機檔案路徑上傳區塊 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,請參閱下列資源。
REST API 操作
適用於 .NET 的 Azure SDK 包含建置在 Azure REST API 之上的程式庫,可讓您透過熟悉的 .NET 範例與 REST API 作業進行互動。 用來上傳 BLOb 的用戶端程式庫方法會使用下列 REST API 作業: