本文說明如何使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫來連線至 Azure Blob 儲存體。 連線後,請使用 開發人員指南 來了解您的程式碼如何對 Blob 儲存體服務中的容器、Blob 和功能進行操作。
如果您想先從完整範例著手,請參閱 快速入門:適用於 .NET 的 Azure Blob 儲存體用戶端程式庫。
API 參考 | 程式庫原始程式碼 | 套件 (NuGet) | 範例 | 提供意見反應
必要條件
設定您的專案
本節會引導您準備專案以搭配使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫。
從您的專案目錄中,使用 dotnet add package 命令安裝 Azure Blob 儲存體和 Azure 身分識別客戶端程式庫的套件。 需要 Azure.Identity 套件才能對 Azure 服務進行無密碼連線。
dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity
將這些 using 指示詞新增至程式碼檔案頂端:
using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;
Blob 用戶端程式庫資訊:
Azure.Storage.Blobs:包含可用來操作服務、容器和 Blob 的主要類別 (「用戶端物件」)。
Azure.Storage.Blobs.Specialized:包含您可用來執行特定 Blob 類型專屬作業的類別,例如區塊 Blob。
Azure.Storage.Blobs.Models:所有其他公用程式類別、結構和列舉類型。
授權存取權並連線到 Blob 儲存體
若要將應用程式連線至 Blob 儲存體,請建立 BlobServiceClient 類別的執行個體。 此物件是您與儲存體帳戶層級的資料資源互動的起點。 使用它來操作儲存體帳戶及其容器。 您也可以使用服務用戶端來建立容器用戶端或 Blob 用戶端,視您需要使用的資源而定。
若要進一步了解如何建立及管理用戶端物件,請參閱 建立及管理與資料資源互動的用戶端物件。
透過使用 Microsoft Entra 授權憑證、帳號存取金鑰或共享存取簽章(SAS)授權 BlobServiceClient 物件。 為了實現最佳安全性,Microsoft 建議使用具有受控識別的 Microsoft Entra ID 來授權針對 Blob 資料的要求。 如需更多資訊,請參閱使用 Microsoft Entra ID 授與 Blob 的存取權。
若要使用 Microsoft Entra ID 授權,請使用安全性主體。 您需要的安全性主體類型取決於您的應用程式執行位置。 使用下表做為指引。
| 應用程式的執行位置 | 安全性主體 | 指引 |
|---|---|---|
| 本機電腦 (開發和測試) | 服務主體 | 若要了解如何註冊應用程式、設定 Microsoft Entra 群組、指派角色及設定環境變數,請參閱 使用開發人員服務主體授權存取 |
| 本機電腦 (開發和測試) | 使用者身分識別 | 若要了解如何設定 Microsoft Entra 群組、指派角色並登入 Azure,請參閱 使用開發人員認證授權存取 |
| 裝載於 Azure 中 | 受控識別 | 若要瞭解如何啟用受控識別並指派角色,請參閱使用 系統指派的受控識別 或 使用者指派的受控識別來授權存取的指引 |
| 託管於 Azure 之外(例如內部部署應用程式) | 服務主體 | 若要了解如何註冊應用程式、指派角色及設定環境變數,請參閱 使用應用程式服務主體從内部部署應用程式授權存取 |
使用 DefaultAzureCredential 授權存取
一個簡單且安全的授權存取與Blob 儲存體連線方式是建立一個 DefaultAzureCredential 實例,取得 OAuth 令牌。 用那個憑證建立 一個 BlobServiceClient 物件。
下列範例會建立使用 BlobServiceClient 授權的 DefaultAzureCredential 物件:
public BlobServiceClient GetBlobServiceClient(string accountName)
{
BlobServiceClient client = new(
new Uri($"https://{accountName}.blob.core.windows.net"),
new DefaultAzureCredential());
return client;
}
如果你確切知道要用哪種憑證類型來驗證使用者,你可以透過 Azure Identity 客戶端庫中的其他類別取得 OAuth 憑證,針對 .NET。 這些類別衍生自 TokenCredential 類別。
您也可以在 .NET 應用程式中註冊客戶端以進行相依性插入。 如需詳細資訊,請參閱 Azure SDK for .NET 中的相依性注入。
若要深入了解上述各種授權機制,請參閱授權存取 Azure 儲存體中的資料。
建置應用程式
當您建置應用程式以在 Azure Blob 儲存體中使用資料資源時,您的程式碼主要會與三種資源類型互動:儲存體帳戶、容器和 Blob。 若要深入了解這些資源類型、彼此的關係,以及應用程式如何與資源互動,請參閱了解應用程式如何與 Blob 儲存體資料資源互動。
下列指南示範如何使用適用於 .NET 的 Azure 儲存體 客戶端連結庫來存取數據並執行特定動作:
| 指南 | 描述 |
|---|---|
| 將資料附加至 Blob | 了解如何建立附加 Blob 物件,然後將資料附加到該 Blob 物件。 |
| 設定重試原則 | 實作用戶端作業的重試原則。 |
| 複製 Blob 物件 | 將 Blob 從一個位置複製到另一個位置。 |
| 建立容器 | 建立容器。 |
| 建立使用者委派 SAS | 建立容器或 Blob 的使用者委派 SAS。 |
| 建立及管理 Blob 租約 | 建立和管理 Blob 上的鎖定。 |
| 建立和管理容器租用 | 建立和管理容器上的鎖定。 |
| 刪除與還原 Blob 物件 | 刪除 Blob;如果已啟用虛刪除,則可還原已刪除的 Blob。 |
| 刪除和還原容器 | 刪除容器;如果已啟用虛刪除功能,則可還原已刪除的容器。 |
| 下載 Blob | 使用字串、資料流和檔案路徑下載 Blob 物件。 |
| 使用標籤尋找 Blob | 設定及取得標籤,並使用標籤尋找 Blob 物件。 |
| 列出 Blob 物件 | 以不同方式列出 Blob。 |
| 列出容器 | 列出帳戶中的容器,以及可用來自訂清單的各種選項。 |
| 管理屬性和中繼資料 | 取得及設定 Blob 的屬性及中繼資料。 |
| 管理屬性和中繼資料 | 取得和設定容器的屬性和中繼資料。 |
| 資料傳輸的效能微調 | 最佳化資料傳輸作業的效能。 |
| 設定或變更 Blob 的存取層 | 設定及變更區塊 Blob 的存取層。 |
| 上傳 Blob 物件 | 了解如何使用字串、串流、檔案路徑和其他方法來上傳 Blob。 |