مكتبة عميل Azure WebPubSub ل Java

إشعار

يتم وصف تفاصيل حول المصطلحات المستخدمة هنا في مقالة المفاهيم الرئيسية.

تهدف SDK من جانب العميل إلى تسريع سير عمل المطور؛ بشكل أكثر تحديدا،

• يبسط إدارة اتصالات العميل
• يبسط إرسال الرسائل بين العملاء
• إعادة المحاولة تلقائيا بعد قطرات غير مقصودة من اتصال العميل
• تسليم الرسائل بشكل موثوق بالرقم وبالترتيب بعد التعافي من انخفاض الاتصال

كما هو موضح في الرسم التخطيطي، يقوم عملاؤك بإنشاء اتصالات WebSocket مع مورد Web PubSub.

هام

تظهر سلسلة الاتصال الأولية في هذه المقالة لأغراض العرض التوضيحي فقط.

سلسلة اتصال تتضمن معلومات التخويل المطلوبة لتطبيقك للوصول إلى خدمة Azure Web PubSub. مفتاح الوصول داخل سلسلة الاتصال يشبه كلمة مرور الجذر للخدمة الخاصة بك. في بيئات الإنتاج، قم دائما بحماية مفاتيح الوصول الخاصة بك. استخدم Azure Key Vault لإدارة مفاتيحك وتدويرها بأمان وتأمين اتصالك ب WebPubSubServiceClient.

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

الشروع في العمل

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

• Java Development Kit (SDK) الإصدار 8 أو أعلى.
• اشتراك Azure
• مثيل Web PubSub موجود

إضافة الحزمة إلى منتجك

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub-client</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

مصادقة العميل

يستخدم Client Access URL العميل للاتصال والمصادقة مع الخدمة. يتبع عنوان URL نمطا من wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. هناك طرق متعددة للحصول على Client Access URL. كبداية سريعة، يمكنك النسخ واللصق من مدخل Microsoft Azure، وللإنتاج، تحتاج عادة إلى خادم تفاوض لإنشاء عنوان URL. راجع التفاصيل.

الاستخدام Client Access URL من مدخل Microsoft Azure

كبداية سريعة، يمكنك الانتقال إلى مدخل Microsoft Azure ونسخ عنوان URL الخاص ب Client Access من شفرة Keys.

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

WebPubSubClient client = new WebPubSubClientBuilder()
    .clientAccessUrl("<client-access-url>")
    .buildClient();

استخدام خادم التفاوض لإنشاء Client Access URL

في الإنتاج، عادة ما يجلب Client Access URL العميل من خادم التفاوض. يحتفظ connection string الخادم وينشئ من Client Access URL خلال WebPubSubServiceClient. كنموذج، توضح القصاصة البرمجية فقط كيفية إنشاء Client Access URL داخل عملية واحدة.

تظهر سلسلة الاتصال الأولية في هذه المقالة لأغراض العرض التوضيحي فقط. في بيئات الإنتاج، قم دائما بحماية مفاتيح الوصول الخاصة بك. استخدم Azure Key Vault لإدارة مفاتيحك وتدويرها بأمان وتأمين اتصالك ب WebPubSubServiceClient.

// WebPubSubServiceAsyncClient is from com.azure:azure-messaging-webpubsub
// create WebPubSub service client
WebPubSubServiceAsyncClient serverClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("<hub>>")
    .buildAsyncClient();

// wrap WebPubSubServiceAsyncClient.getClientAccessToken as WebPubSubClientCredential
WebPubSubClientCredential clientCredential = new WebPubSubClientCredential(Mono.defer(() ->
    serverClient.getClientAccessToken(new GetClientAccessTokenOptions()
            .setUserId("<user-name>")
            .addRole("webpubsub.joinLeaveGroup")
            .addRole("webpubsub.sendToGroup"))
        .map(WebPubSubClientAccessToken::getUrl)));

// create WebPubSub client
WebPubSubClient client = new WebPubSubClientBuilder()
    .credential(clientCredential)
    .buildClient();

ميزات للتمييز WebPubSubClient و WebPubSubServiceClient.

اسم الفئة	WebPubSubClient	WebPubSubServiceClient
اسم الحزمة	azure-messaging-webpubsub-client	azure-messaging-webpubsub
الميزات	يستخدم على جانب العميل. نشر الرسائل والاشتراك في الرسائل.	يستخدم على جانب الخادم. إنشاء Client Access URL العملاء وإدارتهم.

الأمثلة

استهلاك الرسائل من الخادم والمجموعات

يمكن للعميل إضافة عمليات رد اتصال لاستهلاك الرسائل من الخادم والمجموعات. ملاحظة، يمكن للعملاء تلقي رسائل المجموعة التي انضم إليها فقط.

client.addOnGroupMessageEventHandler(event -> {
    System.out.println("Received group message from " + event.getFromUserId() + ": "
        + event.getData().toString());
});
client.addOnServerMessageEventHandler(event -> {
    System.out.println("Received server message: "
        + event.getData().toString());
});

إضافة عمليات رد اتصال للأحداث connecteddisconnectedو و stopped

عند توصيل اتصال عميل بالخدمة، connected يتم تشغيل الحدث.

عند قطع اتصال عميل وفشل الاسترداد، disconnected يتم تشغيل الحدث.

عند إيقاف عميل، مما يعني أن اتصال العميل غير متصل ويتوقف العميل عن محاولة إعادة الاتصال، stopped يتم تشغيل الحدث. يحدث هذا عادة بعد client.StopAsync() استدعاء أو تعطيل AutoReconnect. إذا كنت ترغب في إعادة تشغيل العميل، يمكنك الاتصال client.StartAsync() في Stopped الحدث.

client.addOnConnectedEventHandler(event -> {
    System.out.println("Connection is connected: " + event.getConnectionId());
});
client.addOnDisconnectedEventHandler(event -> {
    System.out.println("Connection is disconnected");
});
client.addOnStoppedEventHandler(event -> {
    System.out.println("Client is stopped");
});

العملية وإعادة المحاولة

بشكل افتراضي، تحتوي العملية مثل client.joinGroup()، client.leaveGroup()، client.sendToGroup()، client.sendEvent() على ثلاث reات. يمكنك استخدام WebPubSubClientBuilder.retryOptions() للتغيير. إذا فشلت جميع عمليات إعادة المحاولة، يتم طرح خطأ. يمكنك الاستمرار في إعادة المحاولة عن طريق تمرير نفس ackId عمليات إعادة المحاولة السابقة، وبالتالي يمكن أن تساعد الخدمة في إلغاء تكرار العملية بنفس ackId.

try {
    client.joinGroup("testGroup");
} catch (SendMessageFailedException e) {
    if (e.getAckId() != null) {
        client.joinGroup("testGroup", e.getAckId());
    }
}

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

تمكين السجلات

يمكنك تعيين متغير البيئة التالي للحصول على سجلات تتبع الأخطاء عند استخدام هذه المكتبة.

export AZURE_LOG_LEVEL=verbose

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

تتبع مباشر

استخدم أداة Live Trace من مدخل Microsoft Azure لفحص حركة مرور الرسائل المباشرة من خلال مورد Web PubSub.