빠른 시작: .NET용 Azure Blob Storage 클라이언트 라이브러리 v12

.NET용 Azure Blob Storage 클라이언트 라이브러리 v12를 시작합니다. Azure Blob Storage는 클라우드를 위한 Microsoft의 개체 스토리지 솔루션입니다. 단계에 따라 패키지를 설치하고 기본 작업을 위한 예제 코드를 사용해 봅니다. Blob Storage는 대량의 비정형 데이터를 저장하도록 최적화되어 있습니다.

이 빠른 시작의 예제에서는 .NET용 Azure Blob Storage 클라이언트 라이브러리 v12를 사용하여 다음을 수행하는 방법을 보여줍니다.

추가 리소스:

필수 구성 요소

설치

이 섹션에서는 .NET용 Azure Blob Storage 클라이언트 라이브러리 v12를 사용하는 프로젝트를 준비합니다.

프로젝트 만들기

이후 단계를 위해 .NET CLI 또는 Visual Studio 2022를 사용하여 .NET 콘솔 앱을 만들어야 합니다.

  1. Visual Studio 위쪽에서 파일>새로 만들기>프로젝트..로 차례로 이동합니다.

  2. 대화 상자 창의 프로젝트 템플릿 검색 상자에서 콘솔 앱을 입력하고, 첫 번째 결과를 선택합니다. 대화 상자 아래쪽에서 다음을 선택합니다.

    Visual Studio를 사용하여 새 프로젝트를 만드는 방법을 보여 주는 스크린샷

  3. 프로젝트 이름에 대해 BlobQuickstartV12를 입력합니다. 나머지 필드는 기본값으로 그대로 두고, 다음을 선택합니다.

  4. 프레임워크에 대해 .NET 6.0이 선택되어 있는지 확인합니다. 그런 다음, 만들기를 선택합니다. Visual Studio 환경 내에서 새 프로젝트가 열립니다.

패키지 설치

Azure Blob Storage와 상호 작용하려면 .NET용 Azure Blob Storage 클라이언트 라이브러리를 설치합니다.

  1. 솔루션 탐색기에서 마우스 오른쪽 단추로 프로젝트의 종속성 노드를 클릭합니다. NuGet 패키지 관리를 선택합니다.

  2. 결과 창에서 Azure.Storage.Blob을 검색합니다. 적절한 결과를 선택하고, 설치를 선택합니다.

    Visual Studio를 사용하여 새 패키지를 추가하는 방법을 보여 주는 스크린샷

앱 코드 설정

이 연습에 필요한 using 문이 포함된 다음 예제와 일치하도록 Program.cs 파일의 시작 코드를 바꿉니다.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Azure에 앱 인증

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

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

DefaultAzureCredential은 .NET용 Azure ID 클라이언트 라이브러리에서 제공하는 클래스이며, DefaultAzureCredential 개요에서 자세히 알아볼 수 있습니다. DefaultAzureCredential은 여러 인증 방법을 지원하고 런타임에 사용해야 하는 방법을 결정합니다. 이 방법을 사용하면 앱에서 환경별 코드를 구현하지 않고도 다양한 환경(로컬 및 프로덕션)에서 다양한 인증 방법을 사용할 수 있습니다.

DefaultAzureCredential에서 자격 증명을 찾는 순서와 위치는 Azure ID 라이브러리 개요에서 확인할 수 있습니다.

자격 증명 흐름 다이어그램

예를 들어 로컬로 개발할 때 앱에서 Visual Studio 로그인 자격 증명을 사용하여 인증할 수 있습니다. 그러면 앱이 Azure에 배포되면 관리 ID를 사용할 수 있습니다. 이 전환에서는 코드를 변경할 필요가 없습니다.

Azure AD 사용자에게 역할 할당

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

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

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

중요

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

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

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

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

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

    역할을 할당하는 방법을 보여 주는 스크린샷

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

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

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

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

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

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

  1. Blob Storage 계정에서 역할을 할당한 것과 동일한 Azure AD 계정을 사용하여 인증되는지 확인합니다. Azure CLI, Visual Studio 또는 Azure PowerShell을 통해 인증할 수 있습니다.

    다음 명령을 사용하여 Azure CLI를 통해 Azure에 로그인합니다.

    az login
    
  2. DefaultAzureCredential을 사용하려면 Azure.Identity 패키지를 애플리케이션에 추가합니다.

    1. 솔루션 탐색기에서 마우스 오른쪽 단추로 프로젝트의 종속성 노드를 클릭합니다. NuGet 패키지 관리를 선택합니다.

    2. 결과 창에서 Azure.Identity를 검색합니다. 적절한 결과를 선택하고, 설치를 선택합니다.

      ID 패키지를 추가하는 방법을 보여 주는 스크린샷

  3. 다음 예제와 일치하도록 Program.cs 코드를 업데이트합니다. 코드가 개발 중에 로컬 워크스테이션에서 실행되면 Azure CLI 또는 Visual Studio와 같이 로그인한 우선 순위가 지정된 도구의 개발자 자격 증명을 사용하여 Azure에 인증합니다.

    using Azure.Storage.Blobs;
    using Azure.Storage.Blobs.Models;
    using System;
    using System.IO;
    using Azure.Identity;
    
    // TODO: Replace <storage-account-name> with your actual storage account name
    var blobServiceClient = new BlobServiceClient(
            new Uri("https://<storage-account-name>.blob.core.windows.net"),
            new DefaultAzureCredential());
    
  4. BlobServiceClient의 URI에서 스토리지 계정 이름을 업데이트해야 합니다. 스토리지 계정 이름은 Azure Portal의 개요 페이지에서 찾을 수 있습니다.

    스토리지 계정 이름을 찾는 방법을 보여 주는 스크린샷

    참고

    Azure에 배포하는 경우 이 동일한 코드를 사용하여 Azure에서 실행되는 애플리케이션에서 Azure Storage 요청에 대한 권한을 부여할 수 있습니다. 그러나 Azure의 앱에서 관리 ID를 사용하도록 설정해야 합니다. 그런 다음, 해당 관리 ID에서 연결할 수 있도록 Blob Storage 계정을 구성합니다. 이 연결을 Azure 서비스 간에 구성하는 방법에 대한 자세한 지침은 Azure 호스팅 앱에서 인증 자습서를 참조하세요.

개체 모델

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

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

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

Blob 스토리지 아키텍처 다이어그램

다음 .NET 클래스를 사용하여 이러한 리소스와 상호 작용합니다.

  • BlobServiceClient: BlobServiceClient 클래스를 사용하여 Azure Storage 리소스 및 blob 컨테이너를 조작할 수 있습니다.
  • BlobContainerClient: BlobContainerClient 클래스를 사용하여 Azure Storage 컨테이너 및 해당 blob을 조작할 수 있습니다.
  • BlobClient: BlobClient 클래스를 사용하여 Azure Storage blob을 조작할 수 있습니다.

코드 예제

다음 섹션의 샘플 코드 조각에서는 .NET용 Azure Blob Storage 클라이언트 라이브러리를 사용하여 기본 데이터 작업을 수행하는 방법을 보여 줍니다.

중요

설정 섹션에서 설명한 대로 올바른 NuGet 패키지를 설치하고 코드 샘플이 작동하는 데 필요한 using 문을 추가했는지 확인하세요.

  • Azure.Identity(암호 없는 방법을 사용하는 경우)
  • Azure.Storage.Blobs

컨테이너 만들기

새 컨테이너의 이름을 결정합니다. 아래 코드는 컨테이너 이름에 GUID 값을 추가하여 고유하게 만듭니다.

중요

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

blobServiceClient에서 CreateBlobContainerAsync 메서드를 호출하여 컨테이너를 스토리지 계정에 만들 수 있습니다.

다음 코드를 Program.cs 클래스의 끝에 추가합니다.

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

컨테이너에 Blob 업로드

다음 코드를 Program.cs 클래스의 끝에 추가합니다.

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

이 코드 조각에서는 다음 단계를 완료합니다.

  1. 로컬 data 디렉터리에 텍스트 파일을 만듭니다.
  2. 컨테이너 만들기 섹션에서 컨테이너에 대해 GetBlobClient 메서드를 호출하여 BlobClient 개체에 대한 참조를 가져옵니다.
  3. UploadAsync 메서드를 호출하여 로컬 텍스트 파일을 Blob에 업로드합니다. 이 메서드는 Blob이 존재하지 않는 경우 Blob을 생성하고, Blob이 존재하는 경우 덮어씁니다.

컨테이너의 Blob 나열

GetBlobsAsync 메서드를 호출하여 컨테이너의 blob을 나열합니다. 이 경우 하나의 Blob만 컨테이너에 추가되었으므로 나열된 작업은 하나의 해당 Blob만 반환합니다.

다음 코드를 Program.cs 클래스의 끝에 추가합니다.

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Blob 다운로드

DownloadToAsync 메서드를 호출하여 이전에 만든 blob을 다운로드합니다. 예제 코드는 로컬 파일 시스템에서 두 파일을 볼 수 있도록 파일 이름에 "DOWNLOADED" 접미사를 추가합니다.

다음 코드를 Program.cs 클래스의 끝에 추가합니다.

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

컨테이너 삭제

다음 코드는 DeleteAsync를 사용하여 전체 컨테이너를 삭제하여 앱이 만든 리소스를 정리합니다. 또한 앱에서 만든 로컬 파일도 삭제합니다.

앱은 blob, 컨테이너 및 로컬 파일을 삭제하기 전에 Console.ReadLine을 호출하여 사용자 입력을 일시 중지합니다. 리소스를 삭제하기 전에 실제로 올바르게 만들어졌는지 확인하는 것이 좋습니다.

다음 코드를 Program.cs 클래스의 끝에 추가합니다.

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

완성된 코드

이러한 단계가 완료되면 Program.cs 파일의 코드가 이제 다음과 비슷합니다.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

코드 실행

이 앱은 로컬 data 폴더에 테스트 파일을 만들고 Blob 스토리지에 업로드합니다. 그런 다음, 컨테이너에 Blob을 나열하고 이전 파일과 새 파일을 비교할 수 있도록 새 이름으로 해당 파일을 다운로드합니다.

Visual Studio를 사용하는 경우 F5 키를 눌러 코드를 빌드하고 실행하고, 콘솔 앱과 상호 작용합니다. .NET CLI를 사용하는 경우 애플리케이션 디렉터리로 이동한 다음, 애플리케이션을 빌드하고 실행합니다.

dotnet build
dotnet run

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

Azure Blob Storage v12 - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

정리 프로세스를 시작하기 전에 data 폴더에서 두 파일을 확인합니다. 이 파일을 열어 동일한지 확인할 수 있습니다.

파일을 확인한 후에 Enter 키를 눌러 테스트 파일을 삭제하고 데모를 완료합니다.

다음 단계

이 빠른 시작에서는 .NET을 사용하여 Blob을 업로드, 다운로드 및 나열하는 방법을 배웠습니다.

Blob 스토리지 샘플 앱을 보려면 다음을 계속 진행합니다.