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

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

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

إشعار

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

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

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

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

إشعار

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

استخدم Node Package Manager (NPM) لتثبيت الحزمة

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

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

    npm install @azure/service-bus @azure/identity
    

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

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

يجب أن تكون قد سجلت الدخول باستخدام Azure CLI az login لكي يوفر جهازك المحلي المصادقة بدون كلمة مرور المطلوبة في هذه التعليمة البرمجية.

  1. افتح المحرر المفضل، مثل Visual Studio Code

  2. أنشئ ملفًا يُسمى sendtotopic.js وألصق التعليمة البرمجية أدناه فيه. هذا الرمز سيرسل رسالة إلى الموضوع.

    هام

    يتم توفير بيانات الاعتماد بدون كلمة مرور مع DefaultAzureCredential.

    const { ServiceBusClient } = require("@azure/service-bus");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
    const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
    
    // Passwordless credential
    const credential = new DefaultAzureCredential();
    
    const topicName = "<TOPIC NAME>";
    
    const messages = [
        { body: "Albert Einstein" },
        { body: "Werner Heisenberg" },
        { body: "Marie Curie" },
        { body: "Steven Hawking" },
        { body: "Isaac Newton" },
        { body: "Niels Bohr" },
        { body: "Michael Faraday" },
        { body: "Galileo Galilei" },
        { body: "Johannes Kepler" },
        { body: "Nikolaus Kopernikus" }
     ];
    
     async function main() {
        // create a Service Bus client using the passwordless authentication to the Service Bus namespace
        const sbClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
    
        // createSender() can also be used to create a sender for a queue.
        const sender = sbClient.createSender(topicName);
    
        try {
            // Tries to send all messages in a single batch.
            // Will fail if the messages cannot fit in a batch.
            // await sender.sendMessages(messages);
    
            // create a batch object
            let batch = await sender.createMessageBatch();
            for (let i = 0; i < messages.length; i++) {
                // for each message in the array
    
                // try to add the message to the batch
                if (!batch.tryAddMessage(messages[i])) {
                    // if it fails to add the message to the current batch
                    // send the current batch as it is full
                    await sender.sendMessages(batch);
    
                    // then, create a new batch
                    batch = await sender.createMessageBatch();
    
                    // now, add the message failed to be added to the previous batch to this batch
                    if (!batch.tryAddMessage(messages[i])) {
                        // if it still can't be added to the batch, the message is probably too big to fit in a batch
                        throw new Error("Message too big to fit in a batch");
                    }
                }
            }
    
            // Send the last created batch of messages to the topic
            await sender.sendMessages(batch);
    
            console.log(`Sent a batch of messages to the topic: ${topicName}`);
    
            // Close the sender
            await sender.close();
        } finally {
            await sbClient.close();
        }
    }
    
    // call the main function
    main().catch((err) => {
        console.log("Error occurred: ", err);
        process.exit(1);
     });
    
  3. استبدل <SERVICE BUS NAMESPACE CONNECTION STRING> بسلسلة الاتصال إلى اسم نطاق ناقل الخدمة الخاص بك.

  4. استبدل <TOPIC NAME> باسم الموضوع.

  5. ثم قم بتشغيل الأمر في موجه الأوامر لتنفيذ هذا الملف.

    node sendtotopic.js
    
  6. يجب أن ترى الناتج التالي.

    Sent a batch of messages to the topic: mytopic
    

تلقي رسائل من اشتراك

يجب أن تكون قد سجلت الدخول باستخدام Azure CLI az login لكي يوفر جهازك المحلي المصادقة بدون كلمة مرور المطلوبة في هذه التعليمة البرمجية.

  1. افتح المحرر المفضل، مثل Visual Studio Code

  2. قم بإنشاء ملف يسمى receivefromsubscription.js وألصق التعليمة البرمجية التالية فيه. راجع تعليقات التعليمات البرمجية للحصول على التفاصيل.

    const { delay, ServiceBusClient, ServiceBusMessage } = require("@azure/service-bus");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
    const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
    
    // Passwordless credential
    const credential = new DefaultAzureCredential();
    
    const topicName = "<TOPIC NAME>";
    const subscriptionName = "<SUBSCRIPTION NAME>";
    
     async function main() {
        // create a Service Bus client using the passwordless authentication to the Service Bus namespace
        const sbClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
    
        // createReceiver() can also be used to create a receiver for a queue.
        const receiver = sbClient.createReceiver(topicName, subscriptionName);
    
        // function to handle messages
        const myMessageHandler = async (messageReceived) => {
            console.log(`Received message: ${messageReceived.body}`);
        };
    
        // function to handle any errors
        const myErrorHandler = async (error) => {
            console.log(error);
        };
    
        // subscribe and specify the message and error handlers
        receiver.subscribe({
            processMessage: myMessageHandler,
            processError: myErrorHandler
        });
    
        // Waiting long enough before closing the sender to send messages
        await delay(5000);
    
        await receiver.close();
        await sbClient.close();
    }
    
    // call the main function
    main().catch((err) => {
        console.log("Error occurred: ", err);
        process.exit(1);
     });
    
  3. استبدل <SERVICE BUS NAMESPACE CONNECTION STRING> بسلسلة الاتصال لمساحة الاسم.

  4. استبدل <TOPIC NAME> باسم الموضوع.

  5. استبدل <SUBSCRIPTION NAME> باسم الاشتراك للموضوع.

  6. ثم قم بتشغيل الأمر في موجه الأوامر لتنفيذ هذا الملف.

    node receivefromsubscription.js
    

يجب أن ترى الناتج التالي.

Received message: Albert Einstein
Received message: Werner Heisenberg
Received message: Marie Curie
Received message: Steven Hawking
Received message: Isaac Newton
Received message: Niels Bohr
Received message: Michael Faraday
Received message: Galileo Galilei
Received message: Johannes Kepler
Received message: Nikolaus Kopernikus

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

Incoming and outgoing messages

إذا شغَّلت تطبيق الإرسال فقط في المرة القادمة، ففي الصفحة موضوع ناقل خدمة Azure، سترى 20 رسالة واردة (10 جديدة) ولكن 10 رسائل صادرة.

Updated topic page

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

Active message count

استكشاف الأخطاء وإصلاحها

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

تنظيف الموارد

انتقل إلى مساحة اسم ناقل خدمة Microsoft Azure في مدخل Microsoft Azure، وحدد Delete على مدخل Microsoft Azure لحذف مساحة الاسم وقائمة الانتظار فيها.

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

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