Azure Web PubSub 可靠 JSON WebSocket 子通訊協定

發行項
2025-01-03

JSON WebSocket 子通訊協定 json.reliable.webpubsub.azure.v1，可讓您透過服務直接在用戶端之間進行發佈/訂閱訊息的高度可靠交換，而不需要往返於上游伺服器。

本文件描述子通訊協定 json.reliable.webpubsub.azure.v1。

當 WebSocket 用戶端連線因為間歇性網路問題而中斷時，訊息可能會遺失。在發佈/訂閱系統中，發行者會與訂閱者分離，因此發行者很難偵測訂閱者的連線中斷或訊息遺失。

若要克服間歇性網路問題並維護可靠的訊息傳遞，您可以使用 Azure WebPubSub json.reliable.webpubsub.azure.v1 子通訊協定來建立可靠的 PubSub WebSocket 用戶端。

可靠的 PubSub WebSocket 用戶端可以：

從間歇性網路問題復原連線。
從訊息遺失復原。
使用加入要求加入群組。
使用離開要求離開群組。
使用發佈要求將訊息直接發佈至群組。
使用事件要求將訊息直接路由傳送至上游事件處理常式。

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

var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.reliable.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 服務就會拒絕用戶端。

Ping

格式：

{
    "type": "ping",
}

用戶端可以將訊息傳送 ping 至服務，讓 Web PubSub 服務偵測客戶端的活躍度。

序列認可

格式：

{
    "type": "sequenceAck",
    "sequenceId": "<sequenceId>",
}

可靠的 PubSub WebSocket 用戶端在收到來自服務的訊息後，必須隨即傳送序列認可訊息。如需詳細資訊，請參閱如何建立可靠的用戶端

sequenceId 是收到的訊息中累加的 uint64 數值。

回覆

用戶端所接收的訊息可以是數種類型： ack、 message、 system和 pong。類型 message 的訊息具有 sequenceId 屬性。用戶端在收到訊息後，必須隨即傳送序列認可給服務。

認可回應

當要求包含 ackId 時，則服務會傳回此要求的認可回應。用戶端實作應該處理此 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 是否為 true 或 false。只有當 success 是 false 時，用戶端才會讀取 error。

訊息回應

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

來自群組的回應訊息：

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

來自伺服器的回應訊息：

{
    "sequenceId": 1,
    "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 用戶端會接收 JSON 格式的訊息：

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

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

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

PubSub WebSocket 用戶端會接收 JSON 格式的訊息：

{
    "sequenceId": 1,
    "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 用戶端會接收 JSON 格式的訊息：

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

系統回應

Web PubSub 服務也可以將系統相關回應傳回給用戶端。

Pong 回應

Web PubSub 服務從用戶端接收ping訊息時，會將訊息傳送pong給用戶端。

格式：

{
    "type": "pong",
}

Connected

對用戶端連線要求的回應：

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
    "reconnectionToken": "<token>"
}

connectionId 和 reconnectionToken 會用於重新連線。請使用 URI 提出連線要求以進行重新連線：

wss://<service-endpoint>/client/hubs/<hub>?awps_connection_id=<connectionId>&awps_reconnection_token=<reconnectionToken>

在連線復原中可找到詳細資料

已中斷連接

伺服器關閉連線時或服務拒絕用戶端連線時的回應：

{
    "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：使用二進位資料傳送事件：

Ping

序列認可

回覆

認可回應

訊息回應

案例 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，將二進位資料傳送至連線

系統回應

Pong 回應

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`，將二進位資料傳送至連線