Bagikan melalui

Subprotokol WebSocket JSON yang didukung Azure Web PubSub

  • Artikel

Subprotokola JSON WebSocket, json.webpubsub.azure.v1, memungkinkan pertukaran pesan publikasi/berlangganan antara klien melalui layanan tanpa perjalanan pulang pergi ke server upstream. Koneksi WebSocket yang menggunakan json.webpubsub.azure.v1 subprotokola disebut klien WebSocket PubSub.

Gambaran Umum

Koneksi WebSocket sederhana memicu message peristiwa saat mengirim pesan dan bergantung pada sisi server untuk memproses pesan dan melakukan operasi lain.

json.webpubsub.azure.v1 Dengan subprotokola, Anda dapat membuat klien WebSocket PubSub yang dapat:

  • bergabung dengan grup menggunakan permintaan gabungan.
  • menerbitkan pesan langsung ke grup menggunakan permintaan penerbitan.
  • merutekan pesan ke penanganan aktivitas upstream yang berbeda menggunakan permintaan peristiwa.

Misalnya, Anda dapat membuat klien WebSocket PubSub dengan kode JavaScript berikut:

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

Dokumen ini menjelaskan permintaan dan respons subprotokol json.webpubsub.azure.v1 . Bingkai data masuk dan keluar harus berisi payload JSON.

Izin

Klien WebSocket PubSub hanya dapat menerbitkan ke klien lain saat diotorisasi. Yang roles ditetapkan ke klien menentukan izin yang diberikan kepada klien:

Peran Izin
Tidak ditentukan Klien dapat mengirim permintaan peristiwa.
webpubsub.joinLeaveGroup Klien dapat bergabung/meninggalkan grup mana pun.
webpubsub.sendToGroup Klien dapat menerbitkan pesan ke grup mana pun.
webpubsub.joinLeaveGroup.<group> Klien dapat bergabung/meninggalkan grup <group>.
webpubsub.sendToGroup.<group> Klien dapat menerbitkan pesan ke grup <group>.

Server dapat secara dinamis memberikan atau mencabut izin klien melalui REST API atau SDK server.

Permintaan

Bergabung dengan grup

Format:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId adalah identitas dari setiap permintaan dan harus unik. Layanan mengirimkan pesan respons ack untuk memberi tahu hasil proses permintaan. Untuk detailnya, lihat Respons AckId dan Ack

Meninggalkan grup

Format:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId adalah identitas dari setiap permintaan dan harus unik. Layanan mengirimkan pesan respons ack untuk memberi tahu hasil proses permintaan. Untuk detailnya, lihat Respons AckId dan Ack

Menerbitkan pesan

Format:

{
    "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 adalah identitas dari setiap permintaan dan harus unik. Layanan mengirimkan pesan respons ack untuk memberi tahu hasil proses permintaan. Untuk detailnya, lihat Respons AckId dan Ack
  • noEcho bersifat opsional. Jika diatur ke true, pesan ini tidak digaungkan kembali ke koneksi yang sama. Jika tidak diatur, nilai default adalah palsu.
  • dataType dapat diatur ke json, text, atau binary:
    • json: data dapat berupa jenis apa pun yang didukung JSON dan akan diterbitkan apa adanya; Jika dataType tidak ditentukan, defaultnya adalah json.
    • text: data harus dalam format string, dan data string akan diterbitkan;
    • binary: data harus dalam format base64, dan data biner akan diterbitkan;

Kasus 1: menerbitkan data teks:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • Klien subprotoklasi dalam <group_name> menerima:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Klien WebSocket sederhana dalam <group_name> menerima string text data.

Kasus 2: menerbitkan data JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • Klien subprotoklasi dalam <group_name> menerima:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Klien WebSocket sederhana dalam <group_name> menerima string {"hello": "world"}berseri .

Kasus 3: menerbitkan data biner:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • Klien subprotoklasi dalam <group_name> menerima:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Klien WebSocket sederhana dalam <group_name> menerima data biner dalam bingkai biner.

Kirim peristiwa kustom

Format:

{
    "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 adalah identitas dari setiap permintaan dan harus unik. Layanan mengirimkan pesan respons ack untuk memberi tahu hasil proses permintaan. Untuk detailnya, lihat Respons AckId dan Ack

dataType dapat berupa salah satu dari text, binary, atau json:

  • json: data dapat berupa jenis apa pun yang didukung json dan akan diterbitkan apa adanya; Defaultnya adalah json.
  • text: data dalam format string, dan data string akan diterbitkan;
  • binary: data dalam format base64, dan data biner akan diterbitkan;

Kasus 1: mengirim peristiwa dengan data teks:

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

Penanganan aktivitas upstram menerima data yang mirip dengan:

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 untuk permintaan HTTP CloudEvents adalah text/plain kapan dataType adalah text.

Kasus 2: mengirim peristiwa dengan data JSON:

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

Penanganan aktivitas upstram menerima data yang mirip dengan:

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 untuk permintaan HTTP CloudEvents adalah application/json kapan dataTypejson

Kasus 3: mengirim peristiwa dengan data biner:

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

Penanganan aktivitas upstram menerima data yang mirip dengan:

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 untuk permintaan HTTP CloudEvents adalah application/octet-stream kapan dataType adalah binary. Bingkai WebSocket dapat berupa format text untuk bingkai pesan teks atau biner yang disandikan UTF8 untuk bingkai pesan binary.

Layanan Web PubSub menolak klien jika pesan tidak cocok dengan format yang dijelaskan.

Respons

Jenis pesan yang diterima oleh klien dapat berupa:

  • ack - Respons terhadap permintaan yang berisi ackId.
  • message - Pesan dari grup atau server.
  • system - Pesan dari layanan Web PubSub.

Respons ack

Ketika permintaan klien berisi ackId, layanan akan mengembalikan respons ack untuk permintaan tersebut. Klien harus menangani mekanisme ack, dengan menunggu respons ack dengan async await operasi dan menggunakan operasi batas waktu ketika respons ack tidak diterima dalam periode tertentu.

Format:

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

Implementasi klien HARUS selalu memeriksa apakah success adalah true atau false pertama, maka hanya membaca kesalahan ketika success adalah false.

Respons pesan

Klien dapat menerima pesan yang diterbitkan dari grup yang telah bergabung dengan klien atau dari server, yang, beroperasi dalam peran manajemen server, mengirim pesan ke klien atau pengguna tertentu.

  1. Saat pesan berasal dari grup

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

  2. Ketika pesan berasal dari server.

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

Kasus 1: Mengirim data Hello World ke koneksi melalui REST API dengan Content-Type=text/plain

  • Klien WebSocket sederhana menerima bingkai WebSocket teks dengan data: Hello World;

  • Klien PubSub WebSocket menerima:

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

Kasus 2: Mengirim data { "Hello" : "World"} ke koneksi melalui REST API dengan Content-Type=application/json

  • Klien WebSocket sederhana menerima bingkai WebSocket teks dengan data ter string: { "Hello" : "World"}.

  • Klien PubSub WebSocket menerima:

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

Jika REST API mengirim string Hello World menggunakan application/json jenis konten, klien WebSocket sederhana menerima string JSON, yang dibungkus "Hello World" dengan tanda kutip ganda (").

Kasus 3: Mengirim data biner ke koneksi melalui REST API dengan Content-Type=application/octet-stream

  • Klien WebSocket sederhana menerima bingkai WebSocket biner dengan data biner.

  • Klien PubSub WebSocket menerima:

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

Respons sistem

Layanan Web PubSub mengirimkan pesan terkait sistem ke klien.

Tersambung

Pesan yang dikirim ke klien ketika klien berhasil terhubung:

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

Terputus

Pesan yang dikirim ke klien ketika server menutup koneksi, atau ketika layanan menolak klien.

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

Langkah berikutnya

Gunakan sumber daya ini untuk mulai membangun aplikasi Anda sendiri:

Tutorial: Menerbitkan dan berlangganan pesan di Azure Web PubSub

Tutorial: Membuat ruang obrolan sederhana dengan Azure Web PubSub

Tutorial: Menggunakan subprotokola yang didukung layanan untuk streaming klien

Tutorial: Bangun obrolan tanpa server dengan Azure Functions dan Web PubSub

Tutorial: Mengonfigurasi pendengar peristiwa

Bermain dengan demo langsung

Jelajahi sampel Azure Web PubSub lainnya