建立和管理與資料資源互動的用戶端物件

發行項
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 物件 (適用於 JavaScript 和 Python 的 ContainerClient)。 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

如果您的工作範圍縮小為單一容器，您可以選擇直接建立 BlobContainerClient 物件而不使用 BlobServiceClient。您仍可在容器用戶端上設定用戶端選項，就像在服務用戶端上一樣。

下列範例示範如何直接建立容器用戶端，而不需使用 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 物件

管理用戶端物件

用戶端不變性和執行緒安全性

下一步

意見反應

其他資源