快速入门:适用于 .NET 的 Azure Blob 存储客户端库
适用于 .NET 的 Azure Blob 存储客户端库入门。 Azure Blob 存储是适用于云的 Azure 的对象存储解决方案,针对存储海量非结构化数据进行了优化。
API 参考文档 | 库源代码 | 包 (NuGet) | 示例
先决条件
设置
本部分逐步指导如何准备一个项目,使其与适用于 .NET 的 Azure Blob 存储客户端库配合使用。
创建项目
使用 .NET CLI 或 Visual Studio 2022 创建 .NET 控制台应用。
在 Visual Studio 顶部,导航到“文件”>“新建”>“项目”。
在对话框窗口中,在项目模板搜索框中输入“控制台应用”,然后选择第一个结果。 选择对话框底部的“下一步”。
对于“项目名称”,请输入“BlobQuickstart”。 保留其余字段的默认值,然后选择“下一步”。
对于 Framework,请确保已选择最新安装版本的 .NET。 然后选择“创建”。 此时新项目在 Visual Studio 环境中打开。
安装包
若要与 Azure Blob 存储交互,请安装适用于 .NET 的 Azure Blob 存储客户端库。
在解决方案资源管理器中,右键单击项目的“依赖项”节点。 选择“管理 NuGet 包”。
在出现的窗口中,搜索 Azure.Storage.Blobs。 选择相应的结果,然后选择“安装”。
设置应用代码
替换 Program.cs
文件中的起始代码,使其与以下示例匹配,其中包括本练习所需的 using
语句。
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");
对象模型
Azure Blob 存储最适合存储巨量的非结构化数据。 非结构化数据并不遵循特定数据模型或定义(如文本或二进制数据)。 Blob 存储提供了三种类型的资源:
- 存储帐户
- 存储帐户中的容器
- 容器中的 blob
以下图示显示了这些资源之间的关系。
使用以下 .NET 类与这些资源进行交互:
- BlobServiceClient:
BlobServiceClient
类可用于操纵 Azure 存储资源和 blob 容器。 - BlobContainerClient:
BlobContainerClient
类可用于操纵 Azure 存储容器及其 blob。 - BlobClient:
BlobClient
类可用于操纵 Azure 存储 blob。
代码示例
以下部分中的示例代码片段演示如何使用适用于 .NET 的 Azure Blob 存储客户端库执行以下任务:
重要
如设置部分所述,请确保已安装正确的 NuGet 包并添加了必要的 using 语句以使代码示例能够正常工作。
向 Azure 进行身份验证并授权访问 Blob 数据
对 Azure Blob 存储的应用程序请求必须获得授权。 要在代码中实现与 Azure 服务(包括 Blob 存储)的无密码连接,推荐使用 azure-identity 客户端库提供的 DefaultAzureCredential
类。
你还可以使用帐户访问密钥授权对 Azure Blob 存储的请求。 但是,应谨慎使用此方法。 开发人员必须尽量避免在不安全的位置公开访问密钥。 具有访问密钥的任何人都可以授权针对存储帐户的请求,并且实际上有权访问所有数据。 DefaultAzureCredential
提供比帐户密钥更好的管理和安全优势,来实现无密码身份验证。 以下示例演示了这两个选项。
DefaultAzureCredential
是适用于 .NET 的 Azure 标识客户端库提供的类,可在 DefaultAzureCredential 概述中了解有关该类的详细信息。 DefaultAzureCredential
支持多种身份验证方法,并确定应在运行时使用哪种方法。 通过这种方法,你的应用可在不同环境(本地与生产)中使用不同的身份验证方法,而无需实现特定于环境的代码。
有关 DefaultAzureCredential
查找凭据的顺序和位置,可查看 Azure 标识库概述。
例如,应用可在本地开发时使用 Visual Studio 登录凭据进行身份验证。 应用在部署到 Azure 后就可以使用托管标识。 此转换不需要进行任何代码更改。
将角色分配至 Microsoft Entra 用户帐户
在本地开发时,请确保访问 Blob 数据的用户帐户具有正确的权限。 需有“存储 Blob 数据参与者”角色才能读取和写入 Blob 数据。 若要为你自己分配此角色,需要具有“用户访问管理员”角色,或者具有包含 Microsoft.Authorization/roleAssignments/write 操作的其他角色。 可使用 Azure 门户、Azure CLI 或 Azure PowerShell 向用户分配 Azure RBAC 角色。 可以在范围概述页上详细了解角色分配的可用范围。
在此方案中,你将为用户帐户分配权限(范围为存储帐户)以遵循最低权限原则。 这种做法仅为用户提供所需的最低权限,并创建更安全的生产环境。
以下示例将“存储 Blob 数据参与者”角色分配给用户帐户,该角色提供对存储帐户中 Blob 数据的读取和写入访问权限。
重要
在大多数情况下,角色分配在 Azure 中传播需要一两分钟的时间,但极少数情况下最多可能需要 8 分钟。 如果在首次运行代码时收到身份验证错误,请稍等片刻再试。
在 Azure 门户中,使用主搜索栏或左侧导航找到存储帐户。
在存储帐户概述页的左侧菜单中选择“访问控制 (IAM)”。
在“访问控制 (IAM)”页上,选择“角色分配”选项卡。
从顶部菜单中选择“+ 添加”,然后从出现的下拉菜单中选择“添加角色分配”。
使用搜索框将结果筛选为所需角色。 在此示例中,搜索“存储 Blob 数据参与者”并选择匹配的结果,然后选择“下一步”。
在“访问权限分配对象”下,选择“用户、组或服务主体”,然后选择“+ 选择成员”。
在对话框中,搜索 Microsoft Entra ID 用户名(通常是 user@domain 电子邮件地址),然后选中对话框底部的“选择”。
选择“查看 + 分配”转到最后一页,然后再次选择“查看 + 分配”完成该过程。
使用 DefaultAzureCredential 登录并将应用代码连接到 Azure
可按照以下步骤授权访问存储帐户中的数据:
-
对于本地开发,请确保使用分配了该角色的同一 Microsoft Entra 帐户进行身份验证。 可以通过常用的开发工具(如 Azure CLI 或 Azure PowerShell)进行身份验证。 可用于进行身份验证的开发工具因语言而异。
使用以下命令通过 Azure CLI 登录到 Azure:
az login
-
若要使用
DefaultAzureCredential
,请将 Azure.Identity 包添加到应用程序。在解决方案资源管理器中,右键单击项目的“依赖项”节点。 选择“管理 NuGet 包”。
在出现的窗口中,搜索 Azure.Identity。 选择相应的结果,然后选择“安装”。
更新 Program.cs 代码以匹配以下示例。 在开发期间,当代码在本地工作站上运行时,它将使用已登录的优先工具的开发人员凭据向 Azure 进行身份验证,例如 Azure CLI 或 Visual Studio。
using Azure.Storage.Blobs; using Azure.Storage.Blobs.Models; using System; using System.IO; using Azure.Identity; // TODO: Replace <storage-account-name> with your actual storage account name var blobServiceClient = new BlobServiceClient( new Uri("https://<storage-account-name>.blob.core.chinacloudapi.cn"), new DefaultAzureCredential());
请确保在
BlobServiceClient
的 URI 中更新存储帐户名称。 可以在 Azure 门户的概述页上找到存储帐户名称。注意
部署到 Azure 时,同样的代码可用于授权从 Azure 中运行的应用程序对 Azure 存储的请求。 但是,需要在 Azure 中的应用上启用托管标识。 然后,配置你的存储帐户以允许该托管标识进行连接。 有关在 Azure 服务之间配置此连接的详细说明,请参阅 Azure 托管应用中的身份验证教程。
创建容器
通过在 blobServiceClient
对象上调用 CreateBlobContainerAsync 方法,在存储帐户中创建新容器。 在此示例中,代码将 GUID 值追加到容器名称,以确保它是唯一的。
在 Program.cs
文件的末尾添加以下代码:
// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
new Uri("https://<storage-account-name>.blob.core.chinacloudapi.cn"),
new DefaultAzureCredential());
//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();
// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);
若要详细了解如何创建容器并浏览更多代码示例,请参阅使用 .NET 创建 Blob 容器。
重要
容器名称必须为小写。 有关命名容器和 Blob 的详细信息,请参阅命名和引用容器、Blob 和元数据。
将 Blob 上传到容器中
使用 UploadAsync 将 blob 上传到容器。 示例代码将在本地数据目录中创建文本文件以上传到容器。
在 Program.cs
文件的末尾添加以下代码:
// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);
// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");
// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);
Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);
// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);
若要详细了解如何上传 Blob 并浏览更多代码示例,请参阅使用 .NET 上传 Blob。
列出容器中的 Blob
通过调用 GetBlobsAsync 方法,列出容器中的 blob。
在 Program.cs
文件的末尾添加以下代码:
Console.WriteLine("Listing blobs...");
// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
Console.WriteLine("\t" + blobItem.Name);
}
若要详细了解如何列出 Blob 并浏览更多代码示例,请参阅使用 .NET 列出 Blob。
下载 blob
通过调用 DownloadToAsync 方法下载之前创建的 blob。 示例代码会将字符串“DOWNLOADED”追加到文件名,以便你可以在本地文件系统中看到这两个文件。
在 Program.cs
文件的末尾添加以下代码:
// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");
Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);
// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);
若要详细了解如何下载 Blob 并浏览更多代码示例,请参阅使用 .NET 下载 Blob。
删除容器
以下代码将使用 DeleteAsync 来删除容器,以清理应用创建的资源。 该代码示例还会删除应用创建的本地文件。
在删除 blob、容器和本地文件之前,应用会调用 Console.ReadLine
以暂停并等待用户输入。 可以通过此机会验证是否已正确创建资源,然后再删除这些资源。
在 Program.cs
文件的末尾添加以下代码:
// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();
Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();
Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);
Console.WriteLine("Done");
若要详细了解如何删除容器并浏览更多代码示例,请参阅使用 .NET 删除和还原 Blob 容器。
完成的代码
完成这些步骤后,Program.cs
文件中的代码现在应如下所示:
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;
// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
new Uri("https://<storage-account-name>.blob.core.chinacloudapi.cn"),
new DefaultAzureCredential());
//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();
// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);
// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);
// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");
// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);
Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);
// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);
Console.WriteLine("Listing blobs...");
// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
Console.WriteLine("\t" + blobItem.Name);
}
// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");
Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);
// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);
// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();
Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();
Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);
Console.WriteLine("Done");
运行代码
此应用在本地 data 文件夹中创建测试文件,并将其上传到 Blob 存储。 然后,该示例会列出容器中的 blob,并使用新名称下载文件,这样便可对新旧文件进行对比。
如果使用 Visual Studio,请按 F5 生成并运行代码,并与控制台应用交互。 如果使用的是 .NET CLI,请导航到应用程序目录,然后生成并运行该应用程序。
dotnet build
dotnet run
应用的输出类似于以下示例(为便于阅读,省略了 GUID 值):
Azure Blob Storage - .NET quickstart sample
Uploading to Blob storage as blob:
https://mystorageacct.blob.core.chinacloudapi.cn/quickstartblobsGUID/quickstartGUID.txt
Listing blobs...
quickstartGUID.txt
Downloading blob to
./data/quickstartGUIDDOWNLOADED.txt
Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done
在开始清理过程之前,请在“data”文件夹中查看这两个文件。 可打开它们,然后就会看到它们完全相同。
清理资源
验证文件并完成测试后,请按 Enter 键删除测试文件以及在存储帐户中创建的容器。 还可以使用 Azure CLI 来删除资源。