معالجات Azure Web PubSub CloudEvents ل Express

خدمة Azure Web PubSub هي خدمة مدارة من Azure تساعد المطورين على إنشاء تطبيقات الويب بسهولة باستخدام ميزات في الوقت الحقيقي ونمط النشر والاشتراك. يمكن لأي سيناريو يتطلب مراسلة النشر والاشتراك في الوقت الحقيقي بين الخادم والعملاء أو بين العملاء استخدام خدمة Azure Web PubSub. يمكن أيضا للميزات التقليدية في الوقت الحقيقي التي تتطلب الاستقصاء من الخادم أو إرسال طلبات HTTP استخدام خدمة Azure Web PubSub.

عند اتصال WebSocket، تحول خدمة Web PubSub دورة حياة الاتصال والرسائل إلى أحداث بتنسيق CloudEvents. توفر هذه المكتبة برنامج وسيط سريع للتعامل مع الأحداث التي تمثل دورة حياة اتصال WebSocket ورسائله، كما هو موضح في الرسم التخطيطي أدناه:

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

التعليمات البرمجية | المصدرالحزمة (NPM) | الوثائق | المرجعية لواجهة برمجة التطبيقاتوثائق | المنتجعينات

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

البيئات المعتمدة حاليًا

• إصدارات "LTS" من "Node.js".
• الإصدار السريع 4.x.x أو أعلى

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

• اشتراك Azure.
• نقطة نهاية Azure Web PubSub موجودة.

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

npm install @azure/web-pubsub-express

2. إنشاء WebPubSubEventHandler

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

المفاهيم الرئيسية

اتصال

يمثل الاتصال، المعروف أيضا باسم عميل أو اتصال عميل، اتصال WebSocket فرديا متصلا بخدمة Web PubSub. عند الاتصال بنجاح، يُعين معرف اتصال فريد لهذا الاتصال بواسطة خدمة Web PubSub.

المركز

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

التجميع

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

المستخدم

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

أحداث العميل

يتم إنشاء الأحداث أثناء دورة حياة اتصال العميل. على سبيل المثال، ينشئ اتصال عميل WebSocket البسيط حدثا connect عندما يحاول الاتصال بالخدمة، connected وحدثا عندما يتصل بنجاح بالخدمة، وحدثا message عندما يرسل رسائل إلى الخدمة وحدثا disconnected عند قطع اتصاله بالخدمة.

معالج الأحداث

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

أمثلة

معالجة الطلب وتعيينه connect<userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>"
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

السماح فقط بنقاط النهاية المحددة

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com"
  ]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

تعيين مسار معالج الأحداث المخصص

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "customPath1"
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

تعيين حالة الاتصال وقراءتها

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  }
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

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

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

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

• الحصول على سجلات تتبع الأخطاء من مكتبة عميل SignalR

export AZURE_LOG_LEVEL=verbose

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

التتبع المباشر

استخدم Live Trace من مدخل خدمة Web PubSub لعرض نسبة استخدام الشبكة المباشرة.

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

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

المساهمة

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

المشاريع ذات الصلة

• Microsoft Azure SDK ل Javascript