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

  • 아티클

Go용 Azure Blob Storage 클라이언트 라이브러리를 시작하여 Blob 및 컨테이너를 관리합니다. 다음 단계에 따라 패키지를 설치하고 기본 작업에 대한 예제 코드를 사용해 보세요.

API 참조 설명서 | 라이브러리 소스 코드 | 패키지(pkg.go.dev)

필수 조건

설정

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

샘플 애플리케이션 다운로드

이 빠른 시작에서 사용되는 샘플 애플리케이션은 기본 Go 애플리케이션입니다.

git을 사용하여 개발 환경에 애플리케이션 복사본을 다운로드합니다.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart

이 명령은 로컬 git 폴더에 해당 리포지토리를 복제합니다. Blob Storage용 Go 샘플을 열려면 storage-quickstart.go이라는 파일을 찾습니다.

패키지 설치

스토리지 계정에서 Blob 및 컨테이너 리소스를 사용하려면 다음 명령을 사용하여 azblob 패키지를 설치합니다.

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Microsoft Entra ID(권장)로 인증하려면 다음 명령을 사용하여 azidentity 모듈을 설치합니다.

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

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

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

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

DefaultAzureCredential는 Go용 Azure ID 클라이언트 라이브러리에서 제공하는 자격 증명 체인 구현입니다. DefaultAzureCredential은 여러 인증 방법을 지원하고 런타임에 사용할 방법을 결정합니다. 이 방법을 사용하면 앱에서 환경별 코드를 구현하지 않고도 다양한 환경(로컬 및 프로덕션)에서 다양한 인증 방법을 사용할 수 있습니다.

DefaultAzureCredential에서 자격 증명을 찾는 순서와 위치에 대해 자세히 알아보려면 Azure Identity 라이브러리 개요에서 확인할 수 있습니다.

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

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분이 걸릴 수 있습니다. 코드를 처음 실행할 때 인증 오류가 발생하면 잠시 기다렸다가 다시 시도하세요.

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

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

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

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

    A screenshot showing how to assign a role.

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

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

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

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

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

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

  1. 스토리지 계정에서 역할을 할당한 것과 동일한 Microsoft Entra 계정을 사용하여 인증되는지 확인합니다. 다음 예제에서는 Azure CLI를 통해 인증하는 방법을 보여줍니다.

    az login

  2. Go 애플리케이션에서 DefaultAzureCredential를 사용하려면 다음 명령을 사용하여 azidentity 모듈을 설치합니다.

    go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

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

다양한 인증 방법에 대한 자세한 내용은 Go용 Azure SDK를 사용하여 Azure 인증을 확인하세요.

샘플 실행

코드 예제는 다음 작업을 수행합니다.

  • DefaultAzureCredential을 통해 데이터 액세스 권한이 부여된 클라이언트 개체 생성
  • 스토리지 계정에서 컨테이너 생성
  • 컨테이너에 Blob 업로드
  • 컨테이너의 Blob 나열
  • Blob 데이터를 버퍼에 다운로드
  • 앱에서 만든 Blob 및 컨테이너 리소스 삭제

샘플을 실행하기 전에 storage-quickstart.go 파일을 엽니다. <storage-account-name>를 Azure Storage 계정 이름으로 바꿉니다.

그리고 다음 명령을 실행하여 애플리케이션을 빌드합니다.

go run storage-quickstart.go

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

Azure Blob storage quick start sample
Creating a container named quickstart-sample-container
Uploading a blob named sample-blob
Listing the blobs in the container:
sample-blob
Blob contents:

Hello, world! This is a blob.

Press enter key to delete resources and exit the application.

Cleaning up.
Deleting the blob sample-blob
Deleting the container quickstart-sample-container

프롬프트에서 Enter 키를 누르면 샘플 프로그램이 앱에서 만든 Blob 및 컨테이너 리소스를 삭제합니다.

팁

Azure Storage Explorer와 같은 도구를 사용하여 Blob Storage의 파일을 볼 수도 있습니다. Azure Storage Explorer는 스토리지 계정 정보에 액세스할 수 있는 무료 플랫폼 간 도구입니다.

샘플 코드 이해

다음으로, 작동 방식을 이해하기 위해 샘플 코드를 따라 진행합니다.

액세스 권한 부여 및 클라이언트 개체 생성

SDK를 사용하여 Azure 리소스를 사용하는 것은 클라이언트 개체 만들기부터 시작합니다. 클라이언트 개체를 만들기 위해 코드 샘플은 다음 값이 있는 azblob.NewClient를 호출합니다.

  • serviceURL - 스토리지 계정의 URL
  • cred - azidentity 모듈을 통해 얻은 Microsoft Entra 자격 증명
  • options - 클라이언트 옵션; 기본값을 수락하려면 nil 전달

