빠른 시작: C++용 Azure Blob Storage 클라이언트 라이브러리

C++용 Azure Blob Storage 클라이언트 라이브러리를 시작합니다. Azure Blob Storage는 클라우드를 위한 Microsoft의 개체 스토리지 솔루션입니다. 다음 단계에 따라 패키지를 설치하고 기본 작업에 대한 예제 코드를 사용해 보세요.

| API 참조 설명서 | 라이브러리 소스 코드 | 샘플 |

필수 조건

• Azure 구독 - 체험 구독 만들기
• Azure Storage 계정 - 스토리지 계정 만들기
• C++ 컴파일러
• CMake
• vcpkg - C 및 C++ 패키지 관리자

설정

이 섹션에서는 C++용 Azure Blob Storage 클라이언트 라이브러리를 사용하는 프로젝트를 준비합니다. C++용 Azure SDK를 획득하는 가장 쉬운 방법은 vcpkg 패키지 관리자를 사용하는 것입니다.

패키지 설치

vcpkg install 명령을 사용하여 C++ 및 필요한 종속성에 대한 Azure Blob Storage 라이브러리를 설치합니다.

vcpkg.exe install azure-storage-blobs-cpp

Azure 서비스에 대한 암호 없는 연결에는 Azure ID 라이브러리가 필요합니다.

vcpkg.exe install azure-identity-cpp

프로젝트 설정 및 C++용 Azure SDK 작업에 대한 자세한 내용은 C++용 Azure SDK 추가 정보를 참조하세요.

프로젝트 만들기

Visual Studio에서 BlobQuickstart라는 Windows용 C++ 콘솔 애플리케이션을 새로 만듭니다.

개체 모델

Azure Blob Storage는 대량의 비정형 데이터를 저장하는 데 최적화되어 있습니다. 비정형 데이터는 텍스트 또는 이진 데이터와 같은 특정 데이터 모델이나 정의를 따르지 않는 데이터입니다. Blob Storage에서 제공하는 세 가지 종류의 리소스는 다음과 같습니다.

• 스토리지 계정
• 스토리지 계정의 컨테이너
• 컨테이너의 blob

다음 다이어그램에서는 리소스 간의 관계를 보여줍니다.

다음 C++ 클래스를 사용하여 다음 리소스와 상호 작용합니다.

• BlobServiceClient: BlobServiceClient 클래스를 사용하면 Azure Storage 리소스 및 Blob 컨테이너를 조작할 수 있습니다.
• BlobContainerClient: BlobContainerClient 클래스를 사용하면 Azure Storage 컨테이너 및 해당 Blob을 조작할 수 있습니다.
• BlobClient: BlobClient 클래스를 사용하면 Azure Storage Blob을 조작할 수 있습니다. 모든 특수 Blob 클래스의 기본 클래스입니다.
• BlockBlobClient: BlockBlobClient 클래스를 사용하여 Azure Storage 블록 Blob을 조작할 수 있습니다.

코드 예제

이러한 코드 조각 예제에서는 C++용 Azure Blob Storage 클라이언트 라이브러리를 사용하여 다음 작업을 수행하는 방법을 보여 줍니다.

• 포함 파일 추가
• Azure에 인증하고 Blob 데이터에 대한 액세스 권한 부여
• 컨테이너 만들기
• 컨테이너에 Blob 업로드
• 컨테이너의 Blob 나열
• Blob 다운로드
• 컨테이너 삭제

포함 파일 추가

프로젝트 디렉터리에서 다음을 수행합니다.

1. Visual Studio에서 BlobQuickstart.sln 솔루션 파일 열기
2. Visual Studio 내에서 BlobQuickstart.cpp 원본 파일 열기
3. main 내에서 자동 생성된 코드를 모두 제거합니다.
4. #include 및 using namespace 문 추가

#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

Azure에 인증하고 Blob 데이터에 대한 액세스 권한 부여

Azure Blob Storage에 대한 애플리케이션 요청에 대한 권한을 부여해야 합니다. Azure.Identity 클라이언트 라이브러리에서 제공하는 DefaultAzureCredential 클래스를 사용하는 것은 Blob Storage를 포함하여 코드에서 Azure 서비스에 대한 암호 없는 연결을 구현하는 데 권장되는 방법입니다.

