الكيانات الداخلية لخدمة Azure Web PubSub

توفر خدمة Azure Web PubSub طريقة سهلة لنشر/ الاشتراك في الرسائل باستخدام اتصالات WebSocket البسيطة.

• يمكن كتابة العملاء بأي لغة تحتوي على دعم WebSocket.
• يتم دعم كل من الرسائل النصية والثنائية داخل اتصال واحد.
• بروتوكول بسيط يسمح للعملاء بنشر التدليك مباشرة إلى بعضها البعض.
• تدير الخدمة اتصالات WebSocket نيابة عنك.

الشروط

• الخدمة: خدمة Azure Web PubSub.

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

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

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

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

• الرسالة: عندما يكون العميل متصلاً، يمكنه إرسال رسائل إلى التطبيق الرئيسي، أو تلقي رسائل من التطبيق الرئيسي، من خلال اتصال WebSocket. يمكن أن تكون الرسائل بتنسيق نص عادي أو ثنائي أو JSON ويكون الحد الأقصى لحجمها 1 ميغابايت.

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

• معالج الأحداث: يحتوي معالج الأحداث على المنطق لمعالجة أحداث العميل. تسجيل وتكوين معالجات الأحداث في الخدمة من خلال المدخل أو Azure CLI مسبقا. يتم وصف التفاصيل في قسم معالج الأحداث.

• Event Listener(preview): يستمع مستمع الحدث فقط إلى أحداث العميل ولكن لا يمكنه التدخل في عمر عملائك من خلال استجابتهم. يتم وصف التفاصيل في قسم مستمع الأحداث.

• الخادم: يمكن للخادم معالجة أحداث العميل أو إدارة اتصالات العميل أو نشر الرسائل إلى المجموعات. يعتبر كل من معالج الأحداث ومستمع الحدث من جانب الخادم. يتم وصف تفاصيل حول الخادم في قسم بروتوكول الخادم.

‏‏سير العمل‬

سير العمل كما هو موضح في الرسم البياني أعلاه:

1. يتصل العميل بنقطة نهاية الخدمة /client باستخدام نقل WebSocket. تقوم الخدمة بإعادة توجيه كل إطار WebSocket إلى المصدر المكون (الخادم) بشكل افتراضي، يمكن لاتصال WebSocket الاتصال بأي بروتوكول فرعي مخصص للخادم للتعامل معه. بدلا من ذلك، يمكن للعميل الاتصال بالوضع sendToGroup وإرسال كل إطار WebSocket إلى مجموعة معينة. يمكن للعميل أيضا الاتصال مع البروتوكولات الفرعية المدعومة بالخدمة، والتي توفر ميزات مثل إرسال الأحداث إلى المصدر والانضمام إلى المجموعات وإرسال الرسائل مباشرة إلى المجموعات. يتم وصف التفاصيل في بروتوكول العميل.
2. في أحداث العميل المختلفة، تستدعي الخدمة الخادم باستخدام بروتوكول CloudEvents. CloudEvents هو تعريف موحد وغير محدد للبروتوكول للبنية ووصف بيانات التعريف للأحداث التي تستضيفها Cloud Native Computing Foundation (CNCF). يعتمد التنفيذ التفصيلي لبروتوكول CloudEvents على دور الخادم، الموضح في بروتوكول الخادم.
3. يمكن لخادم Web PubSub استدعاء الخدمة باستخدام واجهة برمجة تطبيقات REST لإرسال رسائل إلى العملاء أو لإدارة العملاء المتصلين. يتم وصف التفاصيل في بروتوكول الخادم

بروتوكول العميل

يتصل اتصال العميل بنقطة /client نهاية الخدمة باستخدام بروتوكول WebSocket. يوفر بروتوكول WebSocket قنوات اتصال مزدوجة بالكامل عبر اتصال TCP واحد وتم توحيده بواسطة IETF ك RFC 6455 في عام 2011. تتمتع معظم اللغات بدعم أصلي لبدء اتصالات WebSocket.

تدعم خدمتنا نوعين من العملاء:

