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

يتيح البروتوكول الفرعي JSON WebSocket تبادل json.webpubsub.azure.v1رسائل النشر/الاشتراك بين العملاء من خلال الخدمة دون رحلة ذهابا وإيابا إلى الخادم المصدر. يسمى اتصال WebSocket باستخدام json.webpubsub.azure.v1 البروتوكول الفرعي عميل PubSub WebSocket.

نظرة عامة

يقوم اتصال WebSocket البسيط بتشغيل message حدث عندما يرسل رسائل ويعتمد على جانب الخادم لمعالجة الرسائل والقيام بعمليات أخرى.

json.webpubsub.azure.v1 باستخدام البروتوكول الفرعي، يمكنك إنشاء عملاء PubSub WebSocket الذين يمكنهم:

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

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

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

يصف هذا المستند طلبات البروتوكول الفرعي json.webpubsub.azure.v1 والاستجابات. يجب أن تحتوي كل من إطارات البيانات الواردة والصادرة على حمولات JSON.

الأذونات

يمكن لعميل PubSub WebSocket النشر فقط للعملاء الآخرين عندما يكون مصرحا به. roles يحدد المعين للعميل الأذونات الممنوحة للعميل:

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

يمكن للخادم منح أذونات العميل أو إبطالها ديناميكيا من خلال واجهات برمجة تطبيقات REST أو SDKs للخادم.

ملحوظة

أدوار حرف البدل (على سبيل المثال، webpubsub.sendToGroups.<pattern>) غير مدعومة في واجهات برمجة تطبيقات REST أو SDKs للخادم أثناء وقت التشغيل حتى الآن.

الطلبات

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

التنسيق:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId هوية كل طلب ويجب أن يكون فريدا. ترسل الخدمة رسالة استجابة ack لإعلام نتيجة العملية بالطلب. للحصول على التفاصيل، راجع استجابة AckId وAck

مغادرة المجموعات

التنسيق:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId هوية كل طلب ويجب أن يكون فريدا. ترسل الخدمة رسالة استجابة ack لإعلام نتيجة العملية بالطلب. للحصول على التفاصيل، راجع استجابة AckId وAck

انشر الرسائل

التنسيق:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId هوية كل طلب ويجب أن يكون فريدا. ترسل الخدمة رسالة استجابة ack لإعلام نتيجة العملية بالطلب. للحصول على التفاصيل، راجع استجابة AckId وAck
  • noEcho اختياري. إذا تم تعيينها إلى true، فلن يتم تكرار هذه الرسالة مرة أخرى إلى نفس الاتصال. إذا لم يتم تعيينها، تكون القيمة الافتراضية خاطئة.
  • dataType يمكن تعيين إلى jsonأو textأو binary:
    • json: data يمكن أن يكون أي نوع يدعمه JSON وسيتم نشره كما هو؛ إذا dataType لم يتم تحديده، تعيينه افتراضيا إلى json.
    • text: data يجب أن تكون بتنسيق سلسلة، وسيتم نشر بيانات السلسلة؛
    • binary: data يجب أن تكون بتنسيق base64، وسيتم نشر البيانات الثنائية؛

الحالة 1: نشر البيانات النصية:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • يتلقى عملاء <group_name> البروتوكول الفرعي:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • يتلقى عملاء WebSocket البسيطون في <group_name> السلسلة text data.

الحالة 2: نشر بيانات JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • يتلقى عملاء <group_name> البروتوكول الفرعي:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • يتلقى عملاء WebSocket البسيطون في <group_name> السلسلة {"hello": "world"}المتسلسلة .

الحالة 3: نشر البيانات الثنائية:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • يتلقى عملاء <group_name> البروتوكول الفرعي:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • يتلقى عملاء WebSocket البسيطون البيانات <group_name> الثنائيةفي الإطار الثنائي.

إرسال أحداث مخصصة

التنسيق:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId هوية كل طلب ويجب أن يكون فريدا. ترسل الخدمة رسالة استجابة ack لإعلام نتيجة العملية بالطلب. للحصول على التفاصيل، راجع استجابة AckId وAck

dataType يمكن أن يكون واحدا من textأو binaryأو json:

  • json: يمكن أن تكون البيانات أي نوع يدعمه json وسيتم نشره على أنه ما هو عليه؛ الإعداد الافتراضي هو json.
  • text: البيانات بتنسيق سلسلة، وسيتم نشر بيانات السلسلة؛
  • binary: البيانات بتنسيق base64، وسيتم نشر البيانات الثنائية؛

الحالة 1: إرسال حدث مع بيانات نصية:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "text",
    "data": "text data", 
}

يتلقى معالج الأحداث المصدر بيانات مشابهة ل:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

text data

Content-Type لطلب CLOUDEvents HTTP هو text/plain عندما dataType يكون .text

الحالة 2: إرسال حدث مع بيانات JSON:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json",
    "data": {
        "hello": "world"
    }, 
}

يتلقى معالج الأحداث المصدر بيانات مشابهة ل:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

{
    "hello": "world"
}

Content-Type لطلب CloudEvents HTTP هو عندما application/json يكون dataTypejson

الحالة 3: إرسال حدث مع بيانات ثنائية:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_binary", 
}

يتلقى معالج الأحداث المصدر بيانات مشابهة ل:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

binary

Content-Type لطلب CLOUDEvents HTTP هو application/octet-stream عندما dataType يكون .binary يمكن أن يكون text إطار WebSocket تنسيقا لإطارات الرسائل النصية أو ثنائيات UTF8 المشفرة لإطارات binary الرسائل.

تقوم خدمة Web PubSub برفض العميل إذا لم تتطابق الرسالة مع التنسيق الموضح.

أداة اختبار الاتصال

التنسيق:

{
    "type": "ping",
}

يمكن للعميل إرسال رسالة ping إلى الخدمة لتمكين خدمة Web PubSub للكشف عن فعالية العميل.

الاستجابات

يمكن أن تكون أنواع الرسائل التي يتلقاها العميل:

  • ack - الاستجابة لطلب يحتوي على ackId.
  • رسالة - رسائل من المجموعة أو الخادم.
  • النظام - رسائل من خدمة Web PubSub.
  • بونغ - الاستجابة لرسالة ping .

استجابة Ack

عندما يحتوي طلب العميل على ackId، سترجع الخدمة استجابة ack للطلب. يجب على العميل التعامل مع آلية ack، عن طريق انتظار استجابة ack مع asyncawait عملية واستخدام عملية مهلة عندما لا يتم تلقي استجابة ack في فترة معينة.

التنسيق:

{
    "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>"
    }
}

يجب أن يتحقق تنفيذ العميل دائما مما إذا كان success هو true أو false أولا، ثم اقرأ الخطأ فقط عندما success يكون false.

استجابة الرسالة

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

  1. عندما تكون الرسالة من مجموعة

    {
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

  2. عندما تكون الرسالة من الخادم.

    {
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

الحالة 1: إرسال البيانات Hello World إلى الاتصال من خلال واجهة برمجة تطبيقات REST باستخدام Content-Type=text/plain

  • يتلقى عميل WebSocket البسيط إطار WebSocket نصيا مع البيانات: Hello World؛

  • يتلقى عميل PubSub WebSocket ما يلي:

    {
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

الحالة 2: إرسال البيانات { "Hello" : "World"} إلى الاتصال من خلال واجهة برمجة تطبيقات REST باستخدام Content-Type=application/json

  • يتلقى عميل WebSocket البسيط إطار WebSocket نصيا مع بيانات سلسلة: { "Hello" : "World"}.

  • يتلقى عميل PubSub WebSocket ما يلي:

    {
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

إذا كانت واجهة برمجة تطبيقات REST ترسل سلسلة Hello World باستخدام application/json نوع المحتوى، يتلقى عميل WebSocket البسيط سلسلة JSON، والتي يتم "Hello World" تضمينها بعلامات اقتباس مزدوجة (").

الحالة 3: إرسال البيانات الثنائية إلى الاتصال من خلال واجهة برمجة تطبيقات REST باستخدام Content-Type=application/octet-stream

  • يتلقى عميل WebSocket بسيط إطار WebSocket ثنائي مع البيانات الثنائية.

  • يتلقى عميل PubSub WebSocket ما يلي:

    {
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

استجابة النظام

ترسل خدمة Web PubSub رسائل متعلقة بالنظام إلى العملاء.

استجابة بونغ

ترسل خدمة Web PubSub رسالة pong إلى العميل عندما تتلقى رسالة ping من العميل.

التنسيق:

{
    "type": "pong",
}

Connected

الرسالة المرسلة إلى العميل عند اتصال العميل بنجاح:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

غير متصل

الرسالة المرسلة إلى العميل عندما يغلق الخادم الاتصال، أو عندما تقوم الخدمة برفض العميل.

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

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

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

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

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

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

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

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

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

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

  • Last updated on