データ リソースを操作するクライアント オブジェクトの作成および管理

Azure SDK は、さまざまな言語の Azure サービスを簡単に使用できるように構築されたライブラリのコレクションです。 SDK は、アプリケーションと Azure リソース間の操作をシンプルにするように設計されています。 SDK を使用した Azure リソースの操作は、クライアント インスタンスの作成から始まります。 この記事では、Azure Blob Storage でデータ リソースを操作するクライアント オブジェクトを作成する方法を示すとともに、アプリケーションでクライアントを管理する方法に関するベスト プラクティスを提供します。

クライアント オブジェクトについて

Azure Blob Storage クライアント ライブラリを使用すると、ストレージ サービス内の 3 種類のリソースを操作できます。

• ストレージ アカウント
• BLOB コンテナー
• BLOB

アプリケーションのニーズに応じて、これら 3 つのレベルのいずれかでクライアント オブジェクトを作成できます。

BLOB の場合、すべての種類での一般的な BLOB 操作をカバーする一般的な BLOB クライアントがあり、種類 (ブロック BLOB、追加 BLOB、ページ BLOB) ごとに特殊な BLOB クライアントがあります。

次の表では、言語ごとの異なるクライアント クラスが示されています。

Language	パッケージ	サービス クライアント クラス	コンテナー クライアント クラス	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

¹ Python の場合は、BlobClient に特殊化された BLOB 型のメソッドが含まれます。

それぞれのクライアントの種類は、単純なコンストラクター、またはさまざまな構成オプションを受け取るオーバーロードを呼び出すことによってインスタンス化できます。 Java の場合、それぞれのクライアントの種類には、構成とインスタンス化に役立つビルダー API を提供する個別のクラスがあります。 言語 SDK に応じて、これらのクライアント構成オプションはさまざまな方法でコンストラクターに渡されます。 詳細については、表のクラス リファレンスを参照してください。

クライアント オブジェクトの認可

アプリが BLOB リソースにアクセスし、それらを操作するには、クライアント オブジェクトが認可されている必要があります。 この記事のコード サンプルでは、DefaultAzureCredential を使用して、Microsoft Entra セキュリティ プリンシパルを介して Azure に対する認証を行います。 認証プロセスには、認可のためのアクセス トークンの取得が含まれます。 このアクセス トークンは、クライアントがインスタンス化されるときに資格情報として渡され、その資格情報はクライアントの有効期間全体にわたって保持されます。 トークンを要求する Microsoft Entra セキュリティ プリンシパルには、BLOB データへのアクセスを許可する適切な Azure RBAC ロールが割り当てられている必要があります。 詳細については、「BLOB データにアクセスするための Azure ロールを割り当てる」を参照してください。

次の認可メカニズムを使用して、クライアント オブジェクトへの適切なレベルのアクセスを付与できます。

• Microsoft Entra ID: 最適なセキュリティのために推奨されています
• Shared Access Signature (SAS): ユーザー委任 SAS トークンを使用する場合にサポートされ、最も安全です
• アカウント アクセス キー (共有キー): サポートされていますが、セキュリティが低下するおそれがあるため、推奨されていません

認可について詳しくは、「Azure Storage 内のデータへのアクセスを承認する」を参照してください。

クライアント オブジェクトの作成

SDK を使用して Azure リソースを操作するには、まずクライアント オブジェクトを作成します。 このセクションでは、ストレージ サービス内の 3 種類のリソース (ストレージ アカウント、コンテナー、BLOB) を操作するクライアント オブジェクトを作成する方法について説明します。

アプリケーションでクライアント オブジェクトを作成するときに、エンドポイントを参照する URI をクライアント コンストラクターに渡します。 この記事の例に示すように、エンドポイント文字列を手動で構築することも、Azure Storage 管理ライブラリを使用して実行時にエンドポイントのクエリを実行することもできます。 エンドポイントに対してクエリを実行する方法については、Blob Storage エンドポイントのクエリに関するページを参照してください。

