Bagikan melalui

Panduan Mulai Cepat: Pustaka Klien Azure Queue Storage untuk Java

Mulai menggunakan pustaka klien Azure Queue Storage untuk Java. Azure Queue Storage adalah layanan untuk menyimpan sejumlah besar pesan untuk pengambilan dan pemrosesan nanti. Ikuti langkah-langkah berikut untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.

Dokumentasi | referensi APIKode | sumber pustakaPaket (Maven) | Sampel

Gunakan pustaka klien Azure Queue Storage untuk Java untuk:

  • Membuat antrean
  • Menambahkan pesan ke antrean
  • Mengintip pesan dalam antrean
  • Memperbarui pesan dalam antrean
  • Dapatkan panjang antrean
  • Menerima pesan dari antrean
  • Menghapus pesan dari antrean
  • Menghapus antrean

Prasyarat

Persiapan

Bagian ini memandu Anda menyiapkan proyek untuk bekerja dengan pustaka klien Azure Queue Storage untuk Java.

Membuat proyek

Buat aplikasi Java bernama queues-quickstart.

  1. Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan Maven untuk membuat aplikasi konsol baru dengan nama queues-quickstart. Ketik perintah berikut mvn untuk membuat "Halo, dunia!" Proyek Java.

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.queues.quickstart `
    --define artifactId=queues-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Output dari pembuatan proyek akan terlihat seperti ini:

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.394 s
[INFO] Finished at: 2019-12-03T09:58:35-08:00
[INFO] ------------------------------------------------------------------------

  3. Beralih ke direktori queues-quickstart yang baru dibuat.

    cd queues-quickstart

Instal paket-paket tersebut

Buka file pom.xml di editor teks Anda.

Tambahkan azure-sdk-bom untuk mengambil dependensi pada versi terbaru pustaka. Dalam cuplikan berikut, ganti placeholder {bom_version_to_target} dengan nomor versi. Menggunakan azure-sdk-bom membuat Anda tidak perlu menentukan versi setiap dependensi individu. Untuk mempelajari selengkapnya tentang BOM, lihat AZURE SDK BOM README.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Kemudian tambahkan elemen dependensi berikut ke grup dependensi. Dependensi azure-identity diperlukan untuk koneksi tanpa kata sandi ke layanan Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Atur kerangka aplikasi

Dari direktori proyek:

  1. Navigasi ke direktori /src/main/java/com/queues/quickstart
  2. Buka file App.java di editor Anda
  3. System.out.println("Hello, world"); Menghapus pernyataan
  4. Tambahkan direktif import

Berikut kodenya:

package com.queues.quickstart;

/**
 * Azure Queue Storage client library quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Mengautentikasi ke Azure

Permintaan aplikasi ke sebagian besar layanan Azure harus diotorisasi. Menggunakan kelas yang DefaultAzureCredential disediakan oleh pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda.

Anda juga dapat mengotorisasi permintaan ke layanan Azure menggunakan kata sandi, string koneksi, atau kredensial lainnya secara langsung. Namun, pendekatan ini harus digunakan dengan hati-hati. Pengembang harus rajin untuk tidak pernah mengekspos rahasia ini di lokasi yang tidak aman. Siapa pun yang mendapatkan akses ke kata sandi atau kunci rahasia dapat mengautentikasi. DefaultAzureCredential menawarkan manfaat manajemen dan keamanan yang ditingkatkan atas kunci akun untuk memungkinkan autentikasi tanpa kata sandi. Kedua opsi ditunjukkan dalam contoh berikut.

DefaultAzureCredential adalah kelas yang disediakan oleh pustaka klien Azure Identity untuk Java. Untuk mempelajari selengkapnya tentang DefaultAzureCredential, lihat gambaran umum DefaultAzureCredential. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode mana yang harus 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.

Misalnya, aplikasi Anda dapat mengautentikasi menggunakan info masuk Azure CLI Anda saat mengembangkan secara lokal, lalu menggunakan identitas terkelola setelah disebarkan ke Azure. Tidak diperlukan perubahan kode untuk transisi ini.

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data antrean memiliki izin yang benar. Anda memerlukan Kontributor Data Antrean Penyimpanan untuk membaca dan menulis data antrean. 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. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.

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 Antrean Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data antrean 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.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Pada halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu sebelah kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

Cuplikan layar yang menampilkan cara menetapkan peran.

  1. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Antrean Penyimpanan dan pilih hasil yang cocok lalu pilih Berikutnya.

  2. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  3. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  4. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Model objek

Azure Queue Storage adalah layanan untuk menyimpan pesan dalam jumlah besar. Pesan antrean dapat berukuran hingga 64 KB. Antrean mungkin berisi jutaan pesan, hingga batas kapasitas total akun penyimpanan. Antrean umumnya digunakan untuk membuat antrian pekerjaan tertunda yang diproses secara asinkron. Queue Storage menawarkan tiga jenis sumber daya:

  • Akun penyimpanan: Semua akses ke Azure Storage dilakukan melalui akun penyimpanan. Untuk informasi selengkapnya tentang akun penyimpanan, lihat Gambaran umum akun penyimpanan
  • Antrean: Antrean berisi sekumpulan pesan. Semua pesan harus dalam antrean. Perhatikan bahwa nama antrean harus semua huruf kecil. Untuk informasi tentang penamaan antrean, lihat Penamaan Antrean dan Metadata.
  • Pesan: Pesan, dalam format apa pun, hingga 64 KB. Pesan dapat tetap dalam antrean selama maksimal 7 hari. Untuk versi 2017-07-29 atau yang lebih baru, waktu hidup maksimum dapat berupa angka positif apa pun, atau -1 menunjukkan bahwa pesan tidak kedaluwarsa. Jika parameter ini dihilangkan, waktu hidup default adalah tujuh hari.

Diagram berikut menunjukkan hubungan antara sumber daya ini.

Diagram arsitektur penyimpanan Queue

Gunakan kelas Java berikut untuk berinteraksi dengan sumber daya ini:

  • QueueClientBuilder: Kelas QueueClientBuilder mengonfigurasi dan membuat instans QueueClient objek.
  • QueueServiceClient: QueueServiceClient memungkinkan Anda untuk mengelola semua antrean di akun penyimpanan Anda.
  • QueueClient: Kelas QueueClient memungkinkan Anda mengelola dan memanipulasi satu antrean dan pesan-pesannya.
  • QueueMessageItem: Kelas QueueMessageItem mewakili objek individual yang dikembalikan saat memanggil ReceiveMessages pada antrean.

Contoh kode

Contoh cuplikan kode ini menunjukkan kepada Anda cara melakukan tindakan berikut dengan pustaka klien Azure Queue Storage untuk Java:

Mengotorisasi akses dan membuat objek klien

Pastikan Anda diautentikasi dengan akun Microsoft Entra yang sama dengan yang Anda tetapkan perannya. Anda dapat mengautentikasi melalui Azure CLI, Visual Studio Code, atau Azure PowerShell.

Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:

az login

Setelah diautentikasi, Anda dapat membuat dan mengotorisasi QueueClient objek menggunakan DefaultAzureCredential untuk mengakses data antrean di akun penyimpanan. DefaultAzureCredential secara otomatis menemukan dan menggunakan akun yang Anda gunakan untuk masuk di langkah sebelumnya.

Untuk mengotorisasi menggunakan DefaultAzureCredential, pastikan Anda telah menambahkan dependensi azure-identity di pom.xml, seperti yang dijelaskan dalam Menginstal paket. Selain itu, pastikan untuk menambahkan direktif impor untuk com.azure.identity dalam file App.java:

import com.azure.identity.*;

Tentukan nama untuk antrian dan buat instans kelas QueueClient, dengan menggunakan DefaultAzureCredential untuk otorisasi. Kami menggunakan objek klien ini untuk membuat dan berinteraksi dengan sumber daya antrean di akun penyimpanan.

Penting

Nama antrean hanya boleh berisi huruf kecil, angka, dan tanda hubung, dan harus dimulai dengan huruf atau angka. Setiap tanda hubung harus didahului dan diikuti oleh karakter selain tanda hubung. Panjang nama juga harus antara 3 dan 63 karakter. Untuk informasi selengkapnya tentang penamaan antrean, lihat Penamaan antrean dan metadata.

Tambahkan kode ini di dalam metode main, dan pastikan untuk mengganti nilai <storage-account-name>.

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

Nota

Pesan yang dikirim menggunakan QueueClient kelas harus dalam format yang dapat disertakan dalam permintaan XML dengan pengodean UTF-8. Anda dapat secara opsional mengatur opsi QueueMessageEncoding untuk BASE64 menangani pesan yang tidak sesuai.

Membuat antrean

Dengan menggunakan objek QueueClient, panggil metode create untuk membuat antrian di akun penyimpanan Anda.

Tambahkan kode ini ke akhir main metode:

System.out.println("Creating queue: " + queueName);

// Create the queue
queueClient.create();

Menambahkan pesan ke antrean

Cuplikan kode berikut menambahkan pesan ke antrian dengan memanggil metode sendMessage. Ini juga menyimpan SendMessageResult yang dikembalikan oleh pemanggilan sendMessage. Hasilnya digunakan untuk memperbarui pesan nanti dalam program.

Tambahkan kode ini ke akhir main metode:

System.out.println("\nAdding messages to the queue...");

// Send several messages to the queue
queueClient.sendMessage("First message");
queueClient.sendMessage("Second message");

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

Mengintip pesan dalam antrean

Intip pesan dalam antrean dengan memanggil metode peekMessages. Metode ini mengambil satu atau beberapa pesan dari depan antrean tetapi tidak mengubah visibilitas pesan.

Tambahkan kode ini ke akhir main metode:

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

Memperbarui pesan dalam antrean

Perbarui konten pesan dengan memanggil updateMessage metode . Metode ini dapat mengubah batas waktu dan konten visibilitas pesan. Konten pesan harus berupa string yang dikodekan UTF-8 yang berukuran hingga 64 KB. Bersama dengan konten baru pada pesan, berikan ID pesan dan tanda terima pop dengan menggunakan SendMessageResult yang disimpan sebelumnya di dalam kode. ID pesan dan tanda terima pop mengidentifikasi pesan mana yang akan diperbarui.

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

Dapatkan panjang antrean

Anda bisa mendapatkan perkiraan jumlah pesan dalam antrean.

Metode getProperties mengembalikan beberapa nilai, termasuk jumlah pesan yang kini ada dalam antrean. Jumlahnya hanya perkiraan karena pesan dapat ditambahkan atau dihapus setelah permintaan Anda. Metode getApproximateMessageCount mengembalikan nilai terakhir yang diperoleh oleh panggilan ke getProperties, tanpa harus memanggil Queue Storage.

QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();

System.out.println(String.format("Queue length: %d", messageCount));

Menerima dan menghapus pesan dari antrean

Unduh pesan yang ditambahkan sebelumnya dengan memanggil receiveMessages metode . Kode contoh juga menghapus pesan dari antrean setelah diterima dan diproses. Dalam hal ini, pemrosesan hanya menampilkan pesan di konsol.

Aplikasi menjeda untuk input pengguna dengan memanggil System.console().readLine(); sebelum menerima dan menghapus pesan. Verifikasi di portal Microsoft Azure Anda bahwa sumber daya dibuat dengan benar, sebelum dihapus. Setiap pesan yang tidak dihapus secara eksplisit akhirnya menjadi terlihat dalam antrean lagi untuk kesempatan lain untuk memprosesnya.

Tambahkan kode ini ke akhir main metode:

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

Saat memanggil receiveMessages metode , Anda dapat secara opsional menentukan nilai untuk maxMessages, yang merupakan jumlah pesan yang akan diambil dari antrean. Defaultnya adalah 1 pesan dan maksimum adalah 32 pesan. Anda juga dapat menentukan nilai untuk visibilityTimeout, yang menyembunyikan pesan dari operasi lain untuk periode batas waktu. Defaultnya adalah 30 detik.

Menghapus antrean

Kode berikut membersihkan sumber daya yang dibuat aplikasi dengan menghapus antrean menggunakan Delete metode .

Tambahkan kode ini ke akhir main metode:

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("Done");

Menjalankan kode

Aplikasi ini membuat dan menambahkan tiga pesan ke antrean Azure. Kode mencantumkan pesan dalam antrean, kemudian mengambil dan menghapusnya, sebelum akhirnya menghapus antrean.

Di jendela konsol Anda, navigasikan ke direktori aplikasi Anda, lalu buat dan jalankan aplikasi.

mvn compile

Kemudian, buat paket tersebut.

mvn package

Gunakan perintah berikut mvn untuk menjalankan aplikasi.

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

Output aplikasi mirip dengan contoh berikut:

Azure Queue Storage client library - Java quickstart sample

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Press Enter key to receive messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
Done

Saat aplikasi berhenti sejenak sebelum menerima pesan, periksa akun penyimpanan Anda di portal Microsoft Azure. Verifikasi pesan berada dalam antrean.

Tekan tombol Enter untuk menerima dan menghapus pesan. Saat diminta, tekan tombol Enter lagi untuk menghapus antrean dan menyelesaikan demo.

Langkah selanjutnya

Dalam panduan cepat ini, Anda mempelajari cara membuat antrean dan menambahkan pesan ke antrean tersebut menggunakan kode Java. Kemudian Anda belajar melihat, mengambil, dan menghapus pesan. Terakhir, Anda mempelajari cara menghapus antrean pesan.

Untuk tutorial, sampel, panduan cepat, dan dokumentasi lainnya, kunjungi:

Azure untuk pengembang cloud Java

  • Last updated on