Cara menggunakan Queue Storage dari C++P

• .NET
• Java
• Python
• Node.js
• C++
• Ruby
• PHP

Tip

Coba Explorer Microsoft Azure Storage

Explorer Microsoft Azure Storage adalah aplikasi mandiri gratis dari Microsoft yang memungkinkan Anda bekerja secara visual dengan data Azure Storage di Windows, macOS, dan Linux.

Gambaran Umum

Panduan ini memperlihatkan kepada Anda cara melakukan skenario umum menggunakan layanan Azure Queue Storage. Sampel ditulis dalam C++ dan menggunakan pustaka klien Azure Storage untuk C++. Skenario yang disertakan termasuk menyisipkan, mengintip, mendapatkan, dan menghapus pesan antrean, serta membuat dan menghapus antrean.

Catatan

Panduan ini menargetkan pustaka klien Azure Storage untuk C++ v1.0.0 ke atas. Versi yang direkomendasikan adalah pustaka klien Azure Storage v2.2.0, yang disediakan melalui NuGet atau GitHub.

Apa itu penyimpanan Queue?

Penyimpanan Azure Queue adalah layanan untuk menyimpan banyak pesan yang dapat diakses dari mana saja di seluruh dunia melalui panggilan terautentikasi menggunakan HTTP atau HTTPS. Satu pesan antrean dapat berukuran hingga 64 KB, dan antrean dapat berisi jutaan pesan, hingga batas total kapasitas akun penyimpanan. Penyimpanan Queue umumnya digunakan untuk membuat backlog pekerjaan yang akan diproses secara asinkron.

Konsep layanan Queue

Layanan Azure Queue berisi komponen berikut:

• Akun Penyimpanan: Semua akses ke Azure Storage dilakukan melalui akun penyimpanan. Untuk mendapatkan informasi selengkapnya tentang akun penyimpanan, lihat Gambaran umum penyimpanan.

• Queue: 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. Waktu maksimum pesan dapat tetap berada dalam antrean adalah 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, waktu untuk aktif default-nya adalah tujuh hari.

• Format URL: Antrean dapat dialamatkan menggunakan format URL berikut: http://<storage account>.queue.core.windows.net/<queue>

  URL berikut mengatasi antrean dalam diagram:

  http://myaccount.queue.core.windows.net/incoming-orders

Buat akun penyimpanan Azure

Cara termudah untuk membuat akun penyimpanan Azure pertama Anda adalah dengan menggunakan portal Microsoft Azure. Untuk mempelajari selengkapnya, lihat Buat akun penyimpanan.

Anda juga dapat membuat akun penyimpanan Azure dengan menggunakan Microsoft Azure PowerShell,Azure CLI,atau Penyedia Sumber Daya Microsoft Azure Storage untuk .NET.

Jika Anda lebih suka tidak membuat akun penyimpanan di Azure saat ini, Anda juga dapat menggunakan emulator penyimpanan Azurite untuk menjalankan dan menguji kode Anda di lingkungan lokal. Untuk informasi selengkapnya, lihat Gunakan emulator Azurite untuk pengembangan Microsoft Azure Storage lokal.

Membuat aplikasi C++

Dalam panduan ini, Anda akan menggunakan fitur penyimpanan yang dapat dijalankan dalam aplikasi C++.

Untuk melakukannya, Anda harus memasang pustaka klien Azure Storage untuk C++ dan membuat akun Azure Storage di langganan Azure Anda.

Untuk memasang pustaka klien Azure Storage untuk C++, Anda bisa menggunakan metode berikut:

• Linux: Ikuti petunjuk yang diberikan di halaman BACA SAYA tentang pustaka klien Azure Storage: Memulai di Linux.
• Windows: Di Windows, gunakan vcpkg sebagai manajer dependensi. Ikuti mulai cepat untuk menginisialisasivcpkg. Kemudian, gunakan perintah berikut untuk memasang pustaka:

.\vcpkg.exe install azure-storage-cpp

Anda dapat menemukan panduan cara membuat kode sumber dan mengekspor ke NuGet dalam file README.

Konfigurasikan aplikasi Anda untuk mengakses Queue Storage

Tambahkan pernyataan berikut ini ke bagian atas file C++ tempat Anda ingin menggunakan Azure Storage API untuk mengakses antrean:

