你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

项目
08/05/2024

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	BlobClient¹

¹ 对于 Python，BlobClient 包括专用 blob 类型的方法。

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

授权客户端对象

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

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

Microsoft Entra ID：建议使用以获得最佳安全性
共享访问签名(SAS): 使用用户委派 SAS 令牌时受支持且最安全
帐户访问密钥(共享密钥): 受支持但不推荐，因为可能不太安全

要了解有关授权的详细信息，请参阅授权访问 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.windows.net"),
        new DefaultAzureCredential());

    return client;
}

然后，添加以下 import 指令：

import com.azure.identity.*;
import com.azure.storage.blob.*;

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

public BlobServiceClient GetBlobServiceClient(String accountName) {
    String endpointString = String.format("https://%s.blob.core.windows.net", accountName);
    BlobServiceClient client = new BlobServiceClientBuilder()
            .endpoint(endpointString)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

    return client;
}

添加以下 require 语句：

const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');

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

const accountName = "<storage-account-name>";

const blobServiceClient = new BlobServiceClient(
    `https://${accountName}.blob.core.windows.net`,
    new DefaultAzureCredential()
);

添加以下 import 语句：

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

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

def get_blob_service_client(self, account_name):
    account_url = f"https://{account_name}.blob.core.windows.net"
    credential = DefaultAzureCredential()

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

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

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

const containerName = "sample-container";
let containerClient = blobServiceClient.getContainerClient(containerName);

def get_blob_container_client(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)
    return container_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.windows.net/{containerName}"),
        new DefaultAzureCredential(),
        clientOptions);

    return client;
}

public BlobContainerClient getBlobContainerClient(
        String accountName,
        String containerName) {
    // Append the container name to the URI
    String endpointString = String.format("https://%s.blob.core.windows.net/%s",
            accountName, containerName);

    BlobContainerClient client = new BlobContainerClientBuilder()
            .endpoint(endpointString)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

    return client;
}

const accountName = "<storage-account-name>";
const containerName = "sample-container";

// Append the container name to the URI
const containerClient = new ContainerClient(
    `https://${accountName}.blob.core.windows.net/${containerName}`,
    new DefaultAzureCredential()

def get_blob_container_client(self, account_name, container_name):
    # Append the container name to the URI
    account_url = f"https://{account_name}.blob.core.windows.net/{container_name}"
    credential = DefaultAzureCredential()

    # Create the client object
    container_client = ContainerClient(account_url, credential=credential)

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

public BlobClient getBlobClient(
        BlobServiceClient blobServiceClient,
        String containerName,
        String blobName) {
    // Create a blob client using the service client object
    BlobClient client = blobServiceClient.getBlobContainerClient(containerName).getBlobClient(blobName);
    return client;
}

const containerName = "sample-container";
const blobName = "sample-blob";
let blobClient = blobServiceClient.getContainerClient(containerName).getBlobClient(blobName);

def get_blob_client(self, blob_service_client: BlobServiceClient, container_name, blob_name):
    # Create a blob client using the service client object
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    return blob_client

管理客户端对象

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

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

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

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

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

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

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

后续步骤

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

通过

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

关于客户端对象

授权客户端对象

创建客户端对象

创建 BlobServiceClient 对象

创建 BlobContainerClient 对象

创建 BlobClient 对象

管理客户端对象

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

后续步骤

反馈

其他资源