다음 코드 예제는 스토리지 계정에서 컨테이너 및 Blob 리소스와 상호 작용하는 클라이언트 개체를 만듭니다.

// TODO: replace <storage-account-name> with your actual storage account name
url := "https://<storage-account-name>.blob.core.windows.net/"
ctx := context.Background()

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

client, err := azblob.NewClient(url, credential, nil)
handleError(err)

컨테이너 만들기

코드 샘플은 스토리지 계정에 새 컨테이너 리소스를 만듭니다. 이름이 같은 컨테이너가 이미 있는 경우 ResourceExistsError가 발생합니다.

Important

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

다음 코드 예제에서는 스토리지 계정에 quickstart-sample-container라는 새 컨테이너를 만듭니다.

// Create the container
containerName := "quickstart-sample-container"
fmt.Printf("Creating a container named %s\n", containerName)
_, err = client.CreateContainer(ctx, containerName, nil)
handleError(err)

컨테이너에 Blob 업로드

코드 샘플은 일부 데이터가 있는 바이트 배열을 만들고 지정된 컨테이너의 새 Blob 리소스에 버퍼로 데이터를 업로드합니다.

다음 코드 예제에서는 UploadBuffer 메서드를 사용하여 지정된 컨테이너에 Blob 데이터를 업로드합니다.

data := []byte("\nHello, world! This is a blob.\n")
blobName := "sample-blob"

// Upload to data to blob storage
fmt.Printf("Uploading a blob named %s\n", blobName)
_, err = client.UploadBuffer(ctx, containerName, blobName, data, &azblob.UploadBufferOptions{})
handleError(err)

컨테이너의 Blob 나열

코드 샘플은 지정된 컨테이너의 Blob을 나열합니다. 이 예제에서는 지정된 표식에서 시작하는 Blob에 대한 호출기를 반환하는 NewListBlobsFlatPager를 사용합니다. 여기에서는 빈 표식을 사용하여 처음부터 열거를 시작하고 더 이상 결과가 없을 때까지 페이징을 계속합니다. 이 메서드는 사전순으로 Blob 이름을 반환합니다.

다음 코드 예제에서는 지정된 컨테이너에 있는 Blob을 나열합니다.

// List the blobs in the container
fmt.Println("Listing the blobs in the container:")

pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
	Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
})

for pager.More() {
	resp, err := pager.NextPage(context.TODO())
	handleError(err)

	for _, blob := range resp.Segment.BlobItems {
		fmt.Println(*blob.Name)
	}
}

Blob 다운로드

코드 샘플은 DownloadStream 메서드를 사용하여 Blob을 다운로드하고 데이터를 읽기 위한 재시도 판독기를 만듭니다. 읽는 동안 연결에 실패하면 다시 시도 판독기가 연결을 다시 설정하여 읽기를 계속하기 위한 다른 요청을 수행합니다. RetryReaderOptions 구조체를 사용하여 다시 시도 판독기 옵션을 지정할 수 있습니다.

다음 코드 예제는 Blob을 다운로드하고 콘솔에 콘텐츠를 씁니다.

// Download the blob
get, err := client.DownloadStream(ctx, containerName, blobName, nil)
handleError(err)

downloadedData := bytes.Buffer{}
retryReader := get.NewRetryReader(ctx, &azblob.RetryReaderOptions{})
_, err = downloadedData.ReadFrom(retryReader)
handleError(err)

err = retryReader.Close()
handleError(err)

// Print the contents of the blob we created
fmt.Println("Blob contents:")
fmt.Println(downloadedData.String())

리소스 정리

이 빠른 시작에서 업로드된 Blob이 더 이상 필요하지 않은 경우 DeleteBlob 메서드를 사용하여 개별 Blob을 삭제하거나 DeleteContainer 메서드를 사용하여 전체 컨테이너 및 해당 콘텐츠를 삭제할 수 있습니다.

// Delete the blob
fmt.Printf("Deleting the blob " + blobName + "\n")

_, err = client.DeleteBlob(ctx, containerName, blobName, nil)
handleError(err)

// Delete the container
fmt.Printf("Deleting the container " + containerName + "\n")
_, err = client.DeleteContainer(ctx, containerName, nil)
handleError(err)

다음 단계

이 빠른 시작에서는 Go를 사용하여 Blob을 업로드하고, 다운로드하고, 나열하는 방법을 알아보았습니다.

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

Go 샘플용 Azure Blob Storage 라이브러리