#include <was/storage_account.h>
#include <was/queue.h>

Siapkan string koneksi Azure Storage

Klien Azure Storage menggunakan string koneksi penyimpanan untuk menyimpan titik akhir dan kredensial untuk mengakses layanan manajemen data. Saat berjalan dalam aplikasi klien, Anda harus menyediakan string koneksi penyimpanan dalam format berikut, menggunakan nama akun penyimpanan Anda dan kunci akses penyimpanan untuk akun penyimpanan yang tercantum di portal Microsoft Azure untuk nilai AccountName dan AccountKey. Untuk informasi tentang akun penyimpanan dan kunci akses, lihat Tentang akun Azure Storage. Contoh ini memperlihatkan cara Anda dapat mendeklarasikan bidang statis untuk menahan string koneksi:

// Define the connection-string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=your_storage_account;AccountKey=your_storage_account_key"));

Untuk menguji aplikasi di komputer Windows lokal, Anda dapat menggunakan emulator penyimpanan Azurite. Azurite adalah utilitas yang mensimulasikan Azure Blob Storage dan Queue Storage pada mesin pengembangan lokal Anda. Contoh berikut menunjukkan cara Anda dapat mendeklarasikan bidang statis untuk menahan string koneksi ke emulator penyimpanan lokal Anda:

// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));  

Untuk memulai Azurite, lihat Gunakan emulator Azurite untuk pengembangan Azure Storage lokal.

Sampel berikut mengasumsikan bahwa Anda telah menggunakan salah satu dari dua metode ini untuk mendapat string koneksi penyimpanan.

Ambil string koneksi Anda

Anda dapat menggunakan kelas cloud_storage_account untuk mewakili informasi akun penyimpanan Anda. Untuk mengambil informasi akun penyimpanan Anda dari string koneksi penyimpanan, Anda dapat menggunakan metode parse.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

Cara: Membuat antrean

Objek cloud_queue_client memungkinkan Anda mendapat objek referensi untuk antrean. Kode berikut membuat suatu cloud_queue_client objek.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create a queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

Gunakan cloud_queue_client objek untuk mendapat referensi ke antrean yang ingin Anda gunakan. Anda dapat membuat antrean jika tidak ada.

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Create the queue if it doesn't already exist.
queue.create_if_not_exists();  

Cara: Menyisipkan pesan ke antrean

Untuk menyisipkan pesan ke dalam antrean yang sudah ada, pertama-tama buat cloud_queue_message baru. Selanjutnya, panggil metode add_message. cloud_queue_message dapat dibuat baik dari string (dalam format UTF-8) atau byte array. Berikut adalah kode yang membuat antrean (jika tidak ada) dan menyisipkan pesan Hello, World:

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Create the queue if it doesn't already exist.
queue.create_if_not_exists();

// Create a message and add it to the queue.
azure::storage::cloud_queue_message message1(U("Hello, World"));
queue.add_message(message1);  

Cara: Mengintip pesan berikutnya

Anda dapat mengintip pesan dalam antrean tanpa menghapusnya dari antrean dengan memanggil metode peek_message.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Peek at the next message.
azure::storage::cloud_queue_message peeked_message = queue.peek_message();

// Output the message content.
std::wcout << U("Peeked message content: ") << peeked_message.content_as_string() << std::endl;

Cara: Mengubah konten pesan yang diantrekan

Anda dapat mengubah konten suatu pesan di tempat di dalam antrean. Jika pesan itu mewakili tugas kerja, Anda bisa menggunakan fitur ini untuk memperbarui status tugas kerja. Kode berikut memperbarui pesan antrean dengan konten baru, dan mengatur batas waktu visibilitas untuk memperpanjang 60 detik lagi. Ini menyimpan status pekerjaan yang terkait dengan pesan, dan memberi klien waktu satu menit lagi untuk terus mengerjakan pesan. Anda dapat menggunakan teknik ini untuk melacak alur kerja multilangkah pada pesan antrean, tanpa harus memulai dari awal jika langkah pemrosesan gagal karena kegagalan perangkat keras atau perangkat lunak. Biasanya, Anda akan menyimpan jumlah coba lagi juga, dan jika pesan dicoba lebih dari n, kali, Anda akan menghapusnya. Ini melindungi terhadap pesan yang memicu kesalahan aplikasi setiap kali diproses.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Get the message from the queue and update the message contents.
// The visibility timeout "0" means make it visible immediately.
// The visibility timeout "60" means the client can get another minute to continue
// working on the message.
azure::storage::cloud_queue_message changed_message = queue.get_message();

