Mulai cepat: Pustaka klien Azure Queue Storage untuk Java

  • Artikel

Mulai menggunakan pustaka klien Azure Queue Storage untuk Java. Azure Queue Storage adalah layanan untuk menyimpan pesan dalam jumlah besar untuk nantinya diambil dan diproses. Ikuti langkah-langkah berikut untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.

Dokumentasi | referensi API Paket kode | sumber pustaka (Maven)Sampel |

Gunakan pustaka klien Azure Queue Storage untuk Java untuk:

  • Membuat antrean
  • Tambahkan pesan ke antrean
  • Intip pesan dalam antrean
  • Perbarui pesan dalam antrean
  • Dapatkan panjang antrean
  • Terima pesan dari antrean
  • Hapus pesan dari antrean
  • Menghapus antrean

Prasyarat

Menyiapkan

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

Menginstal paket

Buka file pom.xml di editor teks Anda.

Tambahkan azure-sdk-bom untuk mengambil dependensi pada versi terbaru pustaka. Dalam cuplikan berikut, ganti {bom_version_to_target} tempat penampung 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>

Menyiapkan kerangka kerja aplikasi

Dari direktori proyek:

  1. Navigasi ke direktori /src/main/java/com/queues/quickstart
  2. Buka file App.java di editor Anda
  3. Hapus pernyataan System.out.println("Hello, world");
  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 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 keuntungan pengelolaan dan keamanan yang ditingkatkan melalui kunci akun untuk memungkinkan autentikasi tanpa kata sandi. Kedua opsi diperlihatkan 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 autentikasi yang harus digunakan saat runtime bahasa umum. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per 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, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. 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. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu 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.

A screenshot showing how to assign a role.

  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 dapat berisi jutaan pesan, hingga mencapai batas kapasitas total dari akun penyimpanan. Antrean umumnya digunakan untuk membuat backlog pekerjaan untuk 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 ditulis dengan huruf kecil semua. Untuk mendapatkan informasi tentang penamaan antrean, lihat Penamaan Antrean dan Metadata.
  • Pesan: Pesan, dalam format apa pun, dapat mencapai ukuran 64 KB. Pesan dapat tetap dalam antrean selama maksimal 7 hari. Untuk versi 29-07-2017 atau yang lebih baru, waktu untuk aktif maksimum dapat berupa angka positif apa pun, atau -1 yang menunjukkan bahwa pesan belum kedaluwarsa. Jika parameter ini dihilangkan, time-to-live default adalah tujuh hari.

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram of Queue storage architecture

Gunakan kelas Java berikut untuk berinteraksi dengan sumber daya ini:

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

Contoh kode

Contoh cuplikan kode ini menunjukkan 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 arahan impor untuk com.azure.identity dalam file App.java:

import com.azure.identity.*;

Tentukan nama untuk antrean dan buat instans QueueClient kelas, 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 diawali dan diikuti dengan karakter non-tanda hubung. Panjang nama harus antara 3 hingga 63 karakter. Untuk informasi tentang penamaan antrean, lihat Penamaan antrean dan metadata.

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

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();

Catatan

Pesan yang QueueClient dikirim menggunakan 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

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

Tambahkan kode ini ke akhir metode main:

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

// Create the queue
queueClient.create();

Tambahkan pesan ke antrean

Cuplikan kode berikut menambahkan pesan ke antrean dengan memanggil metode sendMessage. Kode tersebut juga menyimpan SendMessageResult yang dikembalikan dari panggilan sendMessage. Hasilnya digunakan untuk nantinya memperbarui isi pesan dalam program.

Tambahkan kode ini ke akhir metode main:

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

Intip pesan dalam antrean

Lihat sekilas pesan dalam antrean dengan memanggil metode peekMessages. Metode ini mengambil satu atau beberapa pesan dari depan antrean tanpa mengubah visibilitas pesan.

Tambahkan kode ini ke akhir metode main:

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()));

Perbarui pesan dalam antrean

Perbarui konten pesan dengan memanggil metode updateMessage. Metode ini dapat mengubah visibilitas batas waktu dan isi pesan. Isi pesan harus merupakan string berkode UTF-8 yang berukuran hingga 64 KB. Bersama dengan konten baru untuk pesan, berikan ID pesan dan tanda terima pop 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 mendapat estimasi jumlah pesan dalam antrean.

Metode getProperties mengembalikan beberapa nilai termasuk jumlah pesan yang saat ini dalam antrean. Jumlahnya hanya perkiraan karena pesan dapat ditambahkan atau dihapus setelah permintaan Anda. Metode getApproximateMessageCount mengembalikan nilai terakhir yang diambil oleh panggilan ke getProperties, tanpa memanggil Azure 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 metode receiveMessages. Kode contoh juga menghapus pesan dari antrean setelah diterima dan diproses. Dalam kasus ini, pemrosesan hanya menampilkan pesan di konsol.

Aplikasi berhenti sejenak untuk input pengguna dengan memanggil System.console().readLine(); sebelum memproses dan menghapus pesan. Pastikan 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 metode main:

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 metode Delete.

Tambahkan kode ini ke akhir metode main:

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, lalu mengambil dan menghapusnya, sebelum akhirnya menghapus antrean.

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

mvn compile

Kemudian, bangun paketnya.

mvn package

Gunakan perintah mvn berikut 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. Pastikan pesan berada dalam antrean.

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

Langkah berikutnya

Dalam mulai cepat ini, Anda belajar cara membuat antrean dan menambahkan pesan ke dalamnya menggunakan kode Java. Kemudian Anda belajar mengintip, mengambil, dan menghapus pesan. Terakhir, Anda belajar cara menghapus antrean pesan.

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

Azure untuk pengembang cloud Java