Cara menggunakan Queue Storage dari PHP

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

Panduan ini memperlihatkan kepada Anda cara melakukan skenario umum dengan menggunakan layanan Azure Queue Storage. Sampel ditulis melalui kelas dari pustaka klien Microsoft Azure Storage untuk PHP. Skenario yang tercakup termasuk menyisipkan, mengintip, mendapatkan, dan menghapus pesan antrean, serta membuat dan menghapus antrean.

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.

Buat aplikasi PHP

Satu-satunya persyaratan untuk membuat aplikasi PHP yang mengakses Azure Queue Storage adalah mereferensikan kelas dalam pustaka klien Azure Storage untuk PHP dari dalam kode Anda. Anda dapat menggunakan alat pengembangan apa pun untuk membuat aplikasi Anda, termasuk Notepad.

Dalam panduan ini, Anda menggunakan fitur layanan Queue Storage yang dapat dipanggil dalam aplikasi PHP secara lokal, atau dalam kode yang berjalan dalam aplikasi web di Azure.

Dapatkan pustaka klien Azure

Pasang melalui komposer

1. Buat file bernama composer.json di akar proyek Anda dan tambahkan kode berikut ke dalamnya:

   {
     "require": {
       "microsoft/azure-storage-queue": "*"
     }
   }
   

2. Unduh composer.phar di akar proyek Anda.

3. Buka command prompt dan jalankan perintah berikut ini di akar proyek Anda:

   php composer.phar install
   

Atau buka pustaka klien Azure Storage PHP GitHub untuk mengkloning kode sumber.

Konfigurasikan aplikasi Anda untuk mengakses Queue Storage

Untuk menggunakan API untuk Azure Queue Storage, Anda perlu:

1. mereferensikan file autoloader dengan menggunakan pernyataan require_once.
2. mereferensikan kelas apa pun yang mungkin Anda gunakan.

Contoh berikut menunjukkan cara menyertakan file autoloader dan rmereferensikan QueueRestProxy kelas.

require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Queue\QueueRestProxy;

Dalam contoh berikut, pernyataan require_once selalu ditampilkan, tetapi hanya kelas yang diperlukan untuk menjalankan contoh direferensikan.

Siapkan koneksi Azure Storage

Untuk menginstansiasikan klien Azure Queue Storage, Anda harus terlebih dahulu memiliki string koneksi yang valid. Format untuk string koneksi Queue Storage adalah sebagai berikut.

Untuk mengakses layanan langsung:

DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]

Untuk mengakses penyimpanan emulator:

UseDevelopmentStorage=true

Untuk membuat klien Azure Queue Storage, Anda harus menggunakan kelas QueueRestProxy. Anda dapat menggunakan salah satu dari teknik berikut:

• Berikan string koneksi langsung ke sana.
• Gunakan variabel lingkungan di aplikasi web Anda untuk menyimpan string koneksi. Lihat dokumen pengaturan konfigurasi aplikasi web Azure untuk mengonfigurasi string koneksi.

Untuk contoh yang diuraikan di sini, string koneksi diteruskan secara langsung.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";
$queueClient = QueueRestProxy::createQueueService($connectionString);

Buat antrean

Objek QueueRestProxy memungkinkan Anda membuat antrean menggunakan metode CreateQueue ini. Saat membuat antrean, Anda dapat mengatur opsi pada antrean, tetapi tidak perlu melakukan itu. Contoh ini memperlihatkan cara mengatur metadata pada antrean.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\CreateQueueOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// OPTIONAL: Set queue metadata.
$createQueueOptions = new CreateQueueOptions();
$createQueueOptions->addMetaData("key1", "value1");
$createQueueOptions->addMetaData("key2", "value2");

