Panduan Cepat: Ekstensi Quarkus untuk Azure Blob Storage

Mulai menggunakan ekstensi Quarkus untuk Azure Blob Storage untuk mengelola blob dan kontainer. Dalam artikel ini, Anda mengikuti langkah-langkah untuk mencoba contoh kode untuk tugas dasar.

Dokumentasi referensi | Kode sumber perpustakaan | Paket (Maven) | Contoh

Prasyarat

Akun Azure dengan langganan aktif - buat akun secara gratis.
Azure CLI - Instal Azure CLI 2.62.0 atau lebih tinggi untuk menjalankan perintah Azure CLI.
Akun Azure Storage - buat akun penyimpanan.
Java Development Kit (JDK) versi 17 atau lebih tinggi.
Apache Maven.

Persiapan

Bagian ini memandu Anda menyiapkan proyek untuk bekerja dengan pengaya Quarkus untuk Azure Blob Storage.

Mengunduh aplikasi sampel

Aplikasi sampel ini adalah aplikasi Quarkus dasar yang digunakan dalam panduan cepat ini.

Gunakan git untuk mengunduh salinan aplikasi ke lingkungan pengembangan Anda, dan navigasikan ke storage-blob-quarkus direktori.

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

Mengautentikasi ke Azure dan mengotorisasi akses ke data blob

Permintaan aplikasi ke Azure Blob Storage harus diotorisasi. Menggunakan DefaultAzureCredential dan pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda, termasuk Blob Storage. Ekstensi Quarkus untuk layanan Azure mendukung pendekatan ini.

DefaultAzureCredential adalah implementasi rantai kredensial yang disediakan oleh pustaka klien Azure Identity untuk Java. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode mana yang akan digunakan saat runtime. Pendekatan ini memungkinkan aplikasi Anda untuk menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode khusus lingkungan.

Urutan dan lokasi di mana DefaultAzureCredential mencari kredensial dapat ditemukan di gambaran umum pustaka Azure Identity.

Dalam panduan memulai cepat ini, aplikasi Anda mengautentikasi dengan menggunakan kredensial sign-in Azure CLI Anda ketika dijalankan secara lokal. Setelah disebarkan ke Azure, aplikasi Anda kemudian dapat menggunakan identitas terkelola. Transisi antar lingkungan ini tidak memerlukan perubahan kode apa pun.

Menetapkan peran ke akun pengguna Microsoft Entra Anda

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data blob memiliki izin yang benar. Anda akan memerlukan hak akses Storage Blob Data Contributor untuk membaca dan menulis data blob. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Untuk informasi selengkapnya tentang peran Kontributor Data Blob Penyimpanan , lihat Kontributor Data Blob Penyimpanan. Untuk informasi selengkapnya tentang cakupan yang tersedia untuk penetapan peran, lihat Memahami cakupan untuk Azure RBAC.

Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna Anda yang dibatasi pada cakupan akun penyimpanan, untuk mengikuti Prinsip Hak Akses Minimum. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut akan menetapkan peran Kontributor Data Blob Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data blob di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.
Pada halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu sebelah kiri.
Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.
Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.
Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Blob Penyimpanan, lalu pilih hasil yang sesuai dan kemudian pilih Berikutnya.
Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.
Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.
Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure CLI, Anda harus terlebih dahulu mengambil id sumber daya menggunakan az storage account show perintah . Anda dapat memfilter properti output menggunakan parameter --query.

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

Salin output Id dari perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah az role di Azure CLI.

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

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure PowerShell, Anda harus terlebih dahulu mengambil ID sumber daya menggunakan Get-AzResource perintah .

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

Salin nilai Id dari output perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah New-AzRoleAssignment di PowerShell.

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

Anda dapat mengotorisasi akses ke data di akun penyimpanan Anda menggunakan langkah-langkah berikut:

Pastikan Anda terautentikasi dengan akun Microsoft Entra yang sama yang Anda gunakan untuk menetapkan peran di akun penyimpanan Anda. Contoh berikut menunjukkan cara mengautentikasi melalui Azure CLI:
```
az login
```
Pastikan Anda menyediakan titik akhir akun Azure Blob Storage Anda. Contoh berikut menunjukkan cara mengatur titik akhir menggunakan variabel QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT lingkungan melalui Azure CLI. Ganti <resource-group-name> dan <storage-account-name> dengan grup sumber daya dan nama akun penyimpanan Anda sebelum menjalankan perintah:
```
export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)
```

Nota

Saat disebarkan ke Azure, Anda perlu mengaktifkan identitas terkelola di aplikasi Anda, dan mengonfigurasi akun penyimpanan Anda untuk memungkinkan identitas terkelola tersebut tersambung. Untuk informasi selengkapnya tentang mengonfigurasi koneksi ini antara layanan Azure, lihat Mengautentikasi aplikasi Java yang dihosting Azure.