• واحد يسمى عميل WebSocket البسيط
• والآخر يسمى عميل PubSub WebSocket

عميل WebSocket البسيط

عميل WebSocket بسيط، كما تشير التسمية، هو اتصال WebSocket بسيط. يمكن أن يكون لها أيضا البروتوكول الفرعي المخصص الخاص بها.

على سبيل المثال، في JS، يمكن إنشاء عميل WebSocket بسيط باستخدام التعليمات البرمجية التالية.

// simple WebSocket client1
var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "custom.subprotocol"
);

يحتوي عميل WebSocket البسيط على وضعين. يتبع الوضع الافتراضي الخاص sendEvent به بنية خادم العميل<>، كما يظهر الرسم التخطيطي للتسلسل أدناه:

1. عندما يبدأ العميل تأكيد اتصال WebSocket، تحاول الخدمة استدعاء connect معالج الأحداث لمصافحة WebSocket. يمكن للمطورين استخدام هذا المعالج لمعالجة تأكيد اتصال WebSocket، وتحديد البروتوكول الفرعي لاستخدامه، ومصادقة العميل، وضم العميل إلى المجموعات.
2. عند اتصال العميل بنجاح، تستدعي connected الخدمة معالج أحداث. يعمل كإشعار ولا يمنع العميل من إرسال الرسائل. يمكن للمطورين استخدام هذا المعالج للقيام بتخزين البيانات ويمكنهم الاستجابة برسائل إلى العميل. تدفع الخدمة أيضا حدثا connected إلى كل ما يتعلق بمستمعي الأحداث، إن وجد.
3. عندما يرسل العميل رسائل، تقوم الخدمة بتشغيل message حدث إلى معالج الأحداث. يحتوي هذا الحدث على الرسائل المرسلة في إطار WebSocket. تحتاج التعليمات البرمجية الخاصة بك إلى إرسال الرسائل داخل معالج الأحداث هذا. إذا أرجع معالج الأحداث رمز استجابة nonsuccessful، فإن الخدمة تسقط اتصال العميل. تدفع الخدمة أيضا حدثا message إلى جميع مستمعي الأحداث المعنيين، إن وجد. إذا لم تتمكن الخدمة من العثور على أي خوادم مسجلة لتلقي الرسائل، فإن الخدمة تسقط أيضا اتصال العميل.
4. عند قطع اتصال العميل، تحاول الخدمة تشغيل disconnected الحدث إلى معالج الأحداث بمجرد اكتشاف قطع الاتصال. تدفع الخدمة أيضا حدثا disconnected إلى كل ما يتعلق بمستمعي الأحداث، إن وجد.

السيناريوهات

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

عميل PubSub WebSocket

تدعم الخدمة أيضا البروتوكول الفرعي المحدد المسمى json.webpubsub.azure.v1، والذي يمكن العملاء من النشر/ الاشتراك مباشرة بدلا من القيام برحلة ذهابا وإيابا إلى الخادم المصدر. نستدعي اتصال WebSocket مع json.webpubsub.azure.v1 البروتوكول الفرعي عميل PubSub WebSocket. لمزيد من المعلومات، راجع مواصفات عميل Web PubSub على GitHub.

على سبيل المثال، في JS، يمكن إنشاء عميل PubSub WebSocket باستخدام التعليمات البرمجية التالية.

// PubSub WebSocket client
var pubsub = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);

يمكن لعميل PubSub WebSocket:

• انضم إلى مجموعة، على سبيل المثال:

  {
    "type": "joinGroup",
    "group": "<group_name>"
  }
  

• اترك مجموعة، على سبيل المثال:

  {
    "type": "leaveGroup",
    "group": "<group_name>"
  }
  

• نشر الرسائل إلى مجموعة، على سبيل المثال:

  {
    "type": "sendToGroup",
    "group": "<group_name>",
    "data": { "hello": "world" }
  }
  

• إرسال أحداث مخصصة إلى الخادم المصدر، على سبيل المثال:

  {
    "type": "event",
    "event": "<event_name>",
    "data": { "hello": "world" }
  }
  