또한 계정 액세스 키를 사용하여 Azure Blob Storage 요청에 대한 권한을 부여할 수 있습니다. 그러나 이 방법은 신중하게 사용해야 합니다. 개발자는 액세스 키를 안전하지 않은 위치에 노출하지 않도록 끊임없이 노력해야 합니다. 액세스 키가 있는 사람은 누구나 스토리지 계정에 대한 요청에 권한을 부여할 수 있으며 모든 데이터에 효과적으로 액세스할 수 있습니다. DefaultAzureCredential은 암호 없는 인증을 허용하기 위해 계정 키보다 향상된 관리 및 보안 이점을 제공합니다. 두 옵션 모두에 대해 다음 예에서 설명하고 있습니다.

암호 없음(권장)

Azure ID 라이브러리는 Azure SDK 전체에서 Microsoft Entra 토큰 인증을 지원합니다. 즉, 이 라이브러리는 Microsoft Entra 토큰 인증을 지원하는 Azure SDK 클라이언트를 생성하는 데 사용할 수 있는 TokenCredential 구현 집합을 제공합니다. DefaultAzureCredential은 여러 인증 방법을 지원하고 런타임에 사용해야 하는 방법을 결정합니다.

Microsoft Entra 사용자 계정에 역할 할당

로컬로 개발하는 경우 Blob 데이터에 액세스하는 사용자 계정에 올바른 권한이 있는지 확인합니다. Blob 데이터를 읽고 쓰려면 Storage Blob 데이터 참가자가 필요합니다. 이 역할을 자신에게 할당하려면 사용자 액세스 관리자 역할 또는 Microsoft.Authorization/roleAssignments/write 작업을 포함하는 다른 역할이 필요합니다. Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 사용자에게 Azure RBAC 역할을 할당할 수 있습니다. 범위 개요 페이지에서 역할 할당에 사용할 수 있는 범위에 대해 자세히 알아볼 수 있습니다.

이 시나리오에서는 최소 권한 원칙을 따르기 위해 범위가 스토리지 계정으로 지정된 사용자 계정에 권한을 할당합니다. 이 방법은 사용자에게 필요한 최소 권한만 부여하고 더 안전한 프로덕션 환경을 만듭니다.

다음 예제에서는 스토리지 계정의 Blob 데이터에 대한 읽기 및 쓰기 액세스를 모두 제공하는 Storage Blob 데이터 참가자 역할을 사용자 계정에 할당합니다.

Important

대부분의 경우 Azure에서 역할 할당이 전파되는 데 1~2분이 걸리지만 드문 경우이지만 최대 8분이 걸릴 수 있습니다. 코드를 처음 실행할 때 인증 오류가 발생하면 잠시 기다렸다가 다시 시도하세요.

Azure Portal

1. Azure Portal에서 기본 검색 창 또는 왼쪽 탐색 영역을 사용하여 스토리지 계정을 찾습니다.

2. 스토리지 계정 개요 페이지의 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다.

3. 액세스 제어(IAM) 페이지에서 역할 할당 탭을 선택합니다.

4. 위쪽 메뉴에서 + 추가를 선택한 다음, 드롭다운 메뉴에서 역할 할당 추가를 선택합니다.

   

5. 검색 상자를 사용하여 결과를 원하는 역할로 필터링합니다. 이 예에서는 Storage Blob 데이터 기여자를 검색하고, 일치하는 결과를 선택하고, 다음을 선택합니다.

6. 다음에 대한 액세스 할당 아래에서 사용자, 그룹 또는 서비스 주체를 선택한 다음, + 멤버 선택을 선택합니다.

7. 대화 상자에서 Microsoft Entra 사용자 이름(일반적으로 user@domain 이메일 주소)을 검색한 다음, 대화 상자 하단에서 선택을 선택합니다.

8. 검토 + 할당을 선택하여 최종 페이지로 이동한 다음, 검토 + 할당을 다시 선택하여 프로세스를 완료합니다.

Azure CLI

Azure CLI를 사용하여 리소스 수준에서 역할을 할당하려면 먼저 az storage account show 명령을 사용하여 리소스 ID를 검색해야 합니다. --query 매개 변수를 사용하여 출력 속성을 필터링할 수 있습니다.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

