إرسال رسائل واستلام الرسائل من قوائم انتظار ناقل خدمة Azure (Python)

في هذا البرنامج التعليمي، تقوم بإكمال المهام التالية:

  1. إنشاء مساحة اسم Service Bus باستخدام المدخل Azure.
  2. إنشاء قائمة انتظار Service Bus باستخدام المدخل Azure.
  3. اكتب تعليمة Python البرمجية لاستخدام حزمة azure-servicebus من أجل:
    1. إرسال مجموعة من الرسائل إلى قائمة الانتظار.
    2. تلقي هذه الرسائل من قائمة الانتظار.

إشعار

توفر هذه البداية السريعة إرشادات خطوة بخطوة لسيناريو بسيط لإرسال مجموعة من الرسائل إلى قائمة انتظار ناقل خدمة Azure وتلقيها منها. يمكنك العثور على نماذج JavaScript وTypeScript لناقل خدمة Azure في SDK Azure لمستودع Pythin على GitHub.

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

إذا كنت جديدًا على الخدمة، راجع نظرة عامة على Service Bus قبل إجراء هذا البدء السريع.

  • اشتراك Azure. لإكمال هذا البرنامج التعليمي، تحتاج إلى حساب Azure. يمكنك تنشيط مزايا مشترك MSDN أو الاشتراك للحصول على حساب مجاني.

  • Python 3.8 أو أعلى.

لاستخدام هذا التشغيل السريع مع حساب Azure الخاص بك:

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

إشعار

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

إنشاء مساحة اسم في مدخل Microsoft Azure

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

لإنشاء مساحة اسم:

  1. قم بتسجيل الدخول إلى بوابة Azure.

  2. انتقل إلى صفحة جميع الخدمات.

  3. في شريط التنقل الأيسر، حدد Integration من قائمة الفئات، وقم بتمرير الماوس فوق ناقل خدمة Microsoft Azure، ثم حدد + الزر على لوحة Service Bus.

    Image showing selection of Create a resource, Integration, and then Service Bus in the menu.

  4. في علامة التبويب "Basics" في صفحة "Create namespace" اتبع الخطوات الآتية:

    1. بالنسبة إلى Subscription، اختر اشتراك Azure لإنشاء مساحة الاسم.

    2. بالنسبة إلى "Resource group"، اختر مجموعة موارد موجودة حيث توجد مساحة الاسم، أو قم بإنشاء مجموعة موارد جديدة.

    3. أدخل name لمساحة الاسم. يجب أن يلتزم اسم مساحة الاسم باصطلاحات التسمية التالية:

      • يجب أن يكون الاسم فريدًا عبر Azure. يتحقق النظام على الفور لمعرفة ما إذا كان الاسم متوفرًا.
      • ألا يقل طول الاسم عن 6 أحرف ولا يزيد عن 50 حرفاً.
      • لا يمكن أن يحتوي الاسم إلا على أحرف وأرقام وواصلات "-".
      • يجب أن يبدأ الاسم وينتهي بحرف أو رقم.
      • ألا ينتهي الاسم بـ "-sb" أو "-mgmt".
    4. بالنسبة إلى "Location"، اختر المنطقة التي ينبغي استضافة مساحة الاسم فيها.

    5. بالنسبة إلى "Pricing tier"، حدد مستوى التسعير (Basic أو Standard أو Premium) لمساحة الاسم. بالنسبة لهذا التشغيل السريع، حدد Standard.

      هام

      وإذا كنت ترغب في استخدام الموضوعات والاشتراكات، فاختر إما "Standard" أو "Premium". فإن الموضوعات/الاشتراكات غير مدعومة في مستوى التسعير الأساسي.

      وإذا حددت مستوى التسعير "Premium"، فحدد عدد وحدات المراسلة. ويوفر المستوى المميز عزل الموارد على مستوى وحدة المعالجة المركزية والذاكرة بحيث يتم تشغيل كل حمل عمل على حدة. تسمى حاوية المورد هذه وحدة المراسلة. وتحتوي مساحة الاسم المميزة على وحدة مراسلة واحدة على الأقل. ويمكنك تحديد وحدات المراسلة 1 أو 2 أو 4 أو 8 أو 16 لكل مساحة اسم مميزة لناقل خدمة Azure. ولمزيد من المعلومات، راجع المراسلة المميزة لناقل خدمة Microsoft Azure.

    6. حدد مراجعة + إنشاء عند أسفل الصفحة.

      Image showing the Create a namespace page

    7. في صفحة "Review + create"، راجع الإعدادات ثم حدد "Create".

  5. بمجرد نجاح نشر المورد، حدد Go to resource في صفحة التوزيع.

    Image showing the deployment succeeded page with the Go to resource link.

  6. راجع الصفحة الرئيسية لمساحة اسم ناقل الخدمة.

    Image showing the home page of the Service Bus namespace created.

إنشاء قائمة الانتظار في مدخل Azure

  1. في الصفحة Service Bus Namespace، حدد قوائم الانتظار في قائمة التنقل اليمنى.

  2. في صفحة قوائم الانتظار، حدد + قائمة انتظار في شريط الأدوات.

  3. أدخل اسمًا لقائمة الانتظار، واترك القيم الأخرى بإعداداتها الافتراضية.

  4. الآن، حدد إنشاء.

    Image showing creation of a queue in the portal

مصادقة التطبيق إلى Azure

تظهر لك هذه البداية السريعة طريقتين للاتصال ناقل خدمة Azure: بدون كلمة مرور سلسلة الاتصال.

يوضح لك الخيار الأول كيفية استخدام أساس الأمان في معرف Microsoft Entra والتحكم في الوصول المستند إلى الدور (RBAC) للاتصال بمساحة اسم ناقل خدمة Microsoft Azure. لا داعي للقلق بشأن وجود تعليمات برمجية مضمنة سلسلة الاتصال في التعليمات البرمجية الخاصة بك أو في ملف تكوين أو في تخزين آمن مثل Azure Key Vault.

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

تعيين أدوار لمستخدم Microsoft Entra

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

يعين Azure Service Bus Data Owner المثال التالي الدور لحساب المستخدم الخاص بك، والذي يوفر الوصول الكامل إلى موارد ناقل خدمة Azure. في سيناريو حقيقي، اتبع مبدأ الامتياز الأقل لمنح المستخدمين الحد الأدنى فقط من الأذونات اللازمة لبيئة إنتاج أكثر أمانا.

أدوار Azure المضمنة لناقل خدمة Azure

بالنسبة إلى ناقل خدمة Azure، تتم حماية إدارة مساحات الأسماء وجميع الموارد المرتبطة بها من خلال مدخل Azure وواجهة برمجة التطبيقات لإدارة الموارد Azure بالفعل باستخدام نموذج Azure RBAC. يوفر Azure أدوار Azure المضمنة أدناه لتخويل الوصول إلى مساحة اسم "ناقل الخدمة":

  • ناقل خدمة Azure مالك البيانات: تمكين الوصول إلى البيانات إلى مساحة اسم ناقل خدمة Microsoft Azure وكياناته (قوائم الانتظار والموضوعات والاشتراكات وعوامل التصفية). يمكن لعضو هذا الدور إرسال رسائل وتلقيها من قوائم الانتظار أو الموضوعات/الاشتراكات.
  • ناقل خدمة Azure Data Sender: استخدم هذا الدور لمنح وصول الإرسال إلى مساحة اسم ناقل خدمة Microsoft Azure والكيانات الخاصة به.
  • ناقل خدمة Azure Data Receiver: استخدم هذا الدور لمنح وصول الاستلام إلى مساحة اسم ناقل خدمة Microsoft Azure وكياناته.

إذا كنت ترغب في إنشاء دور مخصص، فشاهد الحقوق المطلوبة لعمليات ناقل خدمة Microsoft Azure.

إضافة مستخدم Microsoft Entra إلى دور مالك ناقل خدمة Azure

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

هام

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

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

  2. في صفحة النظرة العامة، حدد Access control (IAM) من القائمة اليسرى.

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

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

    A screenshot showing how to assign a role.

  5. استخدم مربع البحث لتصفية النتائج إلى الدور المطلوب. في هذا المثال، ابحث Azure Service Bus Data Owner عن النتيجة المطابقة وحددها. ثم اختر التالي.

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

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

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

استخدام pip لتثبيت الحزم

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

  2. تثبيت الحزم التالية:

    pip install azure-servicebus
    pip install azure-identity
    pip install aiohttp
    

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