changed_message.set_content(U("Changed message"));
queue.update_message(changed_message, std::chrono::seconds(60), true);

// Output the message content.
std::wcout << U("Changed message content: ") << changed_message.content_as_string() << std::endl;  

Cara: Mengeluarkan pesan berikutnya dari antrean

Kode Anda akan menghapus pesan dari antrean dalam dua langkah. Saat Anda memanggil get_message, Anda mendapat pesan berikutnya dalam antrean. Pesan yang dberikan oleh get_message menjadi tidak terlihat oleh pesan pembacaan kode lainnya dari antrean ini. Untuk menyelesaikan menghapus pesan dari antrean, Anda juga harus memanggil delete_message. Proses dua langkah menghapus pesan ini memastikan bahwa jika kode Anda gagal memproses pesan karena kegagalan perangkat keras atau perangkat lunak, instans lain dari kode Anda bisa mendapat pesan yang sama dan mencoba lagi. Kode Anda memanggil delete_message tepat setelah pesan telat diproses.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Get the next message.
azure::storage::cloud_queue_message dequeued_message = queue.get_message();
std::wcout << U("Dequeued message: ") << dequeued_message.content_as_string() << std::endl;

// Delete the message.
queue.delete_message(dequeued_message);

Cara: Menggunakan opsi tambahan untuk mengeluarkan pesan dari antrean

Ada dua cara untuk mengustomisasi pengambilan pesan dari antrean. Pertama, Anda bisa mendapatkan batch pesan (hingga 32). Kedua, Anda dapat mengatur batas waktu invisibilitas yang lebih lama atau lebih pendek, yang memungkinkan kode Anda lebih banyak atau lebih sedikit waktu untuk memproses setiap pesan sepenuhnya. Contoh kode berikut ini menggunakan metode get_messages untuk mendapat 20 pesan dalam satu panggilan. Kemudian, ini memproses setiap pesan menggunakan loop for. Ini juga mengatur batas waktu invisibilitas pandang menjadi lima menit untuk setiap pesan. Perhatikan bahwa lima menit dimulai untuk semua pesan pada saat yang sama, jadi setelah lima menit berlalu sejak panggilan ke get_messages, pesan apa pun yang belum dihapus akan terlihat lagi.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Dequeue some queue messages (maximum 32 at a time) and set their visibility timeout to
// 5 minutes (300 seconds).
azure::storage::queue_request_options options;
azure::storage::operation_context context;

// Retrieve 20 messages from the queue with a visibility timeout of 300 seconds.
std::vector<azure::storage::cloud_queue_message> messages = queue.get_messages(20, std::chrono::seconds(300), options, context);

for (auto it = messages.cbegin(); it != messages.cend(); ++it)
{
    // Display the contents of the message.
    std::wcout << U("Get: ") << it->content_as_string() << std::endl;
}

Cara: Mendapatkan panjang antrean

Anda bisa mendapat estimasi jumlah pesan dalam antrean. Metode download_attributes ini memberi properti antrean termasuk jumlah pesan. Metode approximate_message_count ini mendapatkan perkiraan jumlah pesan dalam antrean.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Fetch the queue attributes.
queue.download_attributes();

// Retrieve the cached approximate message count.
int cachedMessageCount = queue.approximate_message_count();

// Display number of messages.
std::wcout << U("Number of messages in queue: ") << cachedMessageCount << std::endl;  

Cara: Menghapus antrean

Untuk menghapus antrean dan semua pesan yang terkandung di dalamnya, panggil metode delete_queue_if_exists pada objek antrean.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// If the queue exists and delete it.
queue.delete_queue_if_exists();  

Langkah berikutnya

Sekarang setelah Anda mempelajari dasar-dasar Queue Storage, ikuti tautan ini untuk mempelajari hal yang lebih kompleks dari Azure Storage.

• Cara menggunakan Blob Storage dari C++
• Cara menggunakan Table Storage dari C++
• Daftar sumber daya Azure Storage di C++
• Pustaka klien Microsoft Azure Storage untuk referensi C++
• Dokumentasi Azure Storage