ملحق CloudEvents لمعالج أحداث Azure Web PubSub مع بروتوكول HTTP

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

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

• التحقق من صحة خطاف الويب
• ملحق سمة Web PubSub CloudEvents
• الأحداث
  • حظر الأحداث
    • حدث النظام connect
    • أحداث المستخدم
  • إلغاء حظر الأحداث
    • حدث النظام connected
    • حدث النظام disconnected

التحقق من صحة خطاف الويب

يتبع التحقق من صحة Webhook CloudEvents. يحتوي WebHook-Request-Origin: xxx.webpubsub.azure.com الطلب دائما في العنوان.

إذا كان هدف التسليم يسمح بتسليم الأحداث فقط، فيجب عليه الرد على الطلب عن طريق تضمين WebHook-Allowed-Origin العنوان، على سبيل المثال:

WebHook-Allowed-Origin: *

أو:

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

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

ملحق سمة Web PubSub CloudEvents

كما لوحظ أن مواصفات HTTP تتبع الآن نمطا مشابها من خلال عدم اقتراح أن تكون عناوين HTTP الملحق مسبوقة ب X-.

يعرف هذا الملحق السمات المستخدمة من قبل Web PubSub لكل حدث ينتجه.

سمات

حدث

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

• حظر الأحداث
  • حدث النظام connect
  • أحداث المستخدم
• إلغاء حظر الأحداث
  • حدث النظام connected
  • حدث النظام disconnected

حدث النظام connect

• ce-type: azure.webpubsub.sys.connect
• Content-Type: application/json

تنسيق الطلب:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/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}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "<certificate SHA-1 thumbprint>",
            "content": "-----BEGIN CERTIFICATE-----\r\n...\r\n-----END CERTIFICATE-----"
        }
    ]
}

تنسيق استجابة النجاح:

• العنوان ce-connectionState: إذا كان هذا العنوان موجودا، فسيتم تحديث حالة الاتصال لهذا الاتصال إلى قيمة العنوان. يمكن فقط لحظر الأحداث تحديث حالة الاتصال. يستخدم النموذج أدناه سلسلة JSON المشفرة base64 لتخزين الحالة المعقدة للاتصال.

• رمز الحالة:

  • 204: نجاح، بدون محتوى.
  • 200: نجاح، يجب أن يكون المحتوى بتنسيق JSON، مع السماح بالخصائص التالية:

    • subprotocols

      يقوم connect الحدث بإعادة توجيه البروتوكول الفرعي ومعلومات المصادقة إلى المصدر من العميل. تستخدم خدمة Web PubSub رمز الحالة لتحديد ما إذا كان سيتم ترقية الطلب إلى بروتوكول WebSocket.

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

    • userId: {auth-ed user ID}

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

    • groups: {groups to join}

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

    • roles: {roles the client has}

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

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

تنسيق استجابة الخطأ:

• 4xx: خطأ، سيتم إرجاع الاستجابة من المصدر كاستجابة لطلب العميل.

HTTP/1.1 401 Unauthorized

حدث النظام connected

تستدعي الخدمة المصدر عندما يكمل العميل تأكيد اتصال WebSocket ويتم توصيله بنجاح.

• ce-type: azure.webpubsub.sys.connected
• Content-Type: application/json
• ce-connectionState: eyJrZXkiOiJhIn0=

نص الطلب هو JSON فارغ.

تنسيق الطلب:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/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}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

تنسيق الاستجابة:

2xx: استجابة النجاح.

connected هو حدث غير متزامن، عندما لا ينجح رمز حالة الاستجابة، تسجل الخدمة خطأ.

HTTP/1.1 200 OK

حدث النظام disconnected

disconnected يتم تشغيل الحدث دائما عند اكتمال طلب العميل إذا قام حدث الاتصال بإرجاع 2xx رمز الحالة.

• ce-type: azure.webpubsub.sys.disconnected
• Content-Type: application/json

تنسيق الطلب:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/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}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

• reason

  reason يصف سبب قطع اتصال العميل.

تنسيق الاستجابة:

2xx: استجابة النجاح.

disconnected هو حدث غير متزامن، عندما لا ينجح رمز حالة الاستجابة، تسجل الخدمة خطأ.

HTTP/1.1 200 OK

حدث message المستخدم لعملاء WebSocket البسيطين

تستدعي الخدمة معالج الأحداث في المصدر لكل إطار رسالة WebSocket.

• ce-type: azure.webpubsub.user.message
• Content-Type: application/octet-stream للإطار الثنائي؛ text/plain للإطار النصي؛

UserPayload هو ما يرسله العميل.

تنسيق الطلب:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/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}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

تنسيق استجابة النجاح

• رمز الحالة
  • 204: نجاح، بدون محتوى.
  • 200: النجاح، يعتمد تنسيق على UserResponsePayload Content-Type الاستجابة.
• Content-Type: application/octet-stream للإطار الثنائي؛ text/plain للإطار النصي؛
• العنوان Content-Type: application/octet-stream للإطار الثنائي؛ لإطار النص؛ text/plain
• العنوان ce-connectionState: إذا كان هذا العنوان موجودا، فسيتم تحديث حالة الاتصال لهذا الاتصال إلى قيمة العنوان. يمكن فقط لحظر الأحداث تحديث حالة الاتصال. يستخدم النموذج أدناه سلسلة JSON المشفرة base64 لتخزين الحالة المعقدة للاتصال.

Content-Type عندما يكون هو application/octet-stream، ترسل UserResponsePayload الخدمة إلى العميل باستخدام binary إطار WebSocket. Content-Type عندما يكون هو text/plain، ترسل UserResponsePayload الخدمة إلى العميل باستخدام text إطار WebSocket.

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

تنسيق استجابة الخطأ

عندما لا ينجح رمز الحالة، فإنه يعتبر استجابة للخطأ. سيتم إسقاط الاتصال إذا message لم ينجح رمز حالة الاستجابة.

حدث {custom_event} مخصص للمستخدم لعملاء PubSub WebSocket

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

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

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

ما يتلقاه معالج الأحداث المصدر كما هو موضح أدناه، Content-Type لطلب CloudEvents HTTP هو text/plain من أجل dataType=text

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>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

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

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

ما يتلقاه معالج الأحداث المصدر كما هو موضح أدناه، Content-Type لطلب CloudEvents HTTP هو application/json من أجل dataType=json

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>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

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

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

ما يتلقاه معالج الأحداث المصدر كما هو موضح أدناه، Content-Type لطلب CloudEvents HTTP هو application/octet-stream من أجل dataType=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>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

تنسيق استجابة النجاح

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload

• رمز الحالة
  • 204: نجاح، بدون محتوى.
  • 200: النجاح، تعتمد البيانات المرسلة إلى عميل PubSub WebSocket على Content-Type؛
• العنوان ce-connectionState: إذا كان هذا العنوان موجودا، فسيتم تحديث حالة الاتصال لهذا الاتصال إلى قيمة العنوان. يمكن فقط لحظر الأحداث تحديث حالة الاتصال. يستخدم النموذج أدناه سلسلة JSON المشفرة base64 لتخزين الحالة المعقدة للاتصال.
• عندما يكون العنوان Content-Type هو application/octet-stream، ترسل UserResponsePayload الخدمة مرة أخرى إلى العميل باستخدام dataType كما هو الحال binary مع ترميز base64 للحمولة. نموذج استجابة:

  {
      "type": "message",
      "from": "server",
      "dataType": "binary",
      "data" : "aGVsbG8gd29ybGQ="
  }
  

• Content-Type عندما يكون هو text/plain، ترسل UserResponsePayload الخدمة إلى العميل باستخدام dataType كما هو الحال text مع سلسلة الحمولة.
• Content-Type عندما يكون هو application/json، ترسل UserResponsePayload الخدمة إلى العميل باستخدامjson dataType=رمز data مميز للقيمة كنص أساسي لحمولة الاستجابة.

تنسيق استجابة الخطأ

عندما لا ينجح رمز الحالة، فإنه يعتبر استجابة للخطأ. سيتم إسقاط الاتصال إذا {custom_event} لم ينجح رمز حالة الاستجابة.

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

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