이전 명령의 Id 출력을 복사합니다. 그런 다음, Azure CLI의 az role 명령을 사용하여 역할을 할당할 수 있습니다.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Azure PowerShell을 사용하여 리소스 수준에서 역할을 할당하려면 먼저 Get-AzResource 명령을 사용하여 리소스 ID를 검색해야 합니다.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

이전 명령 출력에서 Id 값을 복사합니다. 그런 다음, PowerShell에서 New-AzRoleAssignment 명령을 사용하여 역할을 할당할 수 있습니다.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

DefaultAzureCredential을 사용하여 로그인하고 앱 코드를 Azure에 연결

다음 단계를 사용하여 스토리지 계정의 데이터에 대한 액세스 권한을 부여할 수 있습니다.

1. 스토리지 계정에서 역할을 할당한 것과 동일한 Microsoft Entra 계정을 사용하여 인증되는지 확인합니다. Azure CLI를 통해 인증할 수 있습니다. 다음 명령을 사용하여 Azure CLI를 통해 Azure에 로그인합니다.

   az login
   

2. DefaultAzureCredential를 사용하려면 azure-identity-cpp 패키지가 설치되어 있고 다음 #include이 추가되었는지 확인합니다.

   #include <azure/identity/default_azure_credential.hpp>
   

3. main()의 끝에 다음 코드를 추가합니다. 로컬 워크스테이션에서 코드가 실행되면 DefaultAzureCredential은 Azure CLI에 대한 개발자 자격 증명을 사용하여 Azure에 인증합니다.

   // Initialize an instance of DefaultAzureCredential
    auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
   
    auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
    BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
   

4. BlobServiceClient 개체의 URI에서 스토리지 계정 이름을 업데이트해야 합니다. 스토리지 계정 이름은 Azure Portal의 개요 페이지에서 찾을 수 있습니다.

   

   참고 항목

   프로덕션 환경에서 C++ SDK를 사용하는 경우 애플리케이션에서 사용할 자격 증명만 사용하도록 설정하는 것이 좋습니다. DefaultAzureCredential를 사용하는 대신 특정 자격 증명 형식을 사용하거나 지원되는 자격 증명과 함께 ChainedTokenCredential를 사용하여 권한을 부여해야 합니다.

연결 문자열

연결 문자열에는 스토리지 계정 액세스 키가 포함되며, 이를 사용하여 요청에 대한 권한을 부여합니다. 키를 안전하지 않은 위치에 노출하지 않도록 항상 주의해야 합니다.

참고 항목

스토리지 계정 액세스 키를 사용하여 데이터 액세스 권한을 부여하려면 Microsoft.Storage/storageAccounts/listkeys/action Azure RBAC 작업에 대한 권한이 필요합니다. 이 작업에 대한 권한이 있는 최소 권한의 기본 제공 역할은 읽기 권한자 및 데이터 액세스이지만 이 작업을 포함하는 모든 역할이 작동합니다.

Azure Portal

1. Azure Portal에 로그인합니다.

2. 스토리지 계정을 찾습니다.

3. 스토리지 계정 메뉴 창의 보안 + 네트워킹에서 액세스 키를 선택합니다. 여기에서 계정 액세스 키 및 각 키의 전체 연결 문자열을 볼 수 있습니다.

4. 액세스 키 창에서 키 표시를 선택합니다.

5. key1 섹션에서 연결 문자열 값을 찾습니다. 클립보드에 복사 아이콘을 선택하여 연결 문자열을 복사합니다. 다음 단계에서 연결 문자열 값을 환경 변수에 추가합니다.

   

Azure CLI

az storage account show-connection-string 명령을 사용하여 스토리지 계정에 대한 연결 문자열을 볼 수 있습니다.

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

Get-AzStorageAccount 및 Get-AzStorageAccountKey 명령을 사용하여 PowerShell에서 연결 문자열을 어셈블할 수 있습니다.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

스토리지 연결 문자열 구성