BlobServiceClient オブジェクトを作成する

認可された BlobServiceClient オブジェクトを使用すると、アプリはストレージ アカウント レベルでリソースを操作できます。 BlobServiceClient には、ストレージ アカウント内のコンテナーの一覧表示、作成、および削除を行うメソッドとともに、アカウントのプロパティの取得および構成を行うメソッドが用意されています。 このクライアント オブジェクトは、ストレージ アカウント内のリソースを操作するための開始点です。

一般的なシナリオは、1 つのサービス クライアントをインスタンス化してから、必要に応じて、そのサービス クライアントからコンテナー クライアントと BLOB クライアントを作成することです。 特定のコンテナーまたは BLOB を操作するために、BlobServiceClient オブジェクトを使用して、コンテナー クライアントまたは BLOB クライアントを作成できます。 BlobServiceClient から作成されたクライアントは、クライアント オプションや資格情報など、クライアント構成を継承します。

次の例では、BlobServiceClient オブジェクトを作成する方法が示されています。

.NET

次の 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;
}

Java

次の 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;
}

JavaScript

次の 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()
);

Python

次の 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 オブジェクトからコンテナー クライアントを作成して、特定のコンテナー リソースを操作する方法が示されています。

.NET

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

Java

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

JavaScript

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

Python

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

作業範囲が狭く、1 つのコンテナーだけという場合は、BlobServiceClient を使用せずに BlobContainerClient オブジェクトを直接作成することもできます。 サービス クライアントの場合と同様に、コンテナー クライアントでもクライアント オプションを設定できます。

次の例では、BlobServiceClient を "使用せずに" コンテナー クライアントを直接作成する方法が示されています。

.NET

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

Java

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

JavaScript

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()

Python

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 クライアントを作成する方法が示されています。

.NET

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

Java

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

JavaScript

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

Python

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 クライアント管理のベスト プラクティスは、クライアントをシングルトンとして扱うことです。つまり、クラスには一度に 1 つのオブジェクトだけを含めることになります。 コンストラクター パラメーターまたはクライアント オプションの特定のセットに対して、クライアントのインスタンスを複数保持する必要はありません。 この概念は、次のような多くの方法で実装できます。

• 1 つのクライアント オブジェクトを作成し、アプリケーション全体でパラメーターとして渡します。 この方法は、この記事のコード例に示されています。
• フィールドにクライアント インスタンスを保存します。 C# フィールドの詳細については、「フィールド (C# プログラミング ガイド)」を参照してください。
• 任意の依存関係挿入コンテナーにクライアント オブジェクトをシングルトンとして登録します。 ASP.NET Core アプリでの依存関係の挿入の詳細については、「Azure SDK for .NET での依存関係の挿入」を参照してください。

この方法は、必要なクライアントごとにコンストラクターを呼び出すよりもはるかに効率的です。

クライアントの不変性とスレッド セーフ

Azure SDK クライアントは、作成後は変更できません。つまり、接続先のエンドポイント、認可に使用される資格情報、またはクライアント オプションとして渡されるその他の値を変更することはできません。 クライアントの不変性は、クライアントがアプリケーション全体で安全に共有および再利用されることを意味します。

アプリで同じ種類のクライアントに対して異なる構成または資格情報を使用する必要がある場合は、構成オプションのセットごとにクライアントをインスタンス化できます。

Azure SDK では、すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることが保証されます。 この設計により、クライアント インスタンスの共有および再利用が、たとえスレッド間であっても常に安全であることが保証されます。

次のステップ

Azure Storage クライアント ライブラリを使用してデータ リソースを操作する方法の詳細については、次の記事を参照してください。

• Azure Blob Storage および .NET の概要
• Azure Blob Storage と Java での作業開始
• Azure Blob Storage および JavaScript の概要
• Azure Blob Storage と Python で作業を開始する