데이터 리소스와 상호 작용하는 클라이언트 개체 만들기 및 관리

아티클
08/05/2024

Azure SDK는 다양한 언어의 Azure 서비스를 더 쉽게 사용할 수 있도록 빌드된 라이브러리의 컬렉션입니다. SDK는 애플리케이션과 Azure 리소스 간의 상호 작용을 간소화하도록 설계되었습니다. SDK를 사용하여 Azure 리소스를 사용하는 것은 클라이언트 인스턴스 만들기부터 시작합니다. 이 문서에서는 Azure Blob Storage의 데이터 리소스와 상호 작용하는 클라이언트 개체를 만드는 방법을 보여 주고, 애플리케이션에서 클라이언트를 관리하는 방법에 대한 모범 사례를 제공합니다.

클라이언트 개체 정보

Azure Blob Storage 클라이언트 라이브러리를 사용하면 스토리지 서비스의 세 가지 유형의 리소스와 상호 작용할 수 있습니다.

스토리지 계정
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 보안 주체에는 Blob 데이터에 대한 액세스 권한을 부여하는 적절한 Azure RBAC 역할이 할당되어야 합니다. 자세한 내용은 Blob 데이터에 액세스하기 위한 Azure 역할 할당을 참조하세요.

다음 권한 부여 메커니즘을 사용하여 클라이언트 개체에 대해 적절한 수준의 액세스 권한을 부여할 수 있습니다.

Microsoft Entra ID: 최적의 보안을 위해 권장됨
SAS(공유 액세스 서명): 지원되며, 사용자 위임 SAS 토큰을 사용할 때 가장 안전합니다.
계정 액세스 키(공유 키): 지원되지만 덜 안전할 수 있으므로 권장되지 않습니다.

권한 부여에 대한 자세한 내용은 Azure Storage의 데이터에 대한 액세스 권한 부여를 참조하세요.

클라이언트 개체 만들기

SDK를 사용하여 Azure 리소스를 사용하는 것은 클라이언트 개체 만들기부터 시작합니다. 이 섹션에서는 스토리지 서비스의 세 가지 리소스 유형인 스토리지 계정, 컨테이너 및 Blob과 상호 작용하는 클라이언트 개체를 만드는 방법을 알아봅니다.

애플리케이션이 클라이언트 개체를 만들 때 엔드포인트를 참조하는 URI를 클라이언트 생성자에 전달합니다. 이 문서의 예제와 같이 엔드포인트 문자열을 수동으로 구성하거나 Azure Storage 관리 라이브러리를 사용하여 런타임에 엔드포인트를 쿼리할 수 있습니다. 엔드포인트를 쿼리하는 방법을 알아보려면 Blob Storage 엔드포인트 쿼리를 참조하세요.

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

작업 범위가 단일 컨테이너로 좁혀진 경우 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 Storage 클라이언트 라이브러리를 사용하여 데이터 리소스를 사용하는 방법에 대한 자세한 내용은 다음 문서를 참조하세요.

다음을 통해 공유

데이터 리소스와 상호 작용하는 클라이언트 개체 만들기 및 관리

클라이언트 개체 정보

클라이언트 개체에 권한 부여

클라이언트 개체 만들기

BlobServiceClient 개체 만들기

BlobContainerClient 개체 만들기

BlobClient 개체 만들기

클라이언트 개체 관리

클라이언트 불변성 및 스레드 보안

다음 단계

피드백

추가 리소스