بروتوكولات عميل 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 المميز:

يمكنك أيضا إضافة مطالبات مخصصة إلى الرمز المميز للوصول، ويتم الاحتفاظ بهذه القيم كخاصية 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')

يحتوي عميل WebSocket البسيط على وضعين: sendEvent و sendToGroup. يتم تحديد الوضع بمجرد تأسيس الاتصال ولا يمكن تغييره لاحقا.

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

// Every data frame is considered as a `message` event
var client3 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// Or explicitly set the mode
var client4 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendEvent');

في sendToGroup الوضع، يعتبر كل إطار WebSocket يرسله العميل كرسالة ليتم نشرها إلى مجموعة معينة. group هي معلمة استعلام مطلوبة في هذا الوضع، ويسمح بقيمة واحدة فقط. يجب أن يكون للاتصال أيضا أذونات مقابلة لإرسال رسائل إلى المجموعة المستهدفة. يعمل كل من webpubsub.sendToGroup.<group> والأدوار webpubsub.sendToGroup لذلك.

على سبيل المثال، في JavaScript، يمكنك إنشاء عميل WebSocket بسيط في sendToGroup الوضع باستخدام group=group1 التعليمات البرمجية التالية:

var client5 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendToGroup&group=group1');

عميل 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 السابق، يمكن للعميل النشر إلى عملاء آخرين فقط عندما يكون مخولا للقيام بذلك. يمكن منح أذونات العميل عند اتصاله أو أثناء مدة بقاء الاتصال.

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

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" });

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

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