⁧⁩كيفية استخدام تخزين قائمة الانتظار من C++⁧⁩

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

تلميح

شغل Microsoft Azure Storage Explorer

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

نظرة عامة

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

ملاحظة

يستهدف هذا الدليل مكتبة عميل تخزين Azure لـ C++ الإصدار 1.0.0 وما بعده. الإصدار الموصى به هو مكتبة عميل تخزين Azure الإصدار 2.2.0، والذي يتوفر عبر NuGet أو GitHub.

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

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

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

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

• حساب التخزين:تتم جميع إجراءات الوصول إلى Azure Storage من خلال حساب تخزين. لمزيد من المعلومات حول حسابات التخزين، راجع ⁧⁩«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 في استخدام مدخل Microsoft Azure. لمعرفة المزيد، اطلع على إنشاء حساب تخزين.

يُمكنك أيضا إنشاء حساب تخزين Azure باستخدام AzurePowerShell أو AzureCLI أوموفر موارد تخزين Azure ل .NET.

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

إنشاء تطبيق C++ جديد

في هذا الدليل، ستستخدم ميزات التخزين التي يمكن تشغيلها داخل تطبيق C++‎.

للقيام بذلك، ستحتاج إلى تثبيت مكتبة عميل تخزين Azure لـ C++ وإنشاء حساب تخزين Azure في اشتراك Azure لديك.

لتثبيت مكتبة عميل تخزين Azure لـ C++، يمكنك استخدام الطرق التالية:

• Linux: اتبع الإرشادات الواردة في صفحة مكتبة عميل تخزين Azure لملف C++ التمهيدي: بدء العمل على نظام التشغيل Linux.
• ⁧⁩Windows:⁧⁩ على Windows، استخدم ⁧⁩vcpkg⁧⁩ كمدير التبعية. اتبع التشغيل السريع لتهيئة vcpkg. ثم استخدم الأمر التالي لتثبيت المكتبة:

.\vcpkg.exe install azure-storage-cpp

يمكنك العثور على دليل بشأن كيفية إنشاء التعليمات البرمجية المصدر والتصدير إلى Nuget في ملف الملف التمهيدي.

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

أضف عبارات التضمين التالية إلى أعلى ملف C++ حيث تريد استخدام واجهات برمجة التطبيقات لتخزين Azure للوصول إلى قوائم الانتظار:

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

بإعداد سلسلة اتصال Azure Storage

يستخدم عميل تخزين Azure سلسلة اتصال تخزين لتخزين نقاط النهاية، وبيانات الاعتماد للوصول إلى خدمات إدارة البيانات. عند التشغيل في تطبيق عميل، يجب عليك توفير سلسلة اتصال التخزين بالتنسيق التالي، باستخدام اسم حساب التخزين الخاص بك، ومفتاح اختصار التخزين لحساب التخزين المدرج في ⁧⁩مدخل Microsoft Azure⁧⁩ لقيمتي ⁧AccountName⁩ و ⁧AccountKey⁩. للحصول على معلومات حول حسابات التخزين ومفاتيح الاختصار، راجع حول حسابات تخزين Azure. يوضح هذا المثال كيف يمكنك إعلان حقل ثابت لاستيعاب سلسلة الاتصال:

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

لاختبار التطبيق الخاص بك في كمبيوتر Windows المحلي، يمكنك استخدام محاكي تخزين Azurite. إن Azurite هي أداة مساعدة تحاكي Azure Blob Storage و"تخزين قائمة الانتظار" على جهاز التطوير المحلي لديك. يوضح المثال التالي كيفية إعلان حقل ثابت للاحتفاظ بسلسلة الاتصال بمحاكي التخزين المحلي لديك:

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

لبدء تشغيل Azurite، راجع استخدام محاكي Azurite لتطوير تخزين Azure المحلي.

تفترض العينات التالية أنك استخدمت إحدى طريقتين للحصول على سلسلة اتصال التخزين.

استرداد سلسلة الاتصال الخاصة بك

يمكنك استخدام فئة ⁧cloud_storage_account⁩ لتمثيل معلومات حساب التخزين الخاص بك. لاسترداد معلومات حساب التخزين الخاص بك من سلسلة اتصال التخزين، استخدم الطريقة parse.

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

كيفية: إنشاء قائمة انتظار

يتيح لك عنصر cloud_queue_client الحصول على عناصر مرجعية لقوائم الانتظار. تُنشئ التعليمات البرمجية التالية عنصر cloud_queue_client.

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

استخدم العنصر 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();  

كيفية: إدراج رسالة في قائمة انتظار

لإدراج رسالة في قائمة انتظار موجودة، قم أولاً بإنشاء cloud_queue_message جديدة. بعد ذلك، قم باستدعاء أسلوب add_message. يمكن إنشاء cloud_queue_message إما من السلسلة (بتنسيق UTF-8) أو من صفيف البايت. إليك التعليمة البرمجية التي تُنشئ قائمة انتظار (إذا لم تكن موجودة) وتدرج الرسالة 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);  

كيفية: التحرير السريع عند الرسالة التالية

يمكنك التحرير السريع للرسالة الموجودة في مقدمة أي قائمة انتظار دون إزالتها من قائمة الانتظار عن طريق استدعاء الطريقة 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;

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

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

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

كيفية: إلغاء انتظار الرسالة التالية

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

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

كيفية: استخدام خيارات إضافية لإزالة الرسائل من القائمة

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

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

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

يمكنك الحصول على تقدير لعدد الرسائل في قائمة انتظار. أسلوب download_attributesيرجع خصائص قائمة الإنتظار بما في ذلك عدد الرسائل. تحتوي الخاصية approximate_message_countعلى العدد التقريبي للرسائل الموجودة في قائمة الانتظار.

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

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

لحذف قائمة انتظار وكافة الرسائل المضمنة فيه، استدعىي الأسلوب delete_queue_if_existsعلى عنصر قائمة الإنتظار.

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

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

الآن وقد تعرفت على أساسيات "تخزين قائمة الانتظار"، اتبع هذه الارتباطات لمعرفة المزيد حول تخزين Azure.

• كيفية استخدام تخزين الكائنات الثنائية كبيرة الحجم من C++‎
• كيفية استخدام "تخزين الجدول" من C++‎
• ⁧⁩سرد موارد تخزين Azure في C++⁧⁩
• مكتبة عميل تخزين Azure لمرجع C++‎
• توثيق Azure Storage