يحتوي PubSub WebSocket Subprotocol على تفاصيل json.webpubsub.azure.v1 البروتوكول الفرعي.

في وضع sendEventdafult لعميل WebSocket البسيط، يجب أن يكون للخادم دور لتلقي message الأحداث من العملاء. يؤدي اتصال WebSocket البسيط في sendEvent الوضع دائما إلى تشغيل message حدث عند إرسال الرسائل، ويعتمد دائما على جانب الخادم لمعالجة الرسائل والقيام بعمليات أخرى. لا sendToGroup يمكن الوضع إلا العملاء من نشر الرسائل إلى المجموعات مباشرة دون تشغيل الطلبات إلى الخادم، والذي لا يزال محدودا. json.webpubsub.azure.v1 يمكن البروتوكول الفرعي العملاء من القيام بالمزيد دون تشغيل الطلبات إلى الخادم. بمساعدة ذلك، يمكن للعميل المعتمد الانضمام إلى مجموعة ونشر الرسائل إلى مجموعة مباشرة. يمكنه أيضا توجيه الرسائل إلى معالجات أحداث / مستمعات أحداث مختلفة عن طريق تخصيص الحدث الذي تنتمي إليه الرسالة.

السيناريوهات

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

Client1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Client2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

كما يوضح المثال أعلاه، client2 يرسل البيانات مباشرة إلى client1 عن طريق نشر الرسائل Group1 التي client1 يوجد فيها.

ملخص أحداث العميل

تندرج أحداث العميل في فئتين:

• تمنع الأحداث المتزامنة (حظر) الأحداث المتزامنة سير عمل العميل.

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

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

  • connected: يتم تشغيل هذا الحدث عندما يتصل عميل بالخدمة بنجاح.
  • disconnected: يتم تشغيل هذا الحدث عند قطع اتصال عميل بالخدمة.

حد رسالة العميل

الحد الأقصى المسموح به لحجم الرسالة لإطار WebSocket واحد هو 1 ميغابايت.

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

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

يستخدم العميل رمز JWT مميز موقع للاتصال بالخدمة. يمكن أن يرفض المصدر أيضا العميل عندما يكون connect معالج الأحداث للعميل الوارد. يقوم معالج الأحداث بمصادقة العميل عن طريق تحديد userId و roles لدى العميل في استجابة webhook، أو رفض العميل مع 401. يصفه قسم معالج الأحداث بالتفصيل.

يصف الرسم البياني التالي سير العمل.

يمكن للعميل النشر إلى عملاء آخرين فقط عندما يكون مصرحا له بذلك. roleيحدد s للعميل الأذونات الأولية التي يمتلكها العميل:

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

بروتوكول الخادم

يوفر بروتوكول الخادم وظائف الخادم لمعالجة أحداث العميل وإدارة اتصالات العميل والمجموعات.

بشكل عام، يحتوي بروتوكول الخادم على ثلاثة أدوار:

1. معالج الأحداث
2. إدارة الاتصال
3. مستمع الحدث

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

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

تقدم خدمة Web PubSub أحداث العميل إلى خطاف الويب المصدر باستخدام بروتوكول CloudEvents HTTP.

لكل حدث، تقوم الخدمة بصياغة طلب HTTP POST إلى المصدر المسجل وتتوقع استجابة HTTP.

دائما ما تكون البيانات المرسلة من الخدمة إلى الخادم بتنسيق CloudEvents binary .

المصدر والتحقق من الصحة

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

يمكن أن يستخدم {event} عنوان URL المعلمة لتعريف قالب URL لمعالج webhook. تحسب الخدمة قيمة عنوان URL لخطاف الويب ديناميكيا عند ورود طلب العميل. على سبيل المثال، عندما يأتي طلب /client/hubs/chat ، مع نمط http://host.com/api/{event} URL لمعالج الأحداث المكون للمركز chat، عندما يتصل العميل، فإنه سيتم أولا POST إلى عنوان URL هذا: http://host.com/api/connect. يمكن أن يكون هذا السلوك مفيدا عندما يرسل عميل PubSub WebSocket أحداثا مخصصة، حيث يساعد معالج الأحداث في إرسال أحداث مختلفة إلى مصدر مختلف. {event} المعلمة غير مسموح بها في اسم مجال URL.

