كيفية استخدام التخزين في قائمة الانتظار من PHP

مقالة
05/16/2022
قراءة خلال 9 دقائق

تلميح

شغل Microsoft Azure Storage Explorer

يُعد Microsoft Azure Storage Explorer عبارة عن تطبيق مجاني مستقل من Microsoft يمكّنك من العمل بشكل مرئي مع بيانات تخزين Azure على أنظمة التشغيل Windows وmacOS وLinux.

يوضح لك هذا الدليل كيفية تنفيذ السيناريوهات الشائعة باستخدام خدمة تخزين قائمة انتظار Azure. تتم كتابة العينات عبر فئات من مكتبة عميل Azure Storage PHP. تتضمن السيناريوهات المغطاة إدراج رسائل قائمة الانتظار وإلقاء نظرة خاطفة عليها والحصول عليها وحذفها، بالإضافة إلى إنشاء قوائم الانتظار وحذفها.

ما هو التخزين في قائمة الانتظار؟

تخزين قائمة انتظار Azure عبارة عن خدمة لتخزين أعداد كبيرة من الرسائل التي يمكن الوصول إليها من أي مكان في العالم عبر مكالمات مصادق عليها باستخدام HTTP أو HTTPS. يمكن أن يصل حجم رسالة قائمة انتظار واحدة إلى 64 كيلوبايت، ويمكن أن تحتوي قائمة الانتظار على ملايين الرسائل، إلى الحد الأقصى من السعة الإجمالية لحساب التخزين. وغالبًا ما يستخدم تخزين «قائمة الانتظار» لإنشاء تراكم من العمل لمعالجته بشكل غير متزامن.

مفاهيم خدمة قائمة الانتظار

تحتوي خدمة قائمة الانتظار من Azure على المكونات التالية:

Azure Queue service components

حساب التخزين: تتم جميع إجراءات الوصول إلى تخزين Azure من خلال حساب التخزين. لمزيد من المعلومات حول حسابات التخزين، راجع ⁧⁩«Storage account overview»⁧⁩.
قائمة الانتظار: تحتوي قائمة الانتظار على مجموعة من الرسائل. يجب أن تكون كافة الرسائل في قائمة انتظار. لاحظ أن اسم قائمة الانتظار يجب أن تكون بحروف صغيرة. للحصول على معلومات حول تسمية قوائم الانتظار، راجع تسمية قوائم الانتظار وبيانات التعريف.
رسالة: يصل حجم الرسالة، بأي تنسيق، إلى 64 كيلوبايت. إن أقصى مدة لبقاء الرسالة في قائمة الانتظار هي 7 أيام. بالنسبة إلى الإصدار بتاريخ 2017-07-29 أو الأحدث، يمكن أن تكون أقصى مدة للبقاء أي رقم إيجابي، أو -1 يشير إلى أن الرسالة لا تنتهي صلاحيتها. إذا حُذفت هذه المعلمة، فإن مدة البقاء الافتراضية هي سبعة أيام.
تنسيق عنوان URL: يمكن عنونة قوائم الانتظار باستخدام تنسيق عنوان URL التالي: http://<storage account>.queue.core.windows.net/<queue>

عنوان URL التالي يتناول قائمة انتظار في المخطط:

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

إنشاء حساب تخزين Azure

تتمثل أسهل طريقة لإنشاء أول حساب تخزين Azure لك في استخدام مدخل Azure. لمعرفة المزيد، اطلع على إنشاء حساب تخزين.

بإمكانك أيضًا إنشاء حساب تخزين Azure باستخدام Azure PowerShell، أو Azure CLI، أو موفر موارد تخزين Azure لـ .NET.

إذا كنت تفضّل عدم إنشاء حساب تخزين في Azure في الوقت الحالي، يمكنك أيضًا استخدام محاكي تخزين Azurite لتشغيل التعليمات البرمجية واختبارها في بيئة داخلية. لمزيد من المعلومات، راجع استخدام محاكي Azurite لتطوير تخزين Azure الداخلي.

قم بإنشاء تطبيق PHP

المطلب الوحيد لإنشاء تطبيق PHP يصل إلى تخزين قائمة انتظار Azure هو الرجوع إلى الفئات في مكتبة عميل Azure Storage PHP من داخل التعليمات البرمجية الخاصة بك. يمكنك استخدام أي أدوات تطوير لإنشاء تطبيقك، بما في ذلك المفكرة.

