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>。
webpubsub.joinLeaveGroups.<pattern> 客戶端可以加入或離開任何名稱相符 <pattern> 的群組（參見 萬用卡群組角色模式）。
webpubsub.sendToGroups.<pattern> 用戶端可以向任何名稱相符 <pattern> 的群組發布訊息（參見 萬用字群組角色模式）。

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

備註

REST API 或伺服器 SDK 在執行時尚未支援萬用卡角色（例如 webpubsub.sendToGroups.<pattern>）。

要求

加入群組

格式：

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

離開群組

格式：

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

發佈訊息

格式：

{
    "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 用戶端會接收二進位框架中的二進位資料。

開始串流訊息

要啟動群組串流，請發送 sendToGroup 帶有屬性的 stream 請求。 串流開始請求不包含 data、 dataType或 ackId。

格式：

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "noEcho": true|false,
    "stream": {
        "streamId": "<stream_id>",
        "idleTimeoutMs": 300000
    }
}
  • stream.streamId 是邏輯串流的識別碼。 它必須是非空的字串，且在同一客戶端連線上的多個活躍串流中必須是唯一的。 建議用戶端函式庫產生全球唯一值，例如 GUID 或 UUID。
  • stream.idleTimeoutMs 是選擇性的。 若指定，則必須大於 0。 若省略，服務預設為 300000 毫秒。 這個值是閒置逾時，而非整個串流壽命。 傳送串流資料、傳送串流保持連線，或在此逾時前結束串流，當應用程式需要保持串流開啟時。
  • noEcho 是選擇性的。 如果設定為 true，串流訊息不會被回傳到同一個連線。 如果未設定，預設值為 false。

當串流被接受時，用戶端會收到一個設定expectedSequenceId為 1的串流 ack 回應。

傳送串流資料

要傳送串流資料，請發送streamData一個請求，包含 streamId、 streamSequenceId、 dataTypedata和 。

格式：

{
    "type": "streamData",
    "streamId": "<stream_id>",
    "streamSequenceId": 1,
    "dataType" : "json|text|binary",
    "data": {}
}
  • streamId 識別同一用戶端連線上的活躍串流。
  • streamSequenceId 是正的uint64數值。 串流中的第一個資料片段使用 1，而後續每個相同 streamId 資料片段則會增加恰好 1。
  • dataType 可以設定為 json、 text或 binary，使用與 發佈訊息相同的資料編碼規則。

若要保持串流活躍而不傳送資料給訂閱者，請發送streamData僅typestreamId與 的請求。

{
    "type": "streamData",
    "streamId": "<stream_id>"
}

結束串流訊息

要結束直播，請發送 streamEnd 請求。

格式：

{
    "type": "streamEnd",
    "streamId": "<stream_id>"
}

若要以應用程式定義錯誤結束串流，請加入可選 error 屬性。

{
    "type": "streamEnd",
    "streamId": "<stream_id>",
    "error": {
        "message": "<error_detail>",
        "userErrorCode": "<application_error_code>"
    }
}
  • error.message 是一個可選的人類可讀錯誤訊息。
  • error.userErrorCode 是可選的應用程式定義錯誤碼。

當串流被關閉時，出版者會收到串流 關閉回應。

傳送自訂事件

格式：

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}

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

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

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

當 Content-Type 是 application/json 時，CloudEvents HTTP 要求的 dataType 為 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

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

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

Ping

格式：

{
    "type": "ping",
}

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

回覆

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

  • ack - 包含 ackId的要求回應。
  • message - 來自群組或伺服器的訊息。
  • system - 來自 Web PubSub 服務的訊息。
  • pong - 訊息的 ping 回應。
  • streamAck - 回應，確認已接受的串流資料並回報下一個預期的串流序列 ID。
  • streamNack - 針對可重試串流錯誤的回應。
  • streamClosed - 針對終端發行商端串流關閉的回應。

認可回應

當用戶端要求包含 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為 或true第一個，則只有在 是 falsesuccess時false才會讀取錯誤。

訊息回應

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

  1. 當訊息來自群組時

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

  2. 當訊息來自伺服器時。

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

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

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

  • PubSub WebSocket 用戶端會收到：

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

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

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

  • PubSub WebSocket 用戶端會收到：

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

如果 REST API 使用Hello World內容類型傳送字串application/json，則簡單的 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>"
}

串流訊息回應

當訊息屬於串流時，群組訊息包含一個 stream 屬性。

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data": {},
    "fromUserId": "abc",
    "stream": {
        "streamId": "<stream_id>",
        "streamSequenceId": 1,
        "endOfStream": true,
        "error": {
            "name": "IdleTimeout|InternalServerError|Forbidden|Cancelled|UserError",
            "message": "<error_detail>",
            "userErrorCode": "<application_error_code>"
        }
    }
}
  • stream.streamId 是邏輯串流識別碼。
  • stream.streamSequenceId 是串流中訊息的序號。
  • stream.endOfStream 是選擇性的。 當 設為 true時，訊息即為串流的終端訊息。
  • stream.error 是可選的，僅在串流以錯誤結束時才會出現。 userErrorCode 僅存在於 UserError。

串流 ack 回應

服務會 streamAck 發送回應以確認已接受的串流資料，並回報它預期的下一個串流序列 ID。

格式：

{
    "type": "streamAck",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2
}

Stream nack 回應

服務會 streamNack 針對可重試串流錯誤發送回應。

格式：

{
    "type": "streamNack",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2,
    "name": "InvalidSequenceId|TransientError",
    "message": "<error_detail>"
}

串流閉合反應

當發佈者端的串流關閉時，服務會 streamClosed 發送回應。

格式：

{
    "type": "streamClosed",
    "streamId": "<stream_id>",
    "error": {
        "name": "StreamNotFound|Forbidden|BadRequest|InternalServerError|IdleTimeout",
        "message": "<error_detail>"
    }
}

當溪流正常閉合時，此 error 性質被省略。

系統回應

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

Pong 回應

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

格式：

{
    "type": "pong",
}

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

  • Last updated on