Azure Web PubSub 支援的 JSON WebSocket 子程式
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 機制,方法是等候具有async
await
作業的 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"
}
下一步
使用這些資源開始建置自己的應用程式: