إرسال رسائل إلى موضوع Azure Service Bus وتلقي رسائل من الاشتراكات في الموضوع (Python)

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

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

إشعار

يوفر هذا التشغيل السريع إرشادات خطوة بخطوة لسيناريو بسيط لإرسال دفعة من الرسائل إلى موضوع ناقل خدمة Microsoft Azure وتلقي تلك الرسائل من اشتراك في الموضوع. يمكنك العثور على عينات Python التي تم إنشاؤها مسبقا ناقل خدمة Azure في مستودع Azure SDK ل Python على GitHub.

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

إشعار

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

  2. اخترحفظ في شريط الأدوات.

  3. أدخل اسمالموضوع. اترك الخيارات الأخرى بقيمها الافتراضية.

  4. حدد إنشاء.

    Image showing the Create topic page.

إنشاء اشتراك في الموضوع.

  1. حدد الموضوعالذي أنشأته في القسم السابق.

    Image showing the selection of topic from the list of topics.

  2. في صفحة Service Bus Topic حدد+ Subscriptionعلى شريط الأدوات

    Image showing the Add subscription button.

  3. في صفحة Create subscription، اتبع الخطوات التالية:

    1. أدخل S1لاسم الاشتراك.

    2. أدخل 3 لعدد التسليم الأقصى.

    3. ثم حدد Createلإنشاء الاشتراك.

      Image showing the Create subscription page.

مصادقة التطبيق إلى 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. حدد مراجعة + تعيين للانتقال إلى الصفحة النهائية، ثم مراجعة + تعيين مرة أخرى لإكمال العملية.

إعداد التعليمات البرمجية

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

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

هام

تأكد من تسجيل الدخول باستخدام az login. DefaultAzureCredential تستخدم الفئة في التعليمات البرمجية بدون كلمة مرور بيانات اعتماد Azure CLI للمصادقة باستخدام معرف Microsoft Entra.

لاستخدام التعليمات البرمجية بدون كلمة مرور، ستحتاج إلى تحديد:

  • مساحة اسم ناقل الخدمة المؤهلة بالكامل، على سبيل المثال: <service-bus-namespace.servicebus.windows.net>
  • اسم الموضوع
  • اسم الاشتراك

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

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

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

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

إرسال رسائل إلى موضوع

يوضح نموذج التعليمات البرمجية التالي كيفية إرسال مجموعة من الرسائل إلى موضوع Service Bus. راجع تعليقات التعليمات البرمجية للحصول على التفاصيل.

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

  1. أضف عبارات import التالية.

    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"
    TOPIC_NAME = "TOPIC_NAME"
    
    credential = DefaultAzureCredential()
    

    هام

    • استبدل FULLY_QUALIFIED_NAMESPACE بمساحة الاسم المؤهلة بالكامل لمساحة اسم ناقل خدمة Microsoft Azure.
    • استبدل TOPIC_NAME باسم الموضوع.

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

  3. أضف طريقة لإرسال رسالة واحدة.

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

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

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

    async def send_a_list_of_messages(sender):
        # Create a list of messages
        messages = [ServiceBusMessage("Message in list") for _ in range(5)]
        # send the list of messages to the topic
        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 topic
            await sender.send_messages(batch_message)
        print("Sent a batch of 10 messages")
    
  6. قم بإنشاء عميل Service Bus ثم كائن مرسل الموضوع لإرسال الرسائل.

    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 Topic Sender object to send messages to the topic
            sender = servicebus_client.get_topic_sender(topic_name=TOPIC_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()
    
    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"
    SUBSCRIPTION_NAME = "SUBSCRIPTION_NAME"
    TOPIC_NAME = "TOPIC_NAME"
    
    credential = DefaultAzureCredential()
    
  2. إنشاء عميل ناقل خدمة 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:
    
            async with servicebus_client:
                # get the Subscription Receiver object for the subscription
                receiver = servicebus_client.get_subscription_receiver(topic_name=TOPIC_NAME, 
                subscription_name=SUBSCRIPTION_NAME, max_wait_time=5)
                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 subscription
                        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

حدد الموضوع في الجزء السفلي لمشاهدة صفحة Service Bus Topic لموضوعك. في هذه الصفحة، من المفترض أن ترى ثلاث رسائل واردة وثلاث رسائل صادرة في مخطط الرسائل.

Incoming and outgoing messages

في هذه الصفحة، إذا حددت اشتراكاً، فستصل إلى صفحة اشتراك Service Bus. يمكنك رؤية عدد الرسائل النشطة وعدد الرسائل المهملة والمزيد في هذه الصفحة. في هذا المثال، تم استلام جميع الرسائل، وبالتالي فإن عدد الرسائل النشطة هو صفر.

Active message count

إذا قمت بالتعليق على رمز الاستلام، فسترى أن عدد الرسائل النشطة هو 16.

Active message count - no receive

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

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