عند إعداد معالج الأحداث المصدر من خلال مدخل Microsoft Azure أو CLI، تتبع الخدمة حماية إساءة استخدام CloudEvents للتحقق من صحة خطاف الويب المصدر. WebHook-Request-Origin يتم تعيين عنوان الطلب إلى اسم xxx.webpubsub.azure.comمجال الخدمة ، ويتوقع أن تحتوي الاستجابة على عنوان WebHook-Allowed-Origin اسم المجال هذا.

عند إجراء التحقق من الصحة، يتم حل المعلمة {event} إلى validate. على سبيل المثال، عند محاولة تعيين عنوان URL إلى http://host.com/api/{event}، تحاول الخدمة خيارات طلب إلى http://host.com/api/validate وعندما تكون الاستجابة صالحة فقط، يمكن تعيين التكوين بنجاح.

في الوقت الحالي، لا ندعم WebHook-Request-Rate وWebHook-Request-Callback.

المصادقة/التخويل بين الخدمة والإخطار على الويب

لإنشاء مصادقة وتخويل آمنين بين خدمتك وخطاف الويب، ضع في اعتبارك الخيارات والخطوات التالية:

• الوضع المجهول
• مصادقة code بسيطة يتم توفيرها من خلال عنوان URL الخاص ب Webhook المكون.
• استخدم تخويل Microsoft Entra. لمزيد من المعلومات، راجع كيفية استخدام الهوية المدارة للحصول على التفاصيل.

1. تمكين الهوية لخدمة Web PubSub.
2. حدد من تطبيق Microsoft Entra الموجود الذي يرمز إلى تطبيق الويب webhook الخاص بك.

إدارة الاتصال

الخادم هو بطبيعة الأمر مستخدم معتمد. بمساعدة دور معالج الأحداث، يعرف الخادم بيانات تعريف العملاء، على سبيل المثال، وuserId، connectionId حتى يتمكن من:

• إغلاق اتصال العميل
• إرسال رسائل إلى عميل
• إرسال رسائل إلى العملاء الذين ينتمون إلى نفس المستخدم
• إضافة عميل إلى مجموعة
• إضافة عملاء تمت مصادقته كمستخدم واحد إلى مجموعة
• إزالة عميل من مجموعة
• إزالة العملاء المصادق عليهم كمستخدم واحد من مجموعة
• نشر الرسائل إلى إحدى المجموعات

يمكنه أيضا منح أذونات النشر/الانضمام لعميل PubSub أو إبطالها:

• منح أذونات النشر/الانضمام إلى مجموعة معينة أو لجميع المجموعات
• إبطال أذونات النشر/الانضمام لبعض المجموعات المحددة أو لكافة المجموعات
• تحقق مما إذا كان لدى العميل إذن للانضمام إلى مجموعة معينة أو إلى كافة المجموعات أو نشرها

توفر الخدمة واجهات برمجة تطبيقات REST للخادم للقيام بإدارة الاتصال.

يتم تعريف بروتوكول REST API التفصيلي هنا.

مستمع الحدث

يستمع مستمع الحدث إلى أحداث العميل الواردة. يحتوي كل مستمع حدث على عامل تصفية لتحديد أنواع الأحداث التي يتعلق بها، ونقطة نهاية حول مكان إرسال الأحداث إليها.

حاليا نحن ندعم مراكز الأحداث كنقطة نهاية وحدة استماع الحدث.

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

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

يمكنك دمج معالج الأحداث ومستمعي الأحداث لنفس الحدث. في هذه الحالة، يتلقى كل من معالج الأحداث ومستمعي الأحداث الحدث.

تقدم خدمة Web PubSub أحداث العميل إلى مستمعي الأحداث باستخدام ملحق CloudEvents AMQP ل Azure Web PubSub.

الملخص

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

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

استخدم هذه الموارد لبدء إنشاء التطبيق الخاص بك: