Azure Web PubSub 支援的 JSON WebSocket 子程式

文章
07/03/2024

JSON WebSocket 子程式 json.webpubsub.azure.v1可讓您透過服務在用戶端之間交換發佈/訂閱訊息，而不需要往返上游伺服器。使用 subprotocol 的 json.webpubsub.azure.v1 WebSocket 連線稱為 PubSub WebSocket 用戶端。

概觀

簡單的 WebSocket 聯機會在 message 傳送訊息時觸發事件，並依賴伺服器端來處理訊息並執行其他作業。

json.webpubsub.azure.v1使用子程式，您可以建立 PubSub WebSocket 用戶端，以便：

使用加入要求加入群組。
使用發佈要求將訊息直接發佈至群組。
使用事件要求將訊息路由傳送至不同的上游事件處理程式。

例如，您可以使用下列 JavaScript 程式代碼建立 PubSub WebSocket 用戶端 ：

// 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>`。

伺服器可以透過 REST API 或伺服器 SDK 動態授與或撤銷用戶端權限。

要求

加入群組

格式：

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}

ackId 是每個要求的身分識別，且應該是唯一的。服務會傳送認可回應訊息，以通知要求的處理結果。如需詳細資訊，請參閱 AckId 和 Ack 回應

離開群組

格式：

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}

ackId 是每個要求的身分識別，且應該是唯一的。服務會傳送認可回應訊息，以通知要求的處理結果。如需詳細資訊，請參閱 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 是每個要求的身分識別，且應該是唯一的。服務會傳送認可回應訊息，以通知要求的處理結果。如需詳細資訊，請參閱 AckId 和 Ack 回應
noEcho 是選擇性的。如果設定為 true，則此訊息不會回應到相同的連線。如果未設定，預設值為 false。
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"
}

<group_name> 中的簡單 WebSocket 用戶端會接收字串 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"
    }
}

<group_name> 中的簡單 WebSocket 用戶端會接收序列化字串 {"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>", 
}

<group_name> 中的簡單 WebSocket 用戶端會接收二進位框架中的二進位資料。

傳送自訂事件

格式：

{
    "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 是每個要求的身分識別，且應該是唯一的。服務會傳送認可回應訊息，以通知要求的處理結果。如需詳細資訊，請參閱 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

當 dataType 是 text 時，CloudEvents HTTP 要求的 Content-Type 為 text/plain。

案例 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"
}

當 dataType 是 json 時，CloudEvents HTTP 要求的 Content-Type 為 application/json

案例 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

當 dataType 是 binary 時，CloudEvents HTTP 要求的 Content-Type 為 application/octet-stream。若採用文字簡訊框架，則 WebSocket 框架可以是 text 格式，或若為 binary 訊息框架，則為 UTF8 編碼二進位。

如果訊息不符合描述的格式，Web PubSub 服務就會拒絕用戶端。

回覆

用戶端收到的訊息類型可以是：

ack - 包含 ackId的要求回應。
message - 來自群組或伺服器的訊息。
system - 來自 Web PubSub 服務的訊息。

認可回應

當用戶端要求包含 ackId時，服務會傳回要求的 ack 回應。客戶端應該處理 ack 機制，方法是等候具有asyncawait作業的 ack 回應，並在特定期間未收到 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為或false第一個，則只有在是 true false時success才會讀取錯誤。

訊息回應

用戶端可以接收從用戶端已加入的群組或從伺服器發佈的訊息，以伺服器管理角色操作，將訊息傳送至特定用戶端或使用者。

當訊息來自群組時

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

當訊息來自伺服器時。

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

案例 1：透過 REST API 並使用 `Content-Type`=`text/plain`，將資料 `Hello World` 傳送至連線

簡單的 WebSocket 用戶端接收的內容是包含資料的文字 WebSocket 框架：Hello World；

PubSub WebSocket 用戶端會收到：

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

案例 2：透過 REST API 並使用 `Content-Type`=`application/json`，將資料 `{ "Hello" : "World"}` 傳送至連線

簡單的 WebSocket 用戶端會收到文字 WebSocket 框架，其中包含字串化數據： { "Hello" : "World"}。

PubSub WebSocket 用戶端會收到：

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

如果 REST API 使用application/json內容類型傳送字串Hello World，則簡單的 WebSocket 用戶端會收到 JSON 字串，該"Hello World"字串會包裝成雙引號（"）。

案例 3：透過 REST API 並使用 `Content-Type`=`application/octet-stream`，將二進位資料傳送至連線

簡單的 WebSocket 用戶端所接收的內容是含有二進位資料的二進位 WebSocket 框架。

PubSub WebSocket 用戶端會收到：

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

系統回應

Web PubSub 服務會將系統相關的訊息傳送給用戶端。

Connected

用戶端成功連線時傳送給用戶端的訊息：

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

已中斷連接

當伺服器關閉連線或服務拒絕用戶端時，傳送給用戶端的訊息。

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

下一步

使用這些資源開始建置自己的應用程式：

教學課程：在 Azure Web PubSub 中發佈及訂閱訊息

教學課程：使用 Azure Web PubSub 建立簡單的聊天室

教學課程：使用服務支援的子通訊協定進行用戶端串流

教學課程：使用 Azure Functions 和 Web PubSub 建置無伺服器聊天

教學課程：設定事件接聽程式

探索即時示範

探索更多 Azure Web PubSub 範例

分享方式：

Azure Web PubSub 支援的 JSON WebSocket 子程式

概觀

權限

要求

加入群組

離開群組

發佈訊息

案例 1：發佈文字資料：

案例 2：發佈 JSON 資料：

案例 3：發佈二進位資料：

傳送自訂事件

案例 1：使用文字資料傳送事件：

案例 2：使用 JSON 資料傳送事件：

案例 3：使用二進位資料傳送事件：

回覆

認可回應

訊息回應

案例 1：透過 REST API 並使用 `Content-Type`=`text/plain`，將資料 `Hello World` 傳送至連線

案例 2：透過 REST API 並使用 `Content-Type`=`application/json`，將資料 `{ "Hello" : "World"}` 傳送至連線

案例 3：透過 REST API 並使用 `Content-Type`=`application/octet-stream`，將二進位資料傳送至連線

系統回應

Connected

已中斷連接

下一步

意見反映

更多資源

分享方式：

Azure Web PubSub 支援的 JSON WebSocket 子程式

概觀

權限

要求

加入群組

離開群組

發佈訊息

案例 1：發佈文字資料：

案例 2：發佈 JSON 資料：

案例 3：發佈二進位資料：

傳送自訂事件

案例 1：使用文字資料傳送事件：

案例 2：使用 JSON 資料傳送事件：

案例 3：使用二進位資料傳送事件：

回覆

認可回應

訊息回應

案例 1：透過 REST API 並使用 Content-Type=text/plain，將資料 Hello World 傳送至連線

案例 2：透過 REST API 並使用 Content-Type=application/json，將資料 { "Hello" : "World"} 傳送至連線

案例 3：透過 REST API 並使用 Content-Type=application/octet-stream，將二進位資料傳送至連線

系統回應

Connected

已中斷連接

下一步

意見反映

更多資源

案例 1：透過 REST API 並使用 `Content-Type`=`text/plain`，將資料 `Hello World` 傳送至連線

案例 2：透過 REST API 並使用 `Content-Type`=`application/json`，將資料 `{ "Hello" : "World"}` 傳送至連線

案例 3：透過 REST API 並使用 `Content-Type`=`application/octet-stream`，將二進位資料傳送至連線