Share via

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

  • مقالة

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

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

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

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

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

الإعداد

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

إنشاء مشروع

إنشاء تطبيق Python باسم queues-quickstart.

  1. في نافذة وحدة التحكم (مثل cmd أو PowerShell أو Bash)، أنشِئ دليلاً جديدًا للمشروع.

    mkdir queues-quickstart

  2. قم بالتبديل إلى دليل التشغيل السريع لقوائم الانتظار التي تم إنشاؤها حديثا.

    cd queues-quickstart

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

من دليل المشروع، قم بتثبيت مكتبة عميل Azure Queue Storage لحزمة Python باستخدام pip install الأمر . حزمة azure-identity مطلوبة للاتصالات بدون كلمة مرور بخدمات Azure.

pip install azure-storage-queue azure-identity

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

  1. يرجى فتح ملف نصي جديد في محرر التعليمات البرمجية

  2. إضافة عبارات import

  3. إنشاء بنية البرنامج، بما في ذلك معالجة الاستثناء الأساسي

    وهنا التعليمة البرمجية:

    import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.queue import QueueServiceClient, QueueClient, QueueMessage, BinaryBase64DecodePolicy, BinaryBase64EncodePolicy

try:
    print("Azure Queue storage - Python quickstart sample")
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

  4. احفظ الملف الجديد queues-quickstart.py في دليل queues-quickstart.

مصادقة Azure

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

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

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

على سبيل المثال، يمكن لتطبيقك المصادقة باستخدام بيانات اعتماد تسجيل الدخول إلى Visual Studio Code عند التطوير محليا، ثم استخدام هوية مدارة بمجرد نشرها في 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

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

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

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

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

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

تأكد من مصادقتك باستخدام حساب Microsoft Entra نفسه الذي قمت بتعيين الدور إليه. يمكنك المصادقة عبر Azure CLI أو Visual Studio Code أو Azure PowerShell.

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

az login

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

للتخويل باستخدام DefaultAzureCredential، تأكد من إضافة حزمة azure-identity ، كما هو موضح في تثبيت الحزم. تأكد أيضا من إضافة عبارة الاستيراد التالية في ملف queues-quickstart.py :

from azure.identity import DefaultAzureCredential

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

هام

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

أضف التعليمات البرمجية try التالية داخل الكتلة، وتأكد من استبدال <storage-account-name> قيمة العنصر النائب:

    print("Azure Queue storage - Python quickstart sample")

    # Create a unique name for the queue
    queue_name = "quickstartqueues-" + str(uuid.uuid4())

    account_url = "https://<storageaccountname>.queue.core.windows.net"
    default_credential = DefaultAzureCredential()

    # Create the QueueClient object
    # We'll use this object to create and interact with the queue
    queue_client = QueueClient(account_url, queue_name=queue_name ,credential=default_credential)

يتم تخزين رسائل قائمة الانتظار كنص. إذا كنت ترغب في تخزين البيانات الثنائية، فقم بإعداد دالات ترميز وفك ترميز Base64 قبل وضع رسالة في قائمة الانتظار.

يمكنك تكوين دالات ترميز وفك ترميز Base64 عند إنشاء كائن العميل:

# Setup Base64 encoding and decoding functions
base64_queue_client = QueueClient.from_connection_string(
                            conn_str=connect_str, queue_name=q_name,
                            message_encode_policy = BinaryBase64EncodePolicy(),
                            message_decode_policy = BinaryBase64DecodePolicy()
                        )

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

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

أضف هذه التعليمات البرمجية إلى الكتلة try:

    print("Creating queue: " + queue_name)

    # Create the queue
    queue_client.create_queue()

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

يضيف مقتطف الشفرة التالي الرسائل إلى قائمة الانتظار من خلال استدعاء الطريقة send_message. كما تقوم أيضًا بحفظ QueueMessageالعائد من الاستدعاءsend_messageالثالث. الـsaved_messageيُستخدم لتحديث محتوى الرسالة لاحقًا في البرنامج.

أضف هذه التعليمات البرمجية إلى الكتلة try:

    print("\nAdding messages to the queue...")

    # Send several messages to the queue
    queue_client.send_message(u"First message")
    queue_client.send_message(u"Second message")
    saved_message = queue_client.send_message(u"Third message")

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

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

أضف هذه التعليمات البرمجية إلى الكتلة try:

    print("\nPeek at the messages in the queue...")

    # Peek at messages in the queue
    peeked_messages = queue_client.peek_messages(max_messages=5)

    for peeked_message in peeked_messages:
        # Display the message
        print("Message: " + peeked_message.content)

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

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

    print("\nUpdating the third message in the queue...")

    # Update a message using the message saved when calling send_message earlier
    queue_client.update_message(saved_message, pop_receipt=saved_message.pop_receipt, \
        content="Third message has been updated")

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

يمكنك الحصول على تقدير لعدد الرسائل في قائمة انتظار.

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

properties = queue_client.get_queue_properties()
count = properties.approximate_message_count
print("Message count: " + str(count))

وتكون النتيجة تقريبية حيث يمكن إضافة الرسائل أو إزالتها بعد استجابة الخدمة لطلبك.

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

يمكنك تنزيل الرسائل المضافة مسبقا عن طريق استدعاء receive_messages الأسلوب .

أضف هذه التعليمات البرمجية إلى الكتلة try:

    print("\nReceiving messages from the queue...")

    # Get messages from the queue
    messages = queue_client.receive_messages(max_messages=5)

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

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

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

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

أضف هذه التعليمات البرمجية إلى الكتلة try:

    print("\nPress Enter key to 'process' messages and delete them from the queue...")
    input()

    for msg_batch in messages.by_page():
            for msg in msg_batch:
                # "Process" the message
                print(msg.content)
                # Let the service know we're finished with
                # the message and it can be safely deleted.
                queue_client.delete_message(msg)

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

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

يرجى إضافة هذه التعليمة البرمجية إلى نهاية try"حظر وحفظ" الملف:

    print("\nPress Enter key to delete the queue...")
    input()

    # Clean up
    print("Deleting queue...")
    queue_client.delete_queue()

    print("Done")

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

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

في نافذة وحدة التحكم، انتقل إلى الدليل الذي يحتوي على ملف queues-quickstart.py ، ثم استخدم الأمر التالي python لتشغيل التطبيق.

python queues-quickstart.py

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

Azure Queue Storage client library - Python quickstart sample
Creating queue: quickstartqueues-<UUID>

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

First message
Second message
Third message has been updated

Press Enter key to delete the queue...

Deleting queue...
Done

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

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

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

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

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

Azure لمطورين Python