You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/azure-web-pubsub/includes/reference-permission.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ ms.date: 08/06/2021
8
8
9
9
## Permissions
10
10
11
-
A Web PubSub WebSocket client can only publish to other clients when it's authorized. The `roles` assigned to the client determine the permissions granted to the client:
11
+
A PubSub WebSocket client can only publish to other clients when it's authorized. The `roles` assigned to the client determine the permissions granted to the client:
12
12
13
13
| Role | Permission |
14
14
|---|---|
@@ -18,4 +18,4 @@ A Web PubSub WebSocket client can only publish to other clients when it's author
18
18
| `webpubsub.joinLeaveGroup.<group>` | The client can join/leave the group `<group>`.
19
19
| `webpubsub.sendToGroup.<group>` | The client can publish messages to the group `<group>`.
20
20
21
-
The server can dynamically grant or revoke permissions from the client through REST APIs or server SDKs.
21
+
The server can dynamically grant or revoke client permissions through REST APIs or server SDKs.
Copy file name to clipboardExpand all lines: articles/azure-web-pubsub/includes/reference-protobuf-requests.md
+23-20Lines changed: 23 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,23 +18,23 @@ Set `leave_group_message.group` to the group name.
18
18
19
19
Format:
20
20
21
-
*`ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
21
+
*`ackId`: The unique identity of each request. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
22
22
23
-
There's an implicit `dataType`, which can be `protobuf`, `text`, or `binary`, depending on the `data` in `MessageData` you set. The receiver clients can use `dataType` to handle the content correctly.
23
+
*`dataType`: The format of the `data`, which can be `protobuf`, `text`, or `binary`, depending on the `data` in `MessageData`. The receiving clients can use `dataType` to correctly process the content.
24
24
25
-
*`protobuf`: If you set `send_to_group_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. `protobuf_data` can be of the [Any](https://developers.google.com/protocol-buffers/docs/proto3#any) message type. All other clients receive a protobuf-encoded binary, which can be deserialized by the protobuf SDK. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
25
+
*`protobuf`: When you set `send_to_group_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. `protobuf_data` can be of the [Any](https://developers.google.com/protocol-buffers/docs/proto3#any) message type. All other clients receive a protobuf-encoded binary, which can be deserialized by the protobuf SDK. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
26
26
27
-
*`text`: If you set `send_to_group_message.data.text_data`, the implicit `dataType` is `text`. `text_data` should be a string. All clients with other protocols receive a UTF-8-encoded string.
27
+
*`text`: When you set `send_to_group_message.data.text_data`, the implicit `dataType` is `text`. `text_data` should be a string. All clients with other protocols receive a UTF-8-encoded string.
28
28
29
-
*`binary`: If you set `send_to_group_message.data.binary_data`, the implicit `dataType` is `binary`. `binary_data` should be a byte array. All clients with other protocols receive a raw binary without protobuf encoding. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
29
+
*`binary`: When you set `send_to_group_message.data.binary_data`, the implicit `dataType` is `binary`. `binary_data` should be a byte array. All clients with other protocols receive a raw binary without protobuf encoding. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
30
30
31
31
#### Case 1: Publish text data
32
32
33
33
Set `send_to_group_message.group` to `group`, and set `send_to_group_message.data.text_data` to `"text data"`.
34
34
35
35
* The protobuf subprotocol client in group `group` receives the binary frame and can use [DownstreamMessage](#responses) to deserialize it.
36
36
37
-
* The JSON subprotocol client in group `group`receives:
37
+
* The JSON subprotocol clients in `group`receive:
38
38
39
39
```json
40
40
{
@@ -46,11 +46,11 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
46
46
}
47
47
```
48
48
49
-
* The raw client in group `group` receives string `text data`.
49
+
* The simple WebSocket clients in `group` receive string `text data`.
50
50
51
51
#### Case 2: Publish protobuf data
52
52
53
-
Let's assume that you have a customer message:
53
+
Let's assume that you have a custom message:
54
54
55
55
```
56
56
message MyMessage {
@@ -60,9 +60,9 @@ message MyMessage {
60
60
61
61
Set `send_to_group_message.group` to `group` and `send_to_group_message.data.protobuf_data` to `Any.pack(MyMessage)` with `value = 1`.
62
62
63
-
* The protobuf subprotocol client in group `group` receives the binary frame and can use [DownstreamMessage](#responses) to deserialize it.
63
+
* The protobuf subprotocol clients in `group` receive the binary frame and can use [DownstreamMessage](#responses) to deserialize it.
64
64
65
-
* The subprotocol client in group `group` receives:
65
+
* The subprotocol client in `group` receives:
66
66
67
67
```json
68
68
{
@@ -87,7 +87,7 @@ message MyMessage {
87
87
}
88
88
```
89
89
90
-
* The raw client in group `group`receives the binary frame:
90
+
* The simple WebSocket clients in `group`receive the binary frame:
91
91
92
92
```
93
93
# Show in hexadecimal
@@ -114,7 +114,7 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
114
114
115
115
Because the JSON subprotocol client supports only text-based messaging, the binary is always Base64-encoded.
116
116
117
-
* The raw client in group `group` receives the binary data in the binary frame:
117
+
* The simple WebSocket clients in `group` receive the binary data in the binary frame:
118
118
119
119
```
120
120
# Show in hexadecimal
@@ -125,17 +125,17 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
125
125
126
126
There's an implicit `dataType`, which can be `protobuf`, `text`, or `binary`, depending on the `dataType` you set. The receiver clients can use `dataType` to handle the content correctly.
127
127
128
-
* `protobuf`: If you set `event_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. `protobuf_data` can be any supported protobuf type. The event handler receives the protobuf-encoded binary, which can be deserialized by any protobuf SDK.
128
+
* `protobuf`: When you set `event_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. The `protobuf_data` value can be any supported protobuf type. The event handler receives the protobuf-encoded binary, which can be deserialized by any protobuf SDK.
129
129
130
-
* `text`: If you set `event_message.data.text_data`, the implicit is `text`. `text_data` should be a string. The event handler receives a UTF-8-encoded string;
130
+
* `text`: When you set `event_message.data.text_data`, the implicit `dataType` is `text`. The `text_data` value should be a string. The event handler receives a UTF-8-encoded string.
131
131
132
-
* `binary`: If you set `event_message.data.binary_data`, the implicit is `binary`. `binary_data` should be a byte array. The event handler receives the raw binary frame.
132
+
* `binary`: When you set `event_message.data.binary_data`, the implicit `dataType` is `binary`. The `binary_data` value should be a byte array. The event handler receives the simple WebSocket binary frame.
133
133
134
134
#### Case 1: Send an event with text data
135
135
136
136
Set `event_message.data.text_data` to `"text data"`.
137
137
138
-
The upstream event handler receives a request that's similar to the following. Note that `Content-Type` for the CloudEvents HTTP request is `text/plain`, where `dataType`=`text`.
138
+
The upstream event handler receives a request similar to:
139
139
140
140
```HTTP
141
141
POST /upstream HTTP/1.1
@@ -158,6 +158,8 @@ text data
158
158
159
159
```
160
160
161
+
The `Content-Type` for the CloudEvents HTTP request is `text/plain`, where `dataType`=`text`.
162
+
161
163
#### Case 2: Send an event with protobuf data
162
164
163
165
Assume that you've received the following customer message:
@@ -170,7 +172,7 @@ message MyMessage {
170
172
171
173
Set `event_message.data.protobuf_data` to `any.pack(MyMessage)` with `value = 1`
172
174
173
-
The upstream event handler receives a request that's similar to the following. Note that the `Content-Type` for the CloudEvents HTTP request is `application/x-protobuf`, where `dataType`=`protobuf`.
175
+
The upstream event handler receives a request that's similar to:
The `Content-Type` for the CloudEvents HTTP request is `application/x-protobuf`, where `dataType`=`protobuf`.
199
+
196
200
The data is a valid protobuf binary. You can use the following `proto` and `any.unpack()` to deserialize it:
197
201
198
202
```protobuf
@@ -207,7 +211,7 @@ message MyMessage {
207
211
208
212
Set `send_to_group_message.binary_data` to `[1, 2, 3]`.
209
213
210
-
The upstream event handler receives a request similar to the following. For `dataType`=`binary`, the `Content-Type` for the CloudEvents HTTP request is `application/octet-stream`.
214
+
The upstream event handler receives a request similar to:
211
215
212
216
```HTTP
213
217
POST /upstream HTTP/1.1
@@ -229,7 +233,6 @@ ce-eventName: <event_name>
229
233
// Just show in hexadecimal; you need to read it as binary
230
234
01 02 03
231
235
```
232
-
233
-
The WebSocket frame can be in `text` format for text message frames or UTF-8-encoded binaries for `binary` message frames.
236
+
For `dataType`=`binary`, the `Content-Type` for the CloudEvents HTTP request is `application/octet-stream`. The WebSocket frame can be in `text` format for text message frames or UTF-8-encoded binaries for `binary` message frames.
234
237
235
238
The service declines the client if the message doesn't match the prescribed format.
Copy file name to clipboardExpand all lines: articles/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol.md
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ This document describes the subprotocol json.reliable.webpubsub.azure.v1.
17
17
> [!NOTE]
18
18
> Reliable protocols are still in preview. Some changes are expected in the future.
19
19
20
-
When Websocket client connections drop due to intermittent network issues, messages can be lost. In a pub/sub system, publishers are decoupled from subscribers and may not detect a subscribers' dropped connection or message loss.
20
+
When WebSocket client connections drop due to intermittent network issues, messages can be lost. In a pub/sub system, publishers are decoupled from subscribers and may not detect a subscribers' dropped connection or message loss.
21
21
22
22
To overcome intermittent network issues and maintain reliable message delivery, you can use the Azure WebPubSub `json.reliable.webpubsub.azure.v1` subprotocol to create a *Reliable PubSub WebSocket client*.
23
23
@@ -85,9 +85,9 @@ The client implementation SHOULD always check if the `success` is `true` or `fal
85
85
86
86
### Message response
87
87
88
-
Clients can receive messages published from one group the client joined, or from the server management role that the server sends messages to the specific client or the specific user.
88
+
Clients can receive messages published from a group the client has joined, or from the server that sends messages to a specific client or user.
89
89
90
-
1.When the message is from a group
90
+
1.The response message from a group:
91
91
92
92
```json
93
93
{
@@ -101,7 +101,7 @@ Clients can receive messages published from one group the client joined, or from
101
101
}
102
102
```
103
103
104
-
1. When The message is from the server.
104
+
1. The response message from the server:
105
105
106
106
```json
107
107
{
@@ -145,7 +145,7 @@ Clients can receive messages published from one group the client joined, or from
145
145
}
146
146
```
147
147
148
-
If the REST API is sending a string `Hello World` using `application/json` content type, what the simple WebSocket client receives is a JSON string, which is `"Hello World"` that wraps the string with `"`.
148
+
If the REST API is sending a string `Hello World` using `application/json` content type, the simple WebSocket client receives the JSON string`"Hello World"` wrapped in `"`.
149
149
150
150
#### Case 3: Sending binary data to the connection through REST API with `Content-Type`=`application/octet-stream`
151
151
@@ -164,11 +164,11 @@ If the REST API is sending a string `Hello World` using `application/json` conte
164
164
165
165
### System response
166
166
167
-
The Web PubSub service can also send system-related responses to the client.
167
+
The Web PubSub service can return system-related responses to the client.
168
168
169
169
#### Connected
170
170
171
-
When the connection connects to service.
171
+
The response to the client connect request:
172
172
173
173
```json
174
174
{
@@ -190,7 +190,7 @@ Find more details in [Reconnection](./howto-develop-reliable-clients.md#reconnec
190
190
191
191
#### Disconnected
192
192
193
-
The response when the server closes the connection or when the service declines the client connection.
193
+
The response when the server closes the connection or when the service declines the client connection:
Copy file name to clipboardExpand all lines: articles/azure-web-pubsub/reference-json-webpubsub-subprotocol.md
+12-10Lines changed: 12 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,29 +5,32 @@ author: vicancy
5
5
ms.author: lianwei
6
6
ms.service: azure-web-pubsub
7
7
ms.topic: reference
8
-
ms.date: 01/06/2023
8
+
ms.date: 01/09/2023
9
9
---
10
10
11
11
# Azure Web PubSub supported JSON WebSocket subprotocol
12
12
13
-
The JSON WebSocket subprotocol, `json.webpubsub.azure.v1`, enables the exchange of publish/subscribe messages directly between clients. A WebSocket connection using the `json.webpubsub.azure.v1` subprotocol is called a PubSub WebSocket client.
13
+
The JSON WebSocket subprotocol, `json.webpubsub.azure.v1`, enables the exchange of publish/subscribe messages directly between clients. A WebSocket connection using the `json.webpubsub.azure.v1` subprotocol is called a *PubSub WebSocket client*.
14
14
15
-
This document describes the subprotocol `json.webpubsub.azure.v1`.
16
15
17
16
## Overview
18
17
19
-
In a simple native WebSocket client, a *server* role is required to handle events from clients. A simple WebSocket connection triggers a `message` event when it sends messages, and relies on the server-side to process messages and do other operations.
18
+
In a simple WebSocket client, a *server* role is required to handle events from clients. A simple WebSocket connection triggers a `message` event when it sends messages and relies on the server-side to process messages and do other operations.
20
19
21
-
When you use the `json.webpubsub.azure.v1` subprotocol, an authorized client can join a group using [join requests](#join-groups) and publish messages directly to a group using [publish requests](#publish-messages). The client can also route messages directly to upstream event handlers using [event requests](#send-custom-events).
20
+
With the `json.webpubsub.azure.v1` subprotocol, you can create *PubSub WebSocket clients* that can:
22
21
23
-
In JavaScript, a PubSub WebSocket client can be created using:
22
+
* join a group using [join requests](#join-groups).
23
+
* publish messages directly to a group using [publish requests](#publish-messages).
24
+
* route messages directly to upstream event handlers using [event requests](#send-custom-events).
25
+
26
+
For example, you can create a *PubSub WebSocket client* with the following JavaScript code:
24
27
25
28
```javascript
26
29
// PubSub WebSocket client
27
30
var pubsub =newWebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
28
31
```
29
32
30
-
The following information describes the subprotocol requests and responses. Both incoming and outgoing data frames must contain JSON payloads.
33
+
This document describes the subprotocol`json.webpubsub.azure.v1` requests and responses. Both incoming and outgoing data frames must contain JSON payloads.
0 commit comments