في هذا الدليل، تستخدم ميزات خدمة تخزين قائمة الانتظار التي يمكن استدعاؤها داخل تطبيق PHP محليًا، أو في التعليمات البرمجية التي يتم تشغيلها داخل تطبيق ويب في Azure.

احصل على مكتبات عميل Azure

ركّب عبر Composer

أنشئ ملفًا باسم composer.json في جذر مشروعك وأضف التعليمة البرمجية التالية إليه:
```
{
  "require": {
    "microsoft/azure-storage-queue": "*"
  }
}
```
نزّل composer.phar في جذر المشروع الخاص بك.
افتح موجه الأوامر وقم بتشغيل الأمر التالي في جذر مشروعك:
```
php composer.phar install
```

بدلاً من ذلك، انتقل إلى مكتبة عميل Azure Storage PHP على GitHub لاستنساخ كود المصدر.

تكوين التطبيق الخاص بك للوصول إلى قائمة الانتظار التخزين

لاستخدام واجهات برمجة التطبيقات لتخزين قائمة انتظار Azure، تحتاج إلى:

قم بالرجوع إلى ملف أداة التحميل التلقائي باستخدام العبارة require_once.
قم بالإشارة إلى أي فئات قد تستخدمها.

يوضح المثال التالي كيفية تضمين ملف التحميل التلقائي ثم الإشارة إلى الفئة QueueRestProxy.

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

في الأمثلة التالية، يتم عرض العبارة require_once دائمًا، ولكن تتم الإشارة فقط إلى الفئات المطلوبة لتشغيل المثال.

بإعداد اتصال تخزين Azure

لإنشاء مثيل لتخزين قائمة انتظار Azure، يجب أن يكون لديك أولاً سلسلة اتصال صالحة. تنسيق سلسلة الاتصال "تخزين قائمة الانتظار" كما يلي.

للوصول إلى خدمة مباشرة:

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

للوصول إلى مخزن المحاكي:

UseDevelopmentStorage=true

لإنشاء عميل تخزين قائمة انتظار Azure، تحتاج إلى استخدام الفئة QueueRestProxy. يمكنك استخدام أي من الأساليب التالية:

تمرير سلسلة الاتصال مباشرة إليه.
استخدم متغيرات البيئة في تطبيق الويب لتخزين سلسلة الاتصال. راجع مستند إعدادات تكوين تطبيق الويب Azure لتكوين سلاسل الاتصال.

بالنسبة للأمثلة الموضحة هنا، يتم تمرير سلسلة الاتصال مباشرة.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Queue\QueueRestProxy;

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

قم بإنشاء قائمة انتظار

يتيح لك كائن QueueRestProxy إنشاء قائمة انتظار باستخدام طريقة CreateQueue. عند إنشاء قائمة انتظار، يمكنك تعيين الخيارات في قائمة الانتظار، لكن القيام بذلك ليس مطلوبًا. يوضح هذا المثال كيفية تعيين بيانات التعريف في قائمة انتظار.

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

ملاحظة

ينبغي ألا تعتمد على حساسية حالة الأحرف لمفاتيح بيانات التعريف. تتم قراءة جميع المفاتيح من الخدمة بأحرف صغيرة.

إضافة رسالة إلى قائمة الانتظار

لإضافة رسالة إلى قائمة انتظار، استخدم QueueRestProxy->createMessage. تأخذ الطريقة اسم قائمة الانتظار ونص الرسالة وخيارات الرسالة (وهي اختيارية).

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

نظرة خاطفة على الرسالة التالية

يمكنك إلقاء نظرة خاطفة على رسالة واحدة أو أكثر في مقدمة قائمة الانتظار دون إزالتها من خلال الاتصال بالرقم QueueRestProxy->peekMessages. بشكل افتراضي، تقوم الطريقة peekMessage بإرجاع رسالة واحدة، ولكن يمكنك تغيير هذه القيمة باستخدام الطريقة 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 />";
    }
}

إلغاء وضع الرسالة التالية في قائمة الانتظار

يزيل الرمز الخاص بك رسالة من قائمة انتظار في خطوتين. أولاً، تقوم بالاتصال بـ QueueRestProxy->listMessages، مما يجعل الرسالة غير مرئية لأي كود آخر يتم قراءته من قائمة الانتظار. بشكل افتراضي، تبقى هذه الرسالة غير مرئية لمدة 30 ثانية. (إذا لم يتم حذف الرسالة في هذه الفترة الزمنية، فإنها تصبح مرئية في قائمة الانتظار مرة أخرى.) لإنهاء إزالة الرسالة من قائمة الانتظار، يجب عليك الاتصال بـ QueueRestProxy->deleteMessage. تضمن هذه العملية المكونة من خطوتين لإزالة رسالة أنه عندما يفشل الرمز الخاص بك في معالجة رسالة بسبب فشل في الأجهزة أو البرامج، يمكن لمثيل آخر من التعليمات البرمجية الحصول على نفس الرسالة والمحاولة مرة أخرى. تستدعي تعليماتك البرمجية deleteMessage مباشرة بعد معالجة الرسالة.

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

تغيير محتويات رسالة في قائمة الانتظار

يمكنك تغيير محتويات الرسالة في نفس المكان في قائمة الانتظار من خلال استدعاء QueueRestProxy->updateMessage. إذا كانت الرسالة تمثل مهمة عمل، يمكنك استخدام هذه الميزة لتحديث حالة مهمة العمل. يقوم الكود التالي بتحديث رسالة قائمة الانتظار بمحتويات جديدة، ويقوم بتعيين مهلة الرؤية لتمديد 60 ثانية أخرى. يؤدي ذلك إلى حفظ حالة العمل المرتبطة بالرسالة، ويمنح العميل دقيقة أخرى لمواصلة العمل على الرسالة. يمكنك استخدام هذه التقنية لتتبع مهام سير العمل متعددة الخطوات على رسائل قائمة الانتظار، دون الحاجة إلى البدء من جديد في حالة فشل خطوة المعالجة بسبب فشل الأجهزة أو البرامج. عادةً، ستحتفظ أيضًا بعدد مرات إعادة المحاولة، وإذا تمت إعادة محاولة الرسالة أكثر من n مرة، فستحذفها. يحمي ذلك من الرسالة التي تُحدث خطأً في التطبيق في كل مرة تتم معالجتها.

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

خيارات إضافية لإلغاء ترتيب الرسائل

هناك طريقتان يمكنك من خلالهما تخصيص استرداد الرسائل من قائمة انتظار. أولاً، يمكنك الحصول على مجموعة من الرسائل (تصل إلى 32 رسالة). ثانيًا، يمكنك تعيين مهلة رؤية أطول أو أقصر، مما يتيح للكود الخاص بك وقتًا أطول أو أقل لمعالجة كل رسالة بشكل كامل. يستخدم مثال التعليمة البرمجية التالي طريقة getMessages للحصول على 16 رسالة في الاستدعاء الواحد. ثم يقوم بمعالجة كل رسالة باستخدام حلقة for. كما أنه يحدّد مهلة الاختفاء إلى خمس دقائق لكل رسالة.

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

احصل على طول قائمة الانتظار

يمكنك الحصول على تقدير لعدد الرسائل في قائمة انتظار. يسترد الأسلوب QueueRestProxy->getQueueMetadata بيانات التعريف بشأن قائمة الانتظار. استدعاء الأسلوب getApproximateMessageCount على الكائن الذي تم إرجاعه يوفر حسابًا لعدد الرسائل الموجودة في قائمة الانتظار. يعتبر العدد تقريبيًا فقط لأنه يمكن إضافة الرسائل أو إزالتها بعد أن يستجيب تخزين قائمة الانتظار لطلبك.

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;

حذف قائمة انتظار

لحذف قائمة انتظار وجميع الرسائل الموجودة بها، قم باستدعاء الأسلوب QueueRestProxy->deleteQueue.

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

الخطوات التالية

الآن بعد أن تعلمت أساسيات تخزين قائمة انتظار Azure، اتبع هذه الارتباطات للتعرف على مهام التخزين الأكثر تعقيدًا:

قم بزيارة مرجع API لمكتبة عميل Azure Storage PHP
راجع مثال قائمة الانتظار المتقدمة.

لمزيد من المعلومات، راجع مركز مطوري PHP.