إرسال رسائل إلى موضوع "Azure ناقل خدمة Microsoft Azure" وتلقي رسائل من الاشتراكات في الموضوع (Java)
في هذه البداية السريعة، يمكنك كتابة تعليمات برمجية Java باستخدام حزمة خدمة المراسلة اللازوردية لإرسال رسائل إلى موضوع ناقل خدمة Azure ثم تلقي رسائل من الاشتراكات إلى هذا الموضوع.
إشعار
توفر هذه البداية السريعة إرشادات خطوة بخطوة ل سيناريو بسيط لإرسال مجموعة من الرسائل إلى موضوع "ناقل الخدمة"Azure وتلقي تلك الرسائل من اشتراك في الموضوع. يمكنك العثور على عينات Java المعدة مسبقًا لناقل خدمة Azure في مستودع Azure SDK for Java على GitHub.
تلميح
إذا كنت تعمل مع موارد ناقل خدمة Azure في تطبيق Spring، نوصيك بمراعاة Spring Cloud Azure كبديل. Spring Cloud Azure هو مشروع مفتوح المصدر يوفر تكامل Spring سلس مع خدمات Azure. لمعرفة المزيد حول Spring Cloud Azure، ولرؤية مثال باستخدام ناقل خدمة Microsoft Azure، راجع Spring Cloud Stream مع ناقل خدمة Azure.
المتطلبات الأساسية
- اشتراك Azure. لإكمال هذا البرنامج التعليمي، تحتاج إلى حساب Azure. يمكنك تنشيط مزايا المشتركين في Visual Studio أو MSDN أو الاشتراك في حساب مجاني.
- قم بتثبيت Azure SDK for Java. إذا كنت تستخدم Eclipse، يمكنك تثبيت مجموعة أدوات Azure Toolkit for Eclipse التي تتضمن Azure SDK for Java. يمكنك بعد ذلك إضافة Microsoft Azure Libraries for Java إلى المشروع الخاص بك. إذا كنت تستخدم IntelliJ، فراجع «Install Azure Toolkit for IntelliJ».
إنشاء مساحة اسم في مدخل Microsoft Azure
لبدء استخدام الكيانات المراسلة "ناقل الخدمة" في Azure، يجب أولاً إنشاء مساحة اسم باسم مميز عبر Azure. توفر مساحة الاسم حاوية تحديد النطاق لموارد ناقل خدمة Microsoft Azure (قوائم الانتظار والموضوعات وما إلى ذلك) داخل التطبيق الخاص بك.
لإنشاء مساحة اسم:
قم بتسجيل الدخول إلى بوابة Azure.
انتقل إلى صفحة جميع الخدمات.
في شريط التنقل الأيسر، حدد Integration من قائمة الفئات، وقم بتمرير الماوس فوق ناقل خدمة Microsoft Azure، ثم حدد + الزر على لوحة Service Bus.
في علامة التبويب "Basics" في صفحة "Create namespace" اتبع الخطوات الآتية:
بالنسبة إلى Subscription، اختر اشتراك Azure لإنشاء مساحة الاسم.
بالنسبة إلى "Resource group"، اختر مجموعة موارد موجودة حيث توجد مساحة الاسم، أو قم بإنشاء مجموعة موارد جديدة.
أدخل name لمساحة الاسم. يجب أن يلتزم اسم مساحة الاسم باصطلاحات التسمية التالية:
- يجب أن يكون الاسم فريدًا عبر Azure. يتحقق النظام على الفور لمعرفة ما إذا كان الاسم متوفرًا.
- ألا يقل طول الاسم عن 6 أحرف ولا يزيد عن 50 حرفاً.
- لا يمكن أن يحتوي الاسم إلا على أحرف وأرقام وواصلات "-".
- يجب أن يبدأ الاسم وينتهي بحرف أو رقم.
- ألا ينتهي الاسم بـ "-sb" أو "-mgmt".
بالنسبة إلى "Location"، اختر المنطقة التي ينبغي استضافة مساحة الاسم فيها.
بالنسبة إلى "Pricing tier"، حدد مستوى التسعير (Basic أو Standard أو Premium) لمساحة الاسم. بالنسبة لهذا التشغيل السريع، حدد Standard.
هام
وإذا كنت ترغب في استخدام الموضوعات والاشتراكات، فاختر إما "Standard" أو "Premium". فإن الموضوعات/الاشتراكات غير مدعومة في مستوى التسعير الأساسي.
وإذا حددت مستوى التسعير "Premium"، فحدد عدد وحدات المراسلة. ويوفر المستوى المميز عزل الموارد على مستوى وحدة المعالجة المركزية والذاكرة بحيث يتم تشغيل كل حمل عمل على حدة. تسمى حاوية المورد هذه وحدة المراسلة. وتحتوي مساحة الاسم المميزة على وحدة مراسلة واحدة على الأقل. ويمكنك تحديد وحدات المراسلة 1 أو 2 أو 4 أو 8 أو 16 لكل مساحة اسم مميزة لناقل خدمة Azure. ولمزيد من المعلومات، راجع المراسلة المميزة لناقل خدمة Microsoft Azure.
حدد مراجعة + إنشاء عند أسفل الصفحة.
في صفحة "Review + create"، راجع الإعدادات ثم حدد "Create".
بمجرد نجاح نشر المورد، حدد Go to resource في صفحة التوزيع.
راجع الصفحة الرئيسية لمساحة اسم ناقل الخدمة.
إنشاء موضوع باستخدام مدخل Azure
في صفحة ناقل خدمة Service Bus وحددالموضوعاتفي القائمة اليسرى.
اخترحفظ في شريط الأدوات.
أدخل اسمالموضوع. اترك الخيارات الأخرى بقيمها الافتراضية.
حدد إنشاء.
إنشاء اشتراك في الموضوع.
حدد الموضوعالذي أنشأته في القسم السابق.
في صفحة Service Bus Topic حدد+ Subscriptionعلى شريط الأدوات
في صفحة Create subscription، اتبع الخطوات التالية:
أدخل S1لاسم الاشتراك.
أدخل 3 لعدد التسليم الأقصى.
ثم حدد Createلإنشاء الاشتراك.
مصادقة التطبيق إلى 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 دقيقة أو دقيقتين. في حالات نادرة، قد يستغرق الأمر ما يصل إلى ثماني دقائق. إذا تلقيت أخطاء المصادقة عند تشغيل التعليمات البرمجية لأول مرة، فانتظر بضع لحظات وحاول مرة أخرى.
إذا لم تكن صفحة مساحة اسم ناقل خدمة Microsoft Azure مفتوحة في مدخل Microsoft Azure، فحدد موقع مساحة اسم ناقل الخدمة باستخدام شريط البحث الرئيسي أو التنقل الأيسر.
في صفحة النظرة العامة، حدد Access control (IAM) من القائمة اليسرى.
حدد صفحة التحكم بالوصول (IAM)، وحدد علامة تبويب تعيينات الدور.
حدد + إضافة من القائمة العلوية ثم إضافة تعيين الدور من القائمة المنسدلة الناتجة.
استخدم مربع البحث لتصفية النتائج إلى الدور المطلوب. في هذا المثال، ابحث
Azure Service Bus Data Owner
عن النتيجة المطابقة وحددها. ثم اختر التالي.ضمن تعيين الوصول إلى، حدد المستخدم أو المجموعة أو كيان الخدمة، ثم اختر + تحديد الأعضاء.
في مربع الحوار، ابحث عن اسم مستخدم Microsoft Entra (عنوان بريدك الإلكتروني user@domain عادة) ثم اختر تحديد في أسفل مربع الحوار.
حدد مراجعة + تعيين للانتقال إلى الصفحة النهائية، ثم مراجعة + تعيين مرة أخرى لإكمال العملية.
إرسال رسائل إلى موضوع
في هذا القسم، يمكنك إنشاء مشروع وحدة تحكم Java، وإضافة تعليمة برمجية لإرسال رسائل إلى الموضوع الذي قمت بإنشائه.
إنشاء مشروع وحدة تحكم Java
«Create a Java project» باستخدام Eclipse أو أداة من اختيارك.
تكوين التطبيق لاستخدام "Service Bus"
إضافة مراجع إلى مكتبات Azure Core وAzure Service Bus.
إذا كنت تستخدم Eclipse وأنشأت تطبيق وحدة تحكم Java، فقم بتحويل مشروع Java إلى Maven: انقر بزر الماوس الأيمن فوق المشروع في نافذة Package Explorer ، وحدد Configure ->Convert to Maven project. ثم قم بإضافة تبعيات إلى هاتين المكتبتين كما هو موضح في المثال التالي.
pom.xml
قم بتحديث الملف لإضافة تبعيات إلى حزم ناقل خدمة Azure وAzure Identity.
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-messaging-servicebus</artifactId>
<version>7.13.3</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.8.0</version>
<scope>compile</scope>
</dependency>
</dependencies>
إضافة تعليمات برمجية لإرسال رسائل إلى الموضوع
إضافة عبارات
import
التالية في موضوع ملف Java.import com.azure.messaging.servicebus.*; import com.azure.identity.*; import java.util.concurrent.TimeUnit; import java.util.Arrays; import java.util.List;
في الفئة ، حدد المتغيرات التي يجب الاحتفاظ بها سلسلة الاتصال (غير مطلوبة لسيناريو بدون كلمة مرور) واسم الموضوع واسم الاشتراك.
static String topicName = "<TOPIC NAME>"; static String subName = "<SUBSCRIPTION NAME>";
هام
استبدل
<TOPIC NAME>
باسم الموضوع، واسم<SUBSCRIPTION NAME>
اشتراك الموضوع.إضافة أسلوب المسمى
sendMessage
في الفئة لإرسال رسالة واحدة إلى الموضوع.هام
استبدل
NAMESPACENAME
واستخدم اسم مساحة اسم ناقل خدمة Microsoft Azure بدلاً منه.static void sendMessage() { // create a token using the default Azure credential DefaultAzureCredential credential = new DefaultAzureCredentialBuilder() .build(); ServiceBusSenderClient senderClient = new ServiceBusClientBuilder() .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net") .credential(credential) .sender() .topicName(topicName) .buildClient(); // send one message to the topic senderClient.sendMessage(new ServiceBusMessage("Hello, World!")); System.out.println("Sent a single message to the topic: " + topicName); }
إضافة أسلوب اسمه
createMessages
في الفئة لإنشاء قائمة رسائل. بشكل عام، يمكنك الحصول على هذه الرسائل من أجزاء مختلفة من التطبيق الخاص بك. نقوم هنا بإنشاء قائمة بنماذج الرسائل.static List<ServiceBusMessage> createMessages() { // create a list of messages and return it to the caller ServiceBusMessage[] messages = { new ServiceBusMessage("First message"), new ServiceBusMessage("Second message"), new ServiceBusMessage("Third message") }; return Arrays.asList(messages); }
إضافة أسلوب يسمى أسلوب
sendMessageBatch
لإرسال رسائل إلى الموضوع الذي قمت بإنشائه. ينشئ هذا الأسلوبServiceBusSenderClient
للموضوع، ويستدعي أسلوبcreateMessages
للحصول على قائمة الرسائل، ويحضّر دفعة واحدة أو أكثر، ويرسل الدفعات إلى الموضوع.هام
استبدل
NAMESPACENAME
واستخدم اسم مساحة اسم ناقل خدمة Microsoft Azure بدلاً منه.static void sendMessageBatch() { // create a token using the default Azure credential DefaultAzureCredential credential = new DefaultAzureCredentialBuilder() .build(); ServiceBusSenderClient senderClient = new ServiceBusClientBuilder() .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net") .credential(credential) .sender() .topicName(topicName) .buildClient(); // Creates an ServiceBusMessageBatch where the ServiceBus. ServiceBusMessageBatch messageBatch = senderClient.createMessageBatch(); // create a list of messages List<ServiceBusMessage> listOfMessages = createMessages(); // We try to add as many messages as a batch can fit based on the maximum size and send to Service Bus when // the batch can hold no more messages. Create a new batch for next set of messages and repeat until all // messages are sent. for (ServiceBusMessage message : listOfMessages) { if (messageBatch.tryAddMessage(message)) { continue; } // The batch is full, so we create a new batch and send the batch. senderClient.sendMessages(messageBatch); System.out.println("Sent a batch of messages to the topic: " + topicName); // create a new batch messageBatch = senderClient.createMessageBatch(); // Add that message that we couldn't before. if (!messageBatch.tryAddMessage(message)) { System.err.printf("Message is too large for an empty batch. Skipping. Max size: %s.", messageBatch.getMaxSizeInBytes()); } } if (messageBatch.getCount() > 0) { senderClient.sendMessages(messageBatch); System.out.println("Sent a batch of messages to the topic: " + topicName); } //close the client senderClient.close(); }
تلقي رسائل من اشتراك
في هذا القسم، يمكنك إضافة تعليمة برمجية لاسترداد الرسائل من اشتراك إلى الموضوع.
إضافة أسلوب يسمى
receiveMessages
لتلقي رسائل من الاشتراك. ينشئ هذا الأسلوبServiceBusProcessorClient
للاشتراك عن طريق تحديد معالج لمعالجة الرسائل وآخر لمعالجة الأخطاء. ثم يبدأ المعالج وينتظر بضع ثوانٍ طباعة الرسائل التي يتم تلقيها ثم إيقاف وإغلاق المعالج.هام
- استبدل
NAMESPACENAME
واستخدم اسم مساحة اسم ناقل خدمة Microsoft Azure بدلاً منه. - استبدال
ServiceBusTopicTest
فيServiceBusTopicTest::processMessage
في التعليمات البرمجية باسم الفئة الخاصة بك.
// handles received messages static void receiveMessages() throws InterruptedException { DefaultAzureCredential credential = new DefaultAzureCredentialBuilder() .build(); // Create an instance of the processor through the ServiceBusClientBuilder ServiceBusProcessorClient processorClient = new ServiceBusClientBuilder() .fullyQualifiedNamespace("NAMESPACENAME.servicebus.windows.net") .credential(credential) .processor() .topicName(topicName) .subscriptionName(subName) .processMessage(context -> processMessage(context)) .processError(context -> processError(context)) .buildProcessorClient(); System.out.println("Starting the processor"); processorClient.start(); TimeUnit.SECONDS.sleep(10); System.out.println("Stopping and closing the processor"); processorClient.close(); }
- استبدل
قم بإضافة أسلوب
processMessage
لمعالجة رسالة تم تلقيها من اشتراك Service Bus.private static void processMessage(ServiceBusReceivedMessageContext context) { ServiceBusReceivedMessage message = context.getMessage(); System.out.printf("Processing message. Session: %s, Sequence #: %s. Contents: %s%n", message.getMessageId(), message.getSequenceNumber(), message.getBody()); }
قم بإضافة أسلوب
processError
لمعالجة رسائل الخطأ.private static void processError(ServiceBusErrorContext context) { System.out.printf("Error when receiving messages from namespace: '%s'. Entity: '%s'%n", context.getFullyQualifiedNamespace(), context.getEntityPath()); if (!(context.getException() instanceof ServiceBusException)) { System.out.printf("Non-ServiceBusException occurred: %s%n", context.getException()); return; } ServiceBusException exception = (ServiceBusException) context.getException(); ServiceBusFailureReason reason = exception.getReason(); if (reason == ServiceBusFailureReason.MESSAGING_ENTITY_DISABLED || reason == ServiceBusFailureReason.MESSAGING_ENTITY_NOT_FOUND || reason == ServiceBusFailureReason.UNAUTHORIZED) { System.out.printf("An unrecoverable error occurred. Stopping processing with reason %s: %s%n", reason, exception.getMessage()); } else if (reason == ServiceBusFailureReason.MESSAGE_LOCK_LOST) { System.out.printf("Message lock lost for message: %s%n", context.getException()); } else if (reason == ServiceBusFailureReason.SERVICE_BUSY) { try { // Choosing an arbitrary amount of time to wait until trying again. TimeUnit.SECONDS.sleep(1); } catch (InterruptedException e) { System.err.println("Unable to sleep for period of time"); } } else { System.out.printf("Error source %s, reason %s, message: %s%n", context.getErrorSource(), reason, context.getException()); } }
تحديث أسلوب
main
لاستدعاء أساليبsendMessage
وsendMessageBatch
وreceiveMessages
ثم لإرجاعInterruptedException
.public static void main(String[] args) throws InterruptedException { sendMessage(); sendMessageBatch(); receiveMessages(); }
تشغيل التطبيق
تشغيل البرنامج لمشاهدة الإخراج مشابهة الإخراج التالي:
إذا كنت تستخدم Eclipse، فانقر بزر الماوس الأيمن فوق المشروع، وحدد تصدير، وقم بتوسيع Java، وحدد Runnable JAR file، واتبع الخطوات لإنشاء ملف JAR قابل للتشغيل.
إذا قمت بتسجيل الدخول إلى الجهاز باستخدام حساب مستخدم يختلف عن حساب المستخدم المضاف إلى دور مالك البيانات ناقل خدمة Azure، فاتبع هذه الخطوات. وإلا، فتخط هذه الخطوة وانتقل إلى تشغيل ملف Jar في الخطوة التالية.
تثبيت Azure CLI على جهازك.
قم بتشغيل أمر CLI التالي لتسجيل الدخول إلى Azure. استخدم حساب المستخدم نفسه الذي أضفته إلى دور مالك بيانات ناقل خدمة Azure.
az login
قم بتشغيل ملف Jar باستخدام الأمر التالي.
java -jar <JAR FILE NAME>
ترى الإخراج التالي في نافذة وحدة التحكم.
Sent a single message to the topic: mytopic Sent a batch of messages to the topic: mytopic Starting the processor Processing message. Session: e0102f5fbaf646988a2f4b65f7d32385, Sequence #: 1. Contents: Hello, World! Processing message. Session: 3e991e232ca248f2bc332caa8034bed9, Sequence #: 2. Contents: First message Processing message. Session: 56d3a9ea7df446f8a2944ee72cca4ea0, Sequence #: 3. Contents: Second message Processing message. Session: 7bd3bd3e966a40ebbc9b29b082da14bb, Sequence #: 4. Contents: Third message
في الصفحة Overview لمساحة اسم حافلة الخدمة في مدخل Microsoft Azure، يمكنك مشاهدة عدد الرسائل الوارد والصادر. انتظر دقيقة أو نحو ذلك ثم قم بتحديث الصفحة لمشاهدة أحدث القيم.
قم بالتبديل إلى علامة التبويب Topics في الجزء السفلي الأوسط، وحدد الموضوع لترى صفحة موضوع ناقل خدمة Microsoft Azure للموضوع الخاص بك. في هذه الصفحة، يجب أن تشاهد أربع رسائل واردة وأربع رسائل صادرة في المخطط Messages.
إذا قمت بالتعليق على receiveMessages
استدعاء في أسلوب main
وتشغيل التطبيق مرة أخرى، في الصفحة موضوع ناقل خدمة Microsoft Azure، سترى 8 رسائل واردة (4 رسائل جديدة) ولكن أربع رسائل صادرة.
في هذه الصفحة، إذا حددت اشتراكاً، فستصل إلى صفحة اشتراك Service Bus. يمكنك رؤية عدد الرسائل النشطة وعدد الرسائل المهملة والمزيد في هذه الصفحة. في هذا المثال، هناك أربع رسائل نشطة لم يتلقها المتلقي بعد.
الخطوات التالية
راجع الوثائق والعينات التالية: