다음을 통해 공유

빠른 시작: Azure Blob Storage용 Quarkus 확장

Azure Blob Storage용 Quarkus 확장을 시작하여 Blob 및 컨테이너를 관리합니다. 이 문서에서는 단계에 따라 기본 작업에 대한 예제 코드를 사용해 봅니다.

참조 설명서 | 라이브러리 소스 코드 | 패키지(Maven) | 견본

필수 조건

설치

이 섹션에서는 Azure Blob Storage용 Quarkus 확장을 사용할 프로젝트를 준비하는 방법을 안내합니다.

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

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

git을 사용하여 개발 환경에 애플리케이션의 복사본을 다운로드하고 디렉터리로 이동합니다storage-blob-quarkus.

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

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

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

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

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

이 빠른 시작에서는 로컬로 실행할 때 앱이 Azure CLI 로그인 자격 증명을 사용하여 인증합니다. Azure에 배포된 후 앱은 관리 ID를 사용할 수 있습니다. 환경 간의 이러한 전환에는 코드 변경이 필요하지 않습니다.

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

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

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

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

중요합니다

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

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

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

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

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

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

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

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

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

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

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

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

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

    az login

  2. Azure Blob Storage 계정의 엔드포인트를 제공해야 합니다. 다음 예제에서는 Azure CLI를 통해 환경 변수 QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT 를 사용하여 엔드포인트를 설정하는 방법을 보여 줍니다. 명령을 실행하기 전에 <resource-group-name>와 <storage-account-name>을(를) 각각 리소스 그룹과 스토리지 계정 이름으로 바꾸십시오.

    export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)

비고

Azure에 배포된 경우 앱에서 관리 ID를 사용하도록 설정하고 해당 관리 ID가 연결할 수 있도록 스토리지 계정을 구성해야 합니다. Azure 서비스 간에 이 연결을 구성하는 방법에 대한 자세한 내용은 Azure 호스팅 Java 애플리케이션 인증을 참조하세요.

샘플 실행

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

  • Azure Blob Storage용 Quarkus 확장을 사용하여 데이터 액세스 DefaultAzureCredential 권한이 이미 부여된 클라이언트 개체를 삽입합니다.
  • 스토리지 계정에 컨테이너를 만듭니다.
  • 컨테이너에 블롭(Blob)을 업로드합니다.
  • 컨테이너 내의 Blob을 나열합니다.
  • Blob 데이터를 로컬 파일 시스템에 다운로드합니다.
  • 앱에서 만든 Blob 및 컨테이너 리소스를 삭제합니다.
  • 로컬 원본 및 다운로드한 파일을 삭제합니다.

다음 명령을 사용하여 JVM 모드에서 애플리케이션을 실행합니다.

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

앱의 출력은 다음 예제와 유사합니다(가독성을 위해 생략된 UUID 값).

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

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

필요에 따라 기본 모드에서 샘플을 실행할 수 있습니다. 이렇게 하려면 GraalVM을 설치하거나 작성기 이미지를 사용하여 네이티브 실행 파일을 빌드해야 합니다. 자세한 내용은 네이티브 실행 파일 빌드를 참조하세요. 이 빠른 시작에서는 Docker를 컨테이너 런타임으로 사용하여 Linux 네이티브 실행 파일을 빌드합니다. Docker를 설치하지 않은 경우 Docker 웹 사이트에서 다운로드할 수 있습니다.

다음 명령을 실행하여 Linux 환경에서 네이티브 실행 파일을 빌드하고 실행합니다.

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

샘플 코드 이해

다음으로, 샘플 코드의 작동 방식을 이해합니다.

권한 있는 액세스가 있는 클라이언트 객체 삽입

SDK를 사용하여 Azure 리소스를 사용하는 것은 클라이언트 개체 만들기부터 시작합니다. Azure Blob Storage용 Quarkus 확장은 권한 있는 액세스를 사용하여 DefaultAzureCredential클라이언트 개체를 자동으로 삽입합니다.

클라이언트 개체를 성공적으로 삽입하려면 먼저 확장 quarkus-arc 과 quarkus-azure-storage-blobpom.xml 파일을 종속성으로 추가해야 합니다.

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

quarkus-arc 주석을 사용하여 애플리케이션 코드에 @Inject 클라이언트 개체를 삽입하려면 확장이 필요합니다. quarkus-bom 및 quarkus-azure-services-bom 종속성은 Azure 서비스에 대한 Quarkus 플랫폼 및 Quarkus 확장의 버전을 관리하는 데 사용됩니다.

다음으로 주석을 사용하여 애플리케이션 코드에 클라이언트 개체를 삽입할 @Inject 수 있습니다.

@Inject
BlobServiceClient blobServiceClient;

Azure Blob Storage를 위한 Quarkus 확장을 사용하여 클라이언트 객체를 가져오는 데 필요한 모든 코드는 이것뿐입니다. 클라이언트 개체가 런타임에 스토리지 계정에 액세스할 수 있는 권한이 있는지 확인하려면 애플리케이션을 실행하기 전에 이전 섹션에서 Azure에 인증하고 Blob 데이터에 대한 액세스 권한을 부여 해야 합니다.

Blob 및 컨테이너 관리

다음 코드 예제에서는 컨테이너를 만들고, Blob을 업로드하고, 컨테이너에 Blob을 나열하고, Blob을 다운로드하는 방법을 보여 줍니다.

비고

로컬 파일 시스템에 쓰는 것은 클라우드 네이티브 애플리케이션에서 잘못된 사례로 간주됩니다. 그러나 이 예제에서는 로컬 파일 시스템을 사용하여 사용자가 쉽게 확인할 수 있는 방식으로 Blob Storage를 사용하는 방법을 보여 줍니다. 애플리케이션을 프로덕션으로 사용하는 경우 스토리지 옵션을 검토하고 요구 사항에 가장 적합한 옵션을 선택합니다. 자세한 내용은 스토리지 옵션 검토를 참조하세요.

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

이러한 작업은 빠른 시작: Java SE용 Azure Blob Storage 클라이언트 라이브러리에 설명된 작업과 유사합니다. 자세한 코드 설명은 해당 빠른 시작의 다음 섹션을 참조하세요.

정리

다음 단계 섹션의 링크를 따라 Quarkus 애플리케이션을 Azure에 배포하도록 선택할 수 있습니다. 또는 리소스 그룹을 삭제하여 스토리지 계정을 정리할 수 있습니다. 자세한 내용은 Azure Resource Manager 리소스 그룹 및 리소스 삭제를 참조하세요.

다음 단계

Java용 Azure Storage 샘플 및 개발자 가이드Azure Kubernetes Service 클러스터에 Quarkus를 사용하여 Java 애플리케이션 배포Azure Container Apps에 Quarkus를 사용하여 Java 애플리케이션 배포

  • Last updated on