توضح لك عينة التعليمة البرمجية التالية كيفية إرسال رسالة إلى قائمة انتظار. افتح المحرر المفضل لديك، مثل Visual Studio Code، وأنشئ ملفا send.py، وأضف التعليمات البرمجية التالية إليه.

  1. إضافة عبارات الاستيراد.

    import asyncio
    from azure.servicebus.aio import ServiceBusClient
    from azure.servicebus import ServiceBusMessage
    from azure.identity.aio import DefaultAzureCredential
    
  2. إضافة ثوابت وتحديد بيانات اعتماد.

    FULLY_QUALIFIED_NAMESPACE = "FULLY_QUALIFIED_NAMESPACE"
    QUEUE_NAME = "QUEUE_NAME"
    
    credential = DefaultAzureCredential()
    

    هام

    • استبدل FULLY_QUALIFIED_NAMESPACE بمساحة الاسم المؤهلة بالكامل لمساحة اسم ناقل خدمة Microsoft Azure.
    • استبدل QUEUE_NAME باسم قائمة الانتظار.
  3. أضف طريقة لإرسال رسالة واحدة.

    async def send_single_message(sender):
        # Create a Service Bus message and send it to the queue
        message = ServiceBusMessage("Single Message")
        await sender.send_messages(message)
        print("Sent a single message")
    

    المرسل هو كائن يعمل كعميل لقائمة الانتظار التي قمت بإنشائها. ستقوم بإنشائه لاحقاً وإرساله كوسيطة لهذه الوظيفة.

  4. أضف طريقة لإرسال قائمة بالرسائل.

    async def send_a_list_of_messages(sender):
        # Create a list of messages and send it to the queue
        messages = [ServiceBusMessage("Message in list") for _ in range(5)]
        await sender.send_messages(messages)
        print("Sent a list of 5 messages")
    
  5. أضف طريقة لإرسال مجموعة من الرسائل.

    async def send_batch_message(sender):
        # Create a batch of messages
        async with sender:
            batch_message = await sender.create_message_batch()
            for _ in range(10):
                try:
                    # Add a message to the batch
                    batch_message.add_message(ServiceBusMessage("Message inside a ServiceBusMessageBatch"))
                except ValueError:
                    # ServiceBusMessageBatch object reaches max_size.
                    # New ServiceBusMessageBatch object can be created here to send more data.
                    break
            # Send the batch of messages to the queue
            await sender.send_messages(batch_message)
        print("Sent a batch of 10 messages")
    
  6. قم بإنشاء عميل ناقل خدمة Microsoft Azure ثم كائن مرسل قائمة انتظار لإرسال الرسائل.

    async def run():
        # create a Service Bus client using the credential
        async with ServiceBusClient(
            fully_qualified_namespace=FULLY_QUALIFIED_NAMESPACE,
            credential=credential,
            logging_enable=True) as servicebus_client:
            # get a Queue Sender object to send messages to the queue
            sender = servicebus_client.get_queue_sender(queue_name=QUEUE_NAME)
            async with sender:
                # send one message
                await send_single_message(sender)
                # send a list of messages
                await send_a_list_of_messages(sender)
                # send a batch of messages
                await send_batch_message(sender)
    
            # Close credential when no longer needed.
            await credential.close()
    
  7. run استدعاء الأسلوب وطباعة رسالة.

    asyncio.run(run())
    print("Done sending messages")
    print("-----------------------")
    

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

يوضح نموذج التعليمات البرمجية التالي كيفية تلقي الرسائل من قائمة انتظار. تتلقى التعليمات البرمجية المعروضة رسائل جديدة حتى لا تتلقى أي رسائل جديدة لمدة 5 (max_wait_time) ثوان.

افتح المحرر المفضل لديك، مثل Visual Studio Code، وأنشئ ملفا recv.py، وأضف التعليمات البرمجية التالية إليه.

  1. على غرار نموذج الإرسال، أضف import عبارات، وحدد الثوابت التي يجب استبدالها بقيمك الخاصة، وحدد بيانات اعتماد.

    import asyncio
    
    from azure.servicebus.aio import ServiceBusClient
    from azure.identity.aio import DefaultAzureCredential
    
    FULLY_QUALIFIED_NAMESPACE = "FULLY_QUALIFIED_NAMESPACE"
    QUEUE_NAME = "QUEUE_NAME"
    
    credential = DefaultAzureCredential()
    
  2. إنشاء عميل ناقل خدمة Microsoft Azure ثم كائن متلقي قائمة انتظار لتلقي الرسائل.

    async def run():
        # create a Service Bus client using the connection string
        async with ServiceBusClient(
            fully_qualified_namespace=FULLY_QUALIFIED_NAMESPACE,
            credential=credential,
            logging_enable=True) as servicebus_client:
    
            async with servicebus_client:
                # get the Queue Receiver object for the queue
                receiver = servicebus_client.get_queue_receiver(queue_name=QUEUE_NAME)
                async with receiver:
                    received_msgs = await receiver.receive_messages(max_wait_time=5, max_message_count=20)
                    for msg in received_msgs:
                        print("Received: " + str(msg))
                        # complete the message so that the message is removed from the queue
                        await receiver.complete_message(msg)
    
            # Close credential when no longer needed.
            await credential.close()
    
  3. run استدعاء الأسلوب .

    asyncio.run(run())
    

تشغيل التطبيق

افتح موجه الأوامر الذي يحتوي على Python في مساره، ثم قم بتشغيل التعليمات البرمجية لإرسال الرسائل وتلقيها من قائمة الانتظار.

python send.py; python recv.py

ينبغي أن تشاهد المخرج التالي:

Sent a single message
Sent a list of 5 messages
Sent a batch of 10 messages
Done sending messages
-----------------------
Received: Single Message
Received: Message in list
Received: Message in list
Received: Message in list
Received: Message in list
Received: Message in list
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch
Received: Message inside a ServiceBusMessageBatch

في مدخل Microsoft Azure، انتقل إلى مساحة اسم ناقل الخدمة. في صفحة "Overview"، تحقق من أن عدد الرسائل "incoming" و"outgoing" هو 16. إذا كنت لا ترى الأعداد، فقم بتحديث الصفحة بعد الانتظار لبضع دقائق.

Incoming and outgoing message count

حدد قائمة الانتظار في هذه الصفحة "Overview" للانتقال إلى صفحة ناقل خدمة Microsoft Azure Queue. يمكنك أيضاً مشاهدة عدد الرسائل "incoming" و"outgoing" في هذه الصفحة. يمكنك أيضاً الاطلاع على معلومات أخرى مثل "current size" لقائمة الانتظار و"active message count".

Queue details

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

راجع الوثائق والعينات التالية: