مشاركة عبر

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

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

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

استخدم مكتبة عميل 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. لا توجد تغييرات في التعليمات البرمجية مطلوبة لهذه المرحلة الانتقالية.

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

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

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

هام

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

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

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

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

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

لقطة شاشة توضح كيفية تعيين دور.

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

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

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

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

نموذج الكائن

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

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

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

رسم تخطيطي لبنية تخزين قائمة الانتظار

استخدم فئات 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")

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

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

ترجع الأسلوب get_queue_properties خصائص قائمة الانتظار بما في ذلك ملف 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

  • Last updated on