Jalankan sampel

Contoh kode melakukan tindakan berikut:

Menyuntikkan objek klien yang sudah diotorisasi untuk akses data melalui DefaultAzureCredential menggunakan ekstensi Quarkus untuk Azure Blob Storage.
Membuat kontainer di akun penyimpanan.
Mengunggah blob ke kontainer.
Mencantumkan blob dalam kontainer.
Mengunduh data blob ke sistem file lokal.
Menghapus sumber daya blob dan kontainer yang dibuat oleh aplikasi.
Menghapus sumber lokal dan file yang diunduh.

Jalankan aplikasi dalam mode JVM dengan menggunakan perintah berikut:

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

Output aplikasi mirip dengan contoh berikut (nilai UUID yang dihilangkan untuk keterbacaan):

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

Sebelum Memulai proses pembersihan, periksa folder data Anda untuk dua file tersebut. Anda dapat membandingkannya dan mengamati bahwa mereka identik.

Secara opsional, Anda dapat menjalankan sampel dalam mode asli. Untuk melakukan ini, Anda harus menginstal GraalVM, atau menggunakan gambar penyusun untuk membangun executable asli. Untuk informasi selengkapnya, lihat Membangun Native Executable. Panduan memulai cepat ini menggunakan Docker sebagai runtime kontainer untuk membangun eksekutabel Linux asli. Jika Anda belum menginstal Docker, Anda dapat mengunduhnya dari situs web Docker.

Jalankan perintah berikut untuk membangun dan menjalankan executable asli di lingkungan Linux:

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

Memahami kode sampel

Selanjutnya, Anda menelusuri kode sampel untuk memahami cara kerjanya.

Menyuntikkan objek klien dengan akses resmi

Bekerja dengan sumber daya Azure apa pun menggunakan SDK dimulai dengan membuat objek klien. Ekstensi Quarkus untuk Azure Blob Storage secara otomatis menyuntikkan objek klien dengan akses resmi menggunakan DefaultAzureCredential.

Agar berhasil menyuntikkan objek klien, pertama-tama Anda perlu menambahkan ekstensi quarkus-arc dan quarkus-azure-storage-blob ke file pom.xml Anda sebagai dependensi:

<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>

Diperlukan ekstensi quarkus-arc untuk menggunakan anotasi @Inject agar dapat menyuntikkan objek klien ke dalam kode aplikasi Anda. Dependensi quarkus-bom dan quarkus-azure-services-bom digunakan untuk mengelola versi platform Quarkus dan ekstensi Quarkus untuk layanan Azure.

Selanjutnya, Anda dapat menyuntikkan objek klien ke dalam kode aplikasi Anda menggunakan @Inject anotasi:

@Inject
BlobServiceClient blobServiceClient;

Itu saja yang perlu Anda kode untuk mendapatkan objek klien menggunakan ekstensi Quarkus untuk Azure Blob Storage. Untuk memastikan objek klien berwenang untuk mengakses akun penyimpanan Anda saat runtime, Anda perlu mengikuti langkah-langkah di bagian sebelumnya Mengautentikasi ke Azure dan mengotorisasi akses ke data blob sebelum menjalankan aplikasi.

Mengelola blob dan kontainer

Contoh kode berikut menunjukkan cara membuat kontainer, mengunggah blob, mencantumkan blob dalam kontainer, dan mengunduh blob.

Nota

Menulis ke sistem file lokal dianggap sebagai praktik buruk dalam aplikasi asli cloud. Namun, contohnya menggunakan sistem file lokal untuk mengilustrasikan penggunaan penyimpanan blob dengan cara yang mudah diverifikasi oleh pengguna. Saat Anda mengambil aplikasi untuk produksi, tinjau opsi penyimpanan Anda dan pilih opsi terbaik untuk kebutuhan Anda. Untuk informasi selengkapnya, lihat Meninjau opsi penyimpanan Anda.

// 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");

Operasi ini mirip dengan yang dijelaskan dalam Mulai Cepat: Pustaka klien Azure Blob Storage untuk Java SE. Untuk penjelasan kode yang lebih rinci, lihat bagian berikut di panduan cepat tersebut:

Pembersihan

Anda dapat memilih untuk mengikuti tautan di bagian Langkah berikutnya untuk menyebarkan aplikasi Quarkus ke Azure. Atau Anda dapat membersihkan akun penyimpanan dengan menghapus grup sumber daya. Untuk informasi selengkapnya, lihat Grup sumber daya Azure Resource Manager dan penghapusan sumber daya.

Langkah selanjutnya

Sampel Azure Storage dan panduan pengembang untuk Java Menyebarkan aplikasi Java dengan Quarkus pada kluster Azure Kubernetes Service Menyebarkan aplikasi Java dengan Quarkus di Azure Container Apps

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-09