연결 문자열을 복사한 후 애플리케이션을 실행 중인 로컬 컴퓨터의 새 환경 변수에 씁니다. 환경 변수를 설정하려면 콘솔 창을 열고 사용 중인 운영 체제의 지침을 따릅니다. <yourconnectionstring>을 실제 연결 문자열로 바꿉니다.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Windows에서 환경 변수가 추가되면 명령 창의 새 인스턴스를 시작해야 합니다.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

다음 코드 예제에서는 이전에 만든 환경 변수에서 스토리지 계정에 대한 연결 문자열을 검색하고 연결 문자열을 사용하여 서비스 클라이언트 개체를 생성합니다.

다음 코드를 main()의 끝에 추가합니다.

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

Important

계정 액세스 키는 신중하게 사용해야 합니다. 계정 액세스 키가 손실하거나 실수로 안전하지 않은 위치에 배치되는 경우 서비스가 취약해질 수 있습니다. 액세스 키가 있는 사람은 누구나 스토리지 계정에 대한 요청에 권한을 부여할 수 있으며 모든 데이터에 효과적으로 액세스할 수 있습니다. DefaultAzureCredential은 향상된 보안 기능과 이점을 제공하며 Azure 서비스에 대한 권한 부여를 관리하는 데 권장되는 방법입니다.

컨테이너 만들기

새 컨테이너의 이름을 결정합니다. 그런 다음, BlobContainerClient의 인스턴스를 만들고 컨테이너를 만듭니다.

Important

컨테이너 이름은 소문자여야 합니다. 컨테이너 및 Blob 이름 지정에 대한 자세한 내용은 컨테이너, Blob, 메타데이터 이름 지정 및 참조를 참조하세요.

다음 코드를 main()의 끝에 추가합니다.

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

컨테이너에 Blob 업로드

다음 코드 조각을 실행합니다.

1. “Hello Azure!”가 포함된 문자열 선언
2. 컨테이너 만들기 섹션에서 컨테이너에 대한 GetBlockBlobClient를 호출하여 BlockBlobClient 개체에 대한 참조를 가져옵니다.
3. UploadFrom 함수를 호출하여 문자열을 Blob에 업로드합니다. Blob이 아직 없는 경우 이 함수에서 Blob을 만들고, 있는 경우 이를 업데이트합니다.

다음 코드를 main()의 끝에 추가합니다.

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

컨테이너의 Blob 나열

ListBlobs 함수를 호출하여 컨테이너의 blob을 나열합니다. 하나의 Blob만 컨테이너에 추가되었으므로 작업에서 해당 Blob만 반환합니다.

다음 코드를 main()의 끝에 추가합니다.

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

Blob 다운로드

업로드된 Blob의 속성을 가져옵니다. 그런 다음, 업로드된 Blob의 속성을 사용하여 새 std::vector<uint8_t> 개체를 선언하고 크기를 조정합니다. BlobClient 기본 클래스에서 DownloadTo 함수를 호출하여 이전에 만든 Blob을 새 std::vector<uint8_t> 개체로 다운로드합니다. 마지막으로 다운로드한 Blob 데이터를 표시합니다.

다음 코드를 main()의 끝에 추가합니다.

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

Blob 삭제

다음 코드에서는 BlobClient.Delete 함수를 호출하여 Azure Blob Storage 컨테이너에서 Blob을 삭제합니다.

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

컨테이너 삭제

다음 코드에서는 BlobContainerClient.Delete를 통해 전체 컨테이너를 삭제하여 앱에서 만든 리소스를 정리합니다.

다음 코드를 main()의 끝에 추가합니다.

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

코드 실행

이 앱은 컨테이너를 만들고, 텍스트 파일을 Azure Blob Storage에 업로드합니다. 그런 다음, 예제에서 컨테이너의 Blob을 나열하고, 파일을 다운로드하고, 파일 내용을 표시합니다. 마지막으로 앱에서 Blob 및 컨테이너를 삭제합니다.

앱의 출력은 다음 예제 출력과 유사합니다.

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

다음 단계

이 빠른 시작에서는 C++를 사용하여 Blob을 업로드하고, 다운로드하고, 나열하는 방법을 알아보았습니다. 또한 Azure Blob Storage 컨테이너를 만들고 삭제하는 방법도 알아보았습니다.

Blob Storage 샘플을 보려면 다음으로 계속 진행하세요.

C++용 Azure Blob Storage 클라이언트 라이브러리