try    {
    // Create queue.
    $queueClient->createQueue("myqueue", $createQueueOptions);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Catatan

Anda tidak boleh mengandalkan sensitivitas huruf besar/besar untuk kunci metadata. Semua kunci dibaca dari layanan dalam huruf kecil.

Kirim pesan ke antrean

Kirim pesan ke antrean, gunakan QueueRestProxy->createMessage. Metode ini mengambil nama antrean, teks pesan, dan opsi pesan (opsional).

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\CreateMessageOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Create message.
    $queueClient->createMessage("myqueue", "Hello, World");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Intip pesan berikutnya

Anda dapat mengintip satu pesan atau lebih dalam antrean tanpa menghapusnya dari antrean dengan memanggil QueueRestProxy->peekMessages. Secara default, metode peekMessage ini memberi satu pesan, tetapi Anda dapat mengubah nilai tersebut menggunakan metode PeekMessagesOptions->setNumberOfMessages.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\PeekMessagesOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// OPTIONAL: Set peek message options.
$message_options = new PeekMessagesOptions();
$message_options->setNumberOfMessages(1); // Default value is 1.

try    {
    $peekMessagesResult = $queueClient->peekMessages("myqueue", $message_options);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

$messages = $peekMessagesResult->getQueueMessages();

// View messages.
$messageCount = count($messages);
if($messageCount <= 0){
    echo "There are no messages.<br />";
}
else{
    foreach($messages as $message)    {
        echo "Peeked message:<br />";
        echo "Message Id: ".$message->getMessageId()."<br />";
        echo "Date: ".date_format($message->getInsertionDate(), 'Y-m-d')."<br />";
        echo "Message text: ".$message->getMessageText()."<br /><br />";
    }
}

Hapus pesan berikutnya dari antrean

Kode Anda menghapus pesan dari antrean dalam dua langkah. Pertama, Anda memanggil QueueRestProxy->listMessages, yang membuat pesan tidak terlihat oleh kode lain yang membaca dari antrean. Secara default, pesan ini tetap tidak terlihat selama 30 detik. (Jika pesan tidak dihapus dalam periode waktu ini, pesan akan terlihat pada antrean lagi.) Untuk menyelesaikan menghapus pesan dari antrean, Anda harus memanggil QueueRestProxy->deleteMessage. Proses dua langkah yang 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 deleteMessage tepat setelah pesan telat diproses.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// Get message.
$listMessagesResult = $queueClient->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];

/* ---------------------
    Process message.
   --------------------- */

// Get message ID and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();

try    {
    // Delete message.
    $queueClient->deleteMessage("myqueue", $messageId, $popReceipt);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Ubah konten pesan yang diantrekan

Anda dapat mengubah konten pesan di tempat dalam antrean dengan memanggil QueueRestProxy->updateMessage. 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 ini menetapkan batas waktu visibilitas untuk diperpanjang 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.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Get message.
$listMessagesResult = $queueClient->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];

// Define new message properties.
$new_message_text = "New message text.";
$new_visibility_timeout = 5; // Measured in seconds.

// Get message ID and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();

try    {
    // Update message.
    $queueClient->updateMessage("myqueue",
                                $messageId,
                                $popReceipt,
                                $new_message_text,
                                $new_visibility_timeout);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Gunakan 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 singkat, yang memungkinkan kode Anda lebih banyak atau lebih sedikit waktu untuk memproses setiap pesan sepenuhnya. Contoh kode berikut menggunakan metode getMessages untuk mendapat 16 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.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Queue\Models\ListMessagesOptions;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

// Set list message options.
$message_options = new ListMessagesOptions();
$message_options->setVisibilityTimeoutInSeconds(300);
$message_options->setNumberOfMessages(16);

// Get messages.
try{
    $listMessagesResult = $queueClient->listMessages("myqueue",
                                                     $message_options);
    $messages = $listMessagesResult->getQueueMessages();

    foreach($messages as $message){

        /* ---------------------
            Process message.
        --------------------- */

        // Get message Id and pop receipt.
        $messageId = $message->getMessageId();
        $popReceipt = $message->getPopReceipt();

        // Delete message.
        $queueClient->deleteMessage("myqueue", $messageId, $popReceipt);
    }
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Dapatkan panjang antrean

Anda bisa mendapat estimasi jumlah pesan dalam antrean. Metode QueueRestProxy->getQueueMetadata mengambil metadata tentang antrean. Memanggil metode getApproximateMessageCount pada objek yang dihasilkan memberi hitungan berapa banyak pesan dalam antrean. Hitungan hanyalah perkiraan karena pesan dapat ditambahkan atau dihapus setelah Queue Storage merespons permintaan Anda.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Get queue metadata.
    $queue_metadata = $queueClient->getQueueMetadata("myqueue");
    $approx_msg_count = $queue_metadata->getApproximateMessageCount();
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

echo $approx_msg_count;

Hapus antrean

Untuk menghapus antrean dan semua pesan di dalamnya, panggil metode QueueRestProxy->deleteQueue tersebut.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

$connectionString = "DefaultEndpointsProtocol=http;AccountName=<accountNameHere>;AccountKey=<accountKeyHere>";

// Create queue REST proxy.
$queueClient = QueueRestProxy::createQueueService($connectionString);

try    {
    // Delete queue.
    $queueClient->deleteQueue("myqueue");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://msdn.microsoft.com/library/azure/dd179446.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Langkah berikutnya

Sekarang setelah Anda mempelajari dasar-dasar Azure Queue Storage, ikuti tautan ini untuk mempelajari tugas penyimpanan yang lebih kompleks:

• Kunjungi referensi API untuk pustaka klien Azure Storage PHP
• Lihat contoh antrean tingkat lanjut.

Untuk informasi selengkapnya, lihat Pusat pengembang PHP.