بروتوكولات عميل WebSocket ل Azure Web PubSub

يتصل العملاء ب Azure Web PubSub باستخدام بروتوكول WebSocket القياسي.

نقاط نهاية الخدمة

توفر خدمة Web PubSub نوعين من نقاط النهاية للعملاء للاتصال ب:

• /client/hubs/{hub}
• /client/?hub={hub}

{hub} هي معلمة إلزامية تعمل كعزل للتطبيقات المختلفة. يمكنك تعيينه إما في المسار أو الاستعلام.

التصريح

يتصل العملاء بالخدمة باستخدام JSON Web Token (JWT). يمكن أن يكون الرمز المميز إما في سلسلة الاستعلام، ك /client/?hub={hub}&access_token={token}، أو Authorization العنوان، ك Authorization: Bearer {token}.

فيما يلي سير عمل تخويل عام:

1. يتفاوض العميل مع خادم التطبيق الخاص بك. يحتوي خادم التطبيق على البرنامج الوسيط للتخويل، والذي يعالج طلب العميل ويوقع JWT للعميل للاتصال بالخدمة.
2. يقوم خادم التطبيق بإرجاع JWT وعنوان URL للخدمة إلى العميل.
3. يحاول العميل الاتصال بخدمة Web PubSub باستخدام عنوان URL ورمز JWT المميز الذي تم إرجاعه من خادم التطبيق.

المطالبات المدعومة

يمكنك أيضا تكوين خصائص اتصال العميل عند إنشاء رمز الوصول عن طريق تحديد مطالبات خاصة داخل رمز JWT المميز:

‏‏الوصف	نوع المطالبة	قيمة المطالبة	ملاحظات
userId لاتصال العميل	sub	معرف المستخدم	يسمح بمطالبة واحدة sub فقط.
مدة بقاء الرمز المميز	exp	وقت انتهاء الصلاحية	exp تحدد المطالبة (وقت انتهاء الصلاحية) وقت انتهاء الصلاحية في أو بعد ذلك يجب عدم قبول الرمز المميز للمعالجة.
الأذونات التي يمتلكها اتصال العميل في البداية	role	قيمة الدور المعرفة في الأذونات	حدد مطالبات متعددة role إذا كان لدى العميل أذونات متعددة.
المجموعات الأولية التي ينضم إليها اتصال العميل بمجرد اتصاله ب Azure Web PubSub	group	المجموعة المراد الانضمام إليها	حدد مطالبات متعددة group إذا انضم العميل إلى مجموعات متعددة.

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

توفر SDKs للخادم واجهات برمجة التطبيقات لإنشاء رمز الوصول المميز للعملاء.

عميل WebSocket البسيط

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

على سبيل المثال، في JavaScript، يمكنك إنشاء عميل 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')

عميل PubSub WebSocket

عميل PubSub WebSocket هو عميل WebSocket باستخدام البروتوكولات الفرعية المحددة بواسطة خدمة Azure Web PubSub:

• json.webpubsub.azure.v1
• protobuf.webpubsub.azure.v1

باستخدام البروتوكول الفرعي المدعوم بالخدمة، يمكن لعميلPubSub WebSocket نشر الرسائل مباشرة إلى المجموعات عندما يكون لديهم الأذونات.

json.webpubsub.azure.v1 البروتوكول الفرعي

تحقق هنا من البروتوكول الفرعي JSON بالتفصيل.

إنشاء عميل PubSub WebSocket

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

الانضمام إلى مجموعة من العميل مباشرة

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

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

