创建和管理与数据资源交互的客户端对象

Azure SDK 是库的集合,旨在更轻松地使用不同语言的 Azure 服务。 SDK 旨在简化应用程序与 Azure 资源之间的交互。 使用 SDK 处理 Azure 资源从创建客户端实例开始。 本文介绍了如何创建客户端对象以在 Azure Blob 存储 中与数据资源交互,并提供有关如何在应用程序中管理客户端的最佳做法。

关于客户端对象

Azure Blob 存储客户端库允许与存储服务中三种类型的资源进行交互:

  • 存储帐户
  • Blob 容器
  • Blob

根据应用程序的需求,可以在这三个级别中的任何一个创建客户端对象。

对于 blob,有常规的 blob 客户端,它涵盖跨所有类型(块 blob、追加 blob 和页 blob)的常见 blob 操作,且每种类型都有专用的 blob 客户端。

下表列出了每种语言的不同客户端类:

语言 服务客户端类 容器客户端类 Blob 客户端类
.NET Azure.Storage.Blobs
Azure.Storage.Blobs.Models
Azure.Storage.Blobs.Specialized
BlobServiceClient BlobContainerClient BlobClient
BlockBlobClient
AppendBlobClient
PageBlobClient
Java com.azure.storage.blob
com.azure.storage.blob.models
com.azure.storage.blob.specialized
BlobServiceClient
BlobServiceAsyncClient
BlobServiceClientBuilder
BlobContainerClient
BlobContainerAsyncClient
BlobContainerClientBuilder
BlobClient
BlobAsyncClient
BlobClientBuilder
BlockBlobClient
AppendBlobClient
PageBlobClient
JavaScript @azure/storage-blob BlobServiceClient ContainerClient BlobClient
BlockBlobClient
AppendBlobClient
PageBlobClient
Python azure.storage.blob BlobServiceClient ContainerClient BlobClient1

1 对于 Python,BlobClient 包括专用 blob 类型的方法。

可以调用简单的构造函数或采用各种配置选项的重载,从而实例化每种客户端类型。 对于 Java,每种客户端类型都有单独的类,该类提供生成器 API 以帮助进行配置和实例化。 根据语言 SDK,这些客户端配置选项以不同方式传递给构造函数。 有关详细信息,请参阅表中的类引用。

授权客户端对象

要使应用访问 blob 资源并与之交互,必须授权客户端对象。 本文中的代码示例使用 DefaultAzureCredential 通过 Microsoft Entra 安全主体向 Azure 进行身份验证。 身份验证过程包括获取用于授权的访问令牌。 实例化客户端时,此访问令牌作为凭据传递,且该凭据在整个客户端生存期内一直存在。 必须为请求令牌的 Microsoft Entra 安全主体分配适当的 Azure RBAC 角色,从而授予对 Blob 数据的访问权限。 要了解详细信息,请参阅 分配 Azure 角色以访问 blob 数据

可以使用以下授权机制向客户端对象授予适当的访问级别:

要了解有关授权的详细信息,请参阅 授权访问 Azure 存储中的数据

创建客户端对象

使用 SDK 处理任何 Azure 资源从创建客户端对象开始。 在本节中,你会了解如何创建客户端对象以与存储服务中三种类型的资源进行交互: 存储帐户、容器和 blob。

当应用程序创建客户端对象时,你会向客户端构造函数传递一个引用终结点的 URI。 可以手动构造终结点字符串(如本文中的示例所示),也可以在运行时使用 Azure 存储管理库查询终结点。 要了解如何查询终结点,请参阅查询 Blob 存储终结点

创建 BlobServiceClient 对象

授权的 BlobServiceClient 对象允许应用在存储帐户级别与资源交互。 BlobServiceClient 提供检索和配置帐户属性以及列出、创建和删除存储帐户内容器的方法。 此客户端对象是与存储帐户中的资源交互的起点。

常见方案是实例化单个服务客户端,然后根据需要从服务客户端创建容器客户端和 blob 客户端。 要使用特定的容器或 blob,可以使用 BlobServiceClient 对象创建 容器客户端blob 客户端。 从 BlobServiceClient 创建的客户端将继承其客户端配置,包括客户端选项和凭据。

以下示例演示了如何创建 BlobServiceClient 对象:

然后,添加以下 using 指令:

using Azure.Identity;
using Azure.Storage.Blobs;

添加以下代码以创建客户端对象:

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

    return client;
}

创建 BlobContainerClient 对象

可以使用 BlobServiceClient 对象以新建 BlobContainerClient 对象(ContainerClient 为 JavaScript 和 Python)。 对象 BlobContainerClient 允许与特定容器资源交互。 此资源不需要存在于存储帐户中,即可创建客户端对象。 BlobContainerClient 提供创建、删除或配置容器的方法,并包括列出、上传和删除容器内 blob 的方法。 要对容器内的特定 blob 执行操作,可以 创建 blob 客户端

以下示例演示了如何从 BlobServiceClient 对象创建容器客户端,从而与特定容器资源交互:

public BlobContainerClient GetBlobContainerClient(
    BlobServiceClient blobServiceClient,
    string containerName)
{
    // Create the container client using the service client object
    BlobContainerClient client = blobServiceClient.GetBlobContainerClient(containerName);
    return client;
}

如果工作的范围限定为单个容器,可以选择在不使用 BlobServiceClient的情况下直接创建 BlobContainerClient 对象。 仍然可以像在服务客户端上一样在容器客户端上设置客户端选项。

以下示例演示了如何在 使用 BlobServiceClient 的情况下直接创建容器客户端:

public BlobContainerClient GetBlobContainerClient(
    string accountName,
    string containerName,
    BlobClientOptions clientOptions)
{
    // Append the container name to the end of the URI
    BlobContainerClient client = new(
        new Uri($"https://{accountName}.blob.core.chinacloudapi.cn/{containerName}"),
        new DefaultAzureCredential(),
        clientOptions);

    return client;
}

创建 BlobClient 对象

要与特定 blob 资源交互,请从服务客户端或容器客户端创建 BlobClient 对象。 对象 BlobClient 允许与特定的 blob 资源交互。 此资源不需要存在于存储帐户中,即可创建客户端对象。 BlobClient 提供上传、下载、删除和创建 blob 快照的方法。

以下示例演示了如何创建 blob 客户端以与特定的 blob 资源交互:

public BlobClient GetBlobClient(
    BlobServiceClient blobServiceClient,
    string containerName,
    string blobName)
{
    BlobClient client =
        blobServiceClient.GetBlobContainerClient(containerName).GetBlobClient(blobName);
    return client;
}

管理客户端对象

管理 Azure SDK 客户端的最佳做法是将客户端视为单一实例,这意味着一个类一次只有一个对象。 无需为一组给定的构造函数参数或客户端选项保留多个客户端实例。 可以通过多种方式实现此概念,包括:

  • 创建单个客户端对象并将其作为参数在整个应用程序中传递。 本文的代码示例中介绍了此方法。
  • 在字段中存储客户端实例。 要了解有关 C# 字段的详细信息,请参阅 字段(C# 编程指南)
  • 在所选的依赖项注入容器中将客户端对象注册为单一实例。 有关 ASP.NET Core 应用中依赖项注入的详细信息,请参阅 使用用于 .NET 的 Azure SDK 进行依赖关系注入

与为所需的每个客户端调用构造函数相比,此方法在大规模上效率要高得多。

客户端不可变性和线程安全性

Azure SDK 客户端在创建后是不可变的,这意味着无法更改它连接到的终结点、用于授权的凭据或作为客户端选项传入的其他值。 客户端不可变性还意味着客户端可以安全地在整个应用程序中共享和重复使用。

如果应用需要为相同类型的客户端使用不同的配置或凭据,可以针对每组配置选项实例化客户端。

Azure SDK 保证所有客户端实例方法都线程安全且彼此独立。 此设计可确保共享和重复使用客户端实例始终安全,即使是跨线程也是如此。

后续步骤

要详细了解如何使用 Azure 存储客户端库处理数据资源,请参阅以下文章: