Share via

التشغيل السريع: مكتبة عميل Azure Queue Storage ل .NET

  • مقالة

ابدأ مع مكتبة عميل Azure Queue Storage ل .NET. Azure Queue Storage هي خدمة لتخزين أعداد كبيرة من الرسائل لاسترجاعها ومعالجتها لاحقاً. يُرجى اتباع هذه الخطوات لتثبيت الحزمة وتجربة التعليمات البرمجية للمهام الأساسية.

واجهة برمجة التطبيقات الوثائق المرجعية | التعليمات البرمجية لمصدر المكتبة | حزمة (NuGet) | العينات

استخدم مكتبة عميل Azure Queue Storage ل .NET من أجل:

  • إنشاء ‏‫‏‏قائمة انتظار‬
  • إضافة رسائل إلى قائمة انتظار
  • إلقاء نظرة خاطفة على الرسائل الموجودة في قائمة الانتظار
  • تحديث رسالة في قائمة انتظار
  • الحصول على طول قائمة الانتظار
  • استقبال الرسائل من قائمة الانتظار
  • حذف الرسائل من قائمة الانتظار
  • حذف قائمة انتظار

المتطلبات الأساسية

الإعداد

يرشدك هذا القسم خلال إعداد مشروع للعمل مع مكتبة عميل Azure Queue Storage ل .NET.

إنشاء مشروع

إنشاء تطبيق .NET باسم QueuesQuickstart.

  1. في نافذة وحدة تحكم (مثل cmd أو PowerShell أو Bash)، استخدم الأمر ⁧dotnet new⁩ لإنشاء تطبيق وحدة تحكم جديد بالاسم ⁧QueuesQuickstart⁩. ينشئ هذا الأمر مشروع C# بسيط "hello world" مع ملف مصدر واحد يسمى Program.cs.

    dotnet new console -n QueuesQuickstart

  2. قم بالتبديل إلى دليل QueuesQuickstart المنشأ حديثاً.

    cd QueuesQuickstart

قم بتثبيت الحِزَم

أثناء الاستمرار في دليل التطبيق، ثبّت مكتبة عميل Azure Queue Storage لحزمة.NET باستخدام الأمرdotnet add package.

dotnet add package Azure.Storage.Queues

حزمة مكتبة عميل Azure Identity مطلوبة أيضا للاتصالات بدون كلمة مرور بخدمات Azure.

dotnet add package Azure.Identity

إعداد إطار عمل التطبيق

  1. افتح المشروع في المحرر الذي تختاره
  2. افتح ملف Program.cs
  3. تحديث التعليمات البرمجية الموجودة لمطابقة ما يلي:
using Azure;
using Azure.Identity;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;
using System.Threading.Tasks;

Console.WriteLine("Azure Queue Storage client library - .NET quickstart sample");

// Quickstart code goes here

مصادقة Azure

يجب التصريح بطلبات التطبيق إلى معظم خدمات Azure. DefaultAzureCredential استخدام الفئة التي توفرها مكتبة عميل Azure Identity هو الأسلوب الموصى به لتنفيذ الاتصالات بدون كلمة مرور بخدمات Azure في التعليمات البرمجية الخاصة بك.

يمكنك أيضا تخويل الطلبات إلى خدمات Azure باستخدام كلمات المرور أو سلسلة الاتصال أو بيانات الاعتماد الأخرى مباشرة. ومع ذلك، ينبغي استخدام هذا النهج بحذر. يجب أن يكون المطورون مجتهدا لعدم كشف هذه الأسرار في موقع غير آمن. يمكن لأي شخص لديه حق الوصول إلى كلمة المرور أو المفتاح السري المصادقة. DefaultAzureCredential يوفر مزايا إدارة وأمان محسنة عبر مفتاح الحساب للسماح بالمصادقة التي لا تتطلب كلمة مرور. يتم عرض كلا الخيارين في المثال التالي.

DefaultAzureCredential هي فئة توفرها مكتبة عميل Azure Identity ل .NET. لمعرفة المزيد حول DefaultAzureCredential، راجع نظرة عامة على DefaultAzureCredential. DefaultAzureCredential يدعم أساليب مصادقة متعددة ويحدد الأسلوب الذي يجب استخدامه في وقت التشغيل. يمكن هذا النهج تطبيقك من استخدام أساليب مصادقة مختلفة في بيئات مختلفة (البيئة المحلية مقابل بيئة التشغيل) دون تنفيذ التعليمات البرمجية الخاصة بالبيئة.

على سبيل المثال، يمكن لتطبيقك المصادقة باستخدام بيانات اعتماد تسجيل الدخول إلى Visual Studio عند التطوير محليا، ثم استخدام هوية مدارة بمجرد نشرها في Azure. لا توجد تغييرات في التعليمات البرمجية مطلوبة لهذه المرحلة الانتقالية.

عند التطوير محليا، تأكد من أن حساب المستخدم الذي يصل إلى بيانات قائمة الانتظار لديه الأذونات الصحيحة. ستحتاج إلى مساهم بيانات قائمة انتظار التخزين لقراءة بيانات قائمة الانتظار وكتابتها. لتعيين هذا الدور لنفسك، ستحتاج إلى تعيين دور المستخدم Access مسؤول istrator، أو دور آخر يتضمن إجراء Microsoft.Authorization/roleAssignments/write. يمكنك تعيين أدوار Azure RBAC لمستخدم باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell. يمكنك معرفة المزيد حول النطاقات المتوفرة لتعيينات الأدوار في صفحة نظرة عامة على النطاق.

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

سيقوم المثال التالي بتعيين دور مساهم بيانات قائمة انتظار التخزين لحساب المستخدم الخاص بك، والذي يوفر حق الوصول للقراءة والكتابة إلى بيانات قائمة الانتظار في حساب التخزين الخاص بك.

هام

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

  1. في مدخل Microsoft Azure، حدد موقع حساب التخزين الخاص بك باستخدام شريط البحث الرئيسي أو شريط التنقل الأيسر.

  2. في صفحة نظرة عامة على حساب التخزين، حدد التحكم بالوصول (IAM) من القائمة اليسرى.

  3. حدد صفحة التحكم بالوصول (IAM)، وحدد علامة تبويب تعيينات الدور.

  4. حدد + إضافة من القائمة العلوية ثم إضافة تعيين الدور من القائمة المنسدلة الناتجة.

A screenshot showing how to assign a role.

  1. استخدم مربع البحث لتصفية النتائج إلى الدور المطلوب. في هذا المثال، ابحث عن مساهم بيانات قائمة انتظار التخزين وحدد النتيجة المطابقة ثم اختر التالي.

  2. ضمن تعيين الوصول إلى، حدد المستخدم أو المجموعة أو كيان الخدمة، ثم اختر + تحديد الأعضاء.

  3. في مربع الحوار، ابحث عن اسم مستخدم Microsoft Entra (عنوان بريدك الإلكتروني user@domain عادة) ثم اختر تحديد في أسفل مربع الحوار.

  4. حدد مراجعة + تعيين للانتقال إلى الصفحة النهائية، ثم مراجعة + تعيين مرة أخرى لإكمال العملية.

نموذج الكائن

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

  • حساب التخزين: تتم جميع إجراءات الوصول إلى Azure Storage من خلال حساب تخزين. لمزيد من المعلومات حول حسابات التخزين، راجع نظرة عامة على حساب التخزين
  • قائمة الانتظار: تحتوي قائمة الانتظار على مجموعة من الرسائل. يجب أن تكون كافة الرسائل في قائمة انتظار. لاحظ أن اسم قائمة الانتظار يجب أن تكون بحروف صغيرة. من أجل الحصول على معلومات حول تسمية قوائم الانتظار، راجع تسمية قوائم الانتظار وبيانات التعريف.
  • رسالة: يصل حجم الرسالة، بأي تنسيق، إلى 64 كيلوبايت. يمكن أن تبقى الرسالة في قائمة الانتظار لمدة أقصاها 7 أيام. بالنسبة إلى الإصدار بتاريخ 2017-07-29 أو الأحدث، يمكن أن تكون أقصى مدة للبقاء أي رقم إيجابي، أو -1 يشير إلى أن الرسالة لا تنتهي صلاحيتها. إذا حُذفت هذه المعلمة، فإن مدة البقاء الافتراضية هي سبعة أيام.

يعرض الرسم التخطيطي التالي العلاقة بين هذه الموارد.

Diagram of Queue storage architecture

سوف تستخدم فئات .NET التالية للتفاعل مع هذه الموارد:

  • QueueServiceClientالـQueueServiceClientيتيح إمكانية إدارة جميع قوائم الانتظار في حسابات التخزين.
  • QueueClient: تسمح لك الفئة QueueClient بإدارة قائمة انتظار فردية ورسائلها ومعالجتها.
  • QueueMessage: تمثل الفئة QueueMessage الكائنات الفردية التي يتم إرجاعها عند استدعاء ReceiveMessages في قائمة انتظار.

أمثلة على التعليمات البرمجية

توضح لكم هذه المقتطفات البرمجية المثال على كيفية تنفيذ الإجراءات التالية مع مكتبة عميل Azure Queue Storage لـ .NET:

تخويل الوصول وإنشاء كائن عميل

للتطوير المحلي، تأكد من مصادقتك باستخدام حساب Microsoft Entra نفسه الذي قمت بتعيين الدور إليه. يمكنك المصادقة عبر أدوات التطوير الشائعة، مثل Azure CLI أو Azure PowerShell. تختلف أدوات التطوير التي يمكنك المصادقة بها عبر اللغات.

سجل الدخول إلى Azure من خلال Azure CLI باستخدام الأمر التالي:

az login

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

للتخويل باستخدام DefaultAzureCredential، تأكد من إضافة حزمة Azure.Identity ، كما هو موضح في تثبيت الحزم. تأكد أيضا من إضافة توجيه استخدام لمساحة Azure.Identity الاسم في ملف Program.cs :

using Azure.Identity;

بعد ذلك، حدد اسما لقائمة الانتظار وأنشئ مثيلا للفئة QueueClient ، باستخدام DefaultAzureCredential للتخويل. نستخدم كائن العميل هذا لإنشاء مورد قائمة الانتظار والتفاعل معه في حساب التخزين.

هام

قد تحتوي أسماء قائمة الانتظار فقط على أحرف صغيرة وأرقام وواصلات، ويجب أن تبدأ بحرف أو رقم. يجب أن تكون كل واصلة مسبوقةً ومتبوعةً بحرف أو رقم. يجب أن يتراوح طول الاسم أيضاً بين 3 و63 حرفاً. للمزيد من المعلومات، يرجى مراجعة تسمية قوائم الانتظار وبيانات التعريف.

أضف التعليمات البرمجية التالية إلى نهاية ملف Program.cs . تأكد من استبدال <storage-account-name> قيمة العنصر النائب:

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

إشعار

يجب أن تكون الرسائل المرسلة QueueClient باستخدام الفئة بتنسيق يمكن تضمينه في طلب XML مع ترميز UTF-8. يمكنك اختياريا تعيين الخيار MessageEncoding إلى Base64 لمعالجة الرسائل غير المتوافقة.

إنشاء ‏‫‏‏قائمة انتظار‬

QueueClient باستخدام الكائن ، قم باستدعاء CreateAsync الأسلوب لإنشاء قائمة الانتظار في حساب التخزين الخاص بك.

أضف هذه التعليمة البرمجية إلى نهاية الأسلوب Program.cs :

Console.WriteLine($"Creating queue: {queueName}");

// Create the queue
await queueClient.CreateAsync();

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

تضيف القصاصة البرمجية التالية على نحو غير متزامن رسائل إلى قائمة الانتظار من خلال استدعاءSendMessageAsync الطريقة. كما أنه يحفظ أيضاً SendReceipt تم إرجاعه من مكالمة SendMessageAsync. يُستخدم الإيصال لتحديث محتوى الرسالة لاحقاً في البرنامج.

أضف هذه التعليمة البرمجية إلى نهاية ملف Program.cs :

Console.WriteLine("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.SendMessageAsync("First message");
await queueClient.SendMessageAsync("Second message");

// Save the receipt so we can update this message later
SendReceipt receipt = await queueClient.SendMessageAsync("Third message");

إلقاء نظرة خاطفة على الرسائل الموجودة في قائمة الانتظار

ألق نظرة خاطفة على الرسائل في قائمة الانتظار من خلال استدعاء الأسلوب PeekMessagesAsync. تسترد هذه الطريقة رسالة واحدة أو أكثر من مقدمة قائمة الانتظار ولكنها لا تغير رؤية الرسالة.

أضف هذه التعليمة البرمجية إلى نهاية ملف Program.cs :

Console.WriteLine("\nPeek at the messages in the queue...");

// Peek at messages in the queue
PeekedMessage[] peekedMessages = await queueClient.PeekMessagesAsync(maxMessages: 10);

foreach (PeekedMessage peekedMessage in peekedMessages)
{
    // Display the message
    Console.WriteLine($"Message: {peekedMessage.MessageText}");
}

تحديث رسالة في قائمة انتظار

قم بتحديث محتويات الرسالة عن طريق استدعاء الطريقة UpdateMessageAsync. يمكن لهذه الطريقة تغيير مهلة رؤية الرسالة ومحتوياتها. يجب أن يكون محتوى الرسالة عبارة عن سلسلة مشفرة UTF-8 يصل حجمها إلى 64 كيلو بايت. مع المحتوى للرسالة، يُرجى تمرير القيم من SendReceipt التي تم حفظها سابقاً في التعليمات البرمجية. تحدد القيمSendReceiptأي رسالة يجب تحديثها.

Console.WriteLine("\nUpdating the third message in the queue...");

// Update a message using the saved receipt from sending the message
await queueClient.UpdateMessageAsync(receipt.MessageId, receipt.PopReceipt, "Third message has been updated");

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

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

أضف هذه التعليمة البرمجية إلى نهاية ملف Program.cs :

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

استقبال الرسائل من قائمة الانتظار

يُرجى تحميل الرسائل المضافة مسبقاً من خلال استدعاء الأسلوب ReceiveMessagesAsync.

أضف هذه التعليمة البرمجية إلى نهاية ملف Program.cs :

Console.WriteLine("\nReceiving messages from the queue...");

// Get messages from the queue
QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 10);

يمكنك اختياريا تحديد قيمة ل maxMessages، وهي عدد الرسائل المراد استردادها من قائمة الانتظار. الإعداد الافتراضي هو رسالة 1 والحد الأقصى هو 32 رسالة. يمكنك أيضا تحديد قيمة ل visibilityTimeout، والتي تخفي الرسائل من العمليات الأخرى لفترة المهلة. المهلة الافتراضية هي 30 ثانية.

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

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

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

أضف هذه التعليمة البرمجية إلى نهاية ملف Program.cs :

Console.WriteLine("\nPress Enter key to 'process' messages and delete them from the queue...");
Console.ReadLine();

// Process and delete messages from the queue
foreach (QueueMessage message in messages)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.MessageText}");

    // Let the service know we're finished with
    // the message and it can be safely deleted.
    await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
}

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

تعمل الشفرة التالية على تنظيف الموارد التي أنشأها التطبيق عن طريق حذف قائمة الانتظار باستخدام الطريقة DeleteAsync.

أضف هذه التعليمة البرمجية إلى نهاية ملف Program.cs :

Console.WriteLine("\nPress Enter key to delete the queue...");
Console.ReadLine();

// Clean up
Console.WriteLine($"Deleting queue: {queueClient.Name}");
await queueClient.DeleteAsync();

Console.WriteLine("Done");

تشغيل التعليمات البرمجية

ينشئ هذا التطبيق ويضيف ثلاث رسائل إلى قائمة انتظار Azure. يسرد الرمز الرسائل الموجودة في قائمة الانتظار، ثم يسترجعها ويحذفها، قبل حذف قائمة الانتظار في النهاية.

في نافذة وحدة التحكم، انتقل إلى دليل التطبيق، ثم أنشئ التطبيق وشغله.

dotnet build

dotnet run

يتشابه إخراج التطبيق مع المثال التالي:

Azure Queue Storage client library - .NET quickstart sample

Creating queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2

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

Receiving messages from the queue...

Press Enter key to 'process' 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-5c72da2c-30cc-4f09-b05c-a95d9da52af2
Done

عندما يتوقف التطبيق مؤقتاً قبل تلقي الرسائل، تحقق من حساب التخزين في "مدخل Microsoft Azure". تحقق من وجود الرسائل في قائمة الانتظار.

اضغط على مفتاح Enter لتلقي الرسائل وحذفها. عند المطالبة، اضغط على مفتاح Enter مرة أخرى لحذف قائمة الانتظار وإنهاء العرض التوضيحي.

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

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

للحصول على الدروس التعليمية والعينات والتشغيلات السريعة وغيرها من الوثائق، يُرجى زيارة:

Azure for .NET and .NET Core developers