Web PubSub client-side SDK ل JavaScript

إشعار

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

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

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

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

هام

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

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

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

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

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

• إصدارات "LTS" من "Node.js".
• اشتراك Azure
• مورد Web PubSub

1. تثبيت الحزمة @azure/web-pubsub-client

npm install @azure/web-pubsub-client

2. الاتصال بمورد Web PubSub

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

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

// Imports the client library
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. الانضمام إلى المجموعات

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

// ...continues the code snippet from above

// Specifies the group to join
let groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. إرسال رسائل إلى مجموعة

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

الأمثلة

معالجة connectedالأحداث disconnected و stopped

يطلق Azure Web PubSub أحداث النظام مثل connectedوdisconnected.stopped يمكنك تسجيل معالجات الأحداث لتحديد ما يجب أن يفعله البرنامج عند تشغيل الأحداث.

1. عند اتصال عميل بنجاح بمورد Web PubSub الخاص بك، connected يتم تشغيل الحدث. تقوم هذه القصاصة البرمجية ببساطة بطباعة معرف الاتصال

client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});

2. عندما يتم قطع اتصال عميل ويفشل في استرداد الاتصال، disconnected يتم تشغيل الحدث. تطبع هذه القصاصة البرمجية الرسالة ببساطة.

client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});

3. stopped يتم تشغيل الحدث عند قطع اتصال العميل ويتوقف العميل عن محاولة إعادة الاتصال. يحدث هذا عادة بعد client.stop() استدعاء، أو autoReconnect معطل أو تم الوصول إلى حد محدد لمحاولة إعادة الاتصال. إذا كنت ترغب في إعادة تشغيل العميل، يمكنك الاتصال client.start() في الحدث المتوقف.

// Registers an event handler for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

استخدام خادم تطبيق لإنشاء Client Access URL برمجيا

في الإنتاج، يجلب العملاء عادة Client Access URL من خادم التطبيق. يحتفظ الخادم بمورد connection string Web PubSub الخاص بك وينشئ Client Access URL بمساعدة من المكتبة @azure/web-pubsubمن جانب الخادم .

1. خادم التطبيق

مقتطف التعليمات /negotiate البرمجية هو مثال على خادم تطبيق يعرض نقطة نهاية ويعيد Client Access URL.

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

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  let token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. جانب العميل

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    let value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

إشعار

لمشاهدة التعليمات البرمجية الكاملة لهذه العينة، يرجى الرجوع إلى samples-browser.

---

يستهلك العميل رسائل من خادم التطبيق أو المجموعات المنضمة

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

// Registers a listener for the "server-message". The callback is invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback is invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

إشعار

بالنسبة للحدث group-message ، يمكن للعميل تلقي رسائل من المجموعات التي انضم إليها فقط .

معالجة فشل إعادة الانضمام

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

ومع ذلك، يجب أن تكون على دراية autoRejoinGroupبالقيود.

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

// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

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

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

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

حزمة JavaScript

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

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

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

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

export AZURE_LOG_LEVEL=verbose

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

تتبع مباشر

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