let ackId = 0;
pubsubClient.send(    
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

protobuf.webpubsub.azure.v1 البروتوكول الفرعي

تعد المخازن المؤقتة للبروتوكول (protobuf) بروتوكولا محايدا للغة ومحايدا للنظام الأساسي ومستندا إلى ثنائي يبسط إرسال البيانات الثنائية. يوفر Protobuf أدوات لإنشاء عملاء للعديد من اللغات، مثل Java وPython و Objective-C و C# و C++. تعرف على المزيد حول protobuf.

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

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

تحقق هنا من البروتوكول الفرعي protobuf بالتفصيل.

استجابة AckId وAck

يدعم عميل PubSub WebSocket خاصية للرسائل joinGroupleaveGroupsendToGroup و و.eventackId عند استخدام ackId، يمكنك تلقي رسالة استجابة ack عند معالجة طلبك. يمكنك اختيار حذف ackId في سيناريوهات fire-and-forget. في المقالة، نصف اختلافات السلوك بين تحديد ackId أم لا.

السلوك عند عدم ackId تحديد

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

السلوك عند ackId تحديده

نشر مكرر

ackId هو رقم uint64 ويجب أن يكون فريدا داخل عميل بنفس معرف الاتصال. تسجل ackId خدمة Web PubSub و يتم التعامل مع الرسائل بنفس ackId الرسالة. ترفض الخدمة التوسط في نفس الرسالة أكثر من مرة، وهو أمر مفيد في إعادة المحاولة لتجنب الرسائل المكررة. على سبيل المثال، إذا أرسل عميل رسالة مع ackId=5 وفشل في تلقي استجابة ack مع ackId=5، ثم يعيد العميل المحاولة ويرسل نفس الرسالة مرة أخرى. في بعض الحالات، يتم بالفعل توسط الرسالة ويتم فقدان استجابة ack لسبب ما. ترفض الخدمة إعادة المحاولة والاستجابة لاستجابة ack لسبب Duplicate ما.

استجابة Ack

ترسل خدمة Web PubSub استجابة ack لكل طلب باستخدام ackId.

التنسيق:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

• يربط ackId الطلب.

• success هو قيمة منطقية ويشير إلى ما إذا كان الطلب قد تمت معالجته بنجاح بواسطة الخدمة. إذا كان ، falseيحتاج العملاء إلى التحقق من error.

• error يوجد فقط عندما success يكون والعملاء false يجب أن يكون لديهم منطق مختلف لمختلف name. يجب أن تفترض أنه قد يكون هناك نوع أكثر من name ذلك في المستقبل.

  • Forbidden: لا يملك العميل الإذن للطلب. يحتاج العميل إلى إضافة الأدوار ذات الصلة.
  • InternalServerError: حدث خطأ داخلي في الخدمة. إعادة المحاولة مطلوبة.
  • Duplicate: تمت معالجة الرسالة بنفس الشيء ackId بالفعل بواسطة الخدمة.

الأذونات

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

الدور	الإذن
غير محدد	يمكن للعميل إرسال طلبات الحدث.
webpubsub.joinLeaveGroup	يمكن للعميل الانضمام إلى أي مجموعة أو مغادرتها.
webpubsub.sendToGroup	يمكن للعميل نشر الرسائل إلى أي مجموعة.
webpubsub.joinLeaveGroup.<group>	يمكن للعميل الانضمام إلى المجموعة <group>أو مغادرتها .
webpubsub.sendToGroup.<group>	يمكن للعميل نشر الرسائل إلى المجموعة <group>.

يمكن منح إذن العميل بعدة طرق:

1. تعيين الدور للعميل عند إنشاء رمز الوصول المميز

يمكن للعميل الاتصال بالخدمة باستخدام رمز JWT المميز. يمكن أن تحمل حمولة الرمز المميز معلومات مثل role العميل. عند توقيع رمز JWT المميز للعميل، يمكنك منح أذونات للعميل عن طريق منح أدوار محددة للعميل.

على سبيل المثال، لنوقع على رمز JWT المميز الذي لديه الإذن لإرسال الرسائل إلى group1 و group2:

let token = await serviceClient.getClientAccessToken({
    roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});

2. تعيين الدور للعميل باستخدام connect معالج الأحداث

يمكن أيضا تعيين أدوار العملاء عند connect تسجيل معالج الأحداث ويمكن لمعالج الأحداث المصدر إرجاع roles العميل إلى خدمة Web PubSub عند معالجة connect الأحداث.

على سبيل المثال، في JavaScript، يمكنك تكوين handleConnect الحدث للقيام بذلك:

let handler = new WebPubSubEventHandler("hub1", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
    });
  },
});

3. تعيين الدور للعميل من خلال واجهات برمجة تطبيقات REST أو SDKs للخادم أثناء وقت التشغيل

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });

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

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

البرنامج التعليمي: نشر الرسائل والاشتراك فيها في Azure Web PubSub

البرنامج التعليمي: إنشاء غرفة دردشة بسيطة باستخدام Azure Web PubSub

البرنامج التعليمي: استخدام البروتوكول الفرعي المدعوم بالخدمة لتدفق العميل

البرنامج التعليمي: إنشاء دردشة بلا خادم باستخدام وظائف Azure وWeb PubSub

البرنامج التعليمي: تكوين وحدة استماع الحدث

اللعب مع العروض التوضيحية المباشرة

استكشاف المزيد من نماذج Azure Web PubSub