Skip to content

Commit 320191b

Browse files
committed
more edits
1 parent db2db65 commit 320191b

File tree

5 files changed

+48
-43
lines changed

5 files changed

+48
-43
lines changed

articles/azure-web-pubsub/includes/reference-json-requests.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ Format:
8080
}
8181
```
8282

83-
* The raw clients in `<group_name>` receive the string `text data`.
83+
* The simple WebSocket clients in `<group_name>` receive the string `text data`.
8484

8585
#### Case 2: publish JSON data:
8686

@@ -109,7 +109,7 @@ Format:
109109
}
110110
```
111111

112-
* The raw clients in `<group_name>` receive the serialized string `{"hello": "world"}`.
112+
* The simple WebSocket clients in `<group_name>` receive the serialized string `{"hello": "world"}`.
113113

114114
#### Case 3: publish binary data:
115115

@@ -135,7 +135,7 @@ Format:
135135
}
136136
```
137137

138-
* The raw clients in `<group_name>` receive the **binary** data in the binary frame.
138+
* The simple WebSocket clients in `<group_name>` receive the **binary** data in the binary frame.
139139

140140
### Send custom events
141141

articles/azure-web-pubsub/includes/reference-permission.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ ms.date: 08/06/2021
88

99
## Permissions
1010

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:
1212

1313
| Role | Permission |
1414
|---|---|
@@ -18,4 +18,4 @@ A Web PubSub WebSocket client can only publish to other clients when it's author
1818
| `webpubsub.joinLeaveGroup.<group>` | The client can join/leave the group `<group>`.
1919
| `webpubsub.sendToGroup.<group>` | The client can publish messages to the group `<group>`.
2020

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.

articles/azure-web-pubsub/includes/reference-protobuf-requests.md

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -18,23 +18,23 @@ Set `leave_group_message.group` to the group name.
1818

1919
Format:
2020

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)
2222

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.
2424

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.
2626

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.
2828

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.
3030

3131
#### Case 1: Publish text data
3232

3333
Set `send_to_group_message.group` to `group`, and set `send_to_group_message.data.text_data` to `"text data"`.
3434

3535
* The protobuf subprotocol client in group `group` receives the binary frame and can use [DownstreamMessage](#responses) to deserialize it.
3636

37-
* The JSON subprotocol client in group `group` receives:
37+
* The JSON subprotocol clients in `group` receive:
3838

3939
```json
4040
{
@@ -46,11 +46,11 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
4646
}
4747
```
4848

49-
* The raw client in group `group` receives string `text data`.
49+
* The simple WebSocket clients in `group` receive string `text data`.
5050

5151
#### Case 2: Publish protobuf data
5252

53-
Let's assume that you have a customer message:
53+
Let's assume that you have a custom message:
5454

5555
```
5656
message MyMessage {
@@ -60,9 +60,9 @@ message MyMessage {
6060
6161
Set `send_to_group_message.group` to `group` and `send_to_group_message.data.protobuf_data` to `Any.pack(MyMessage)` with `value = 1`.
6262
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.
6464
65-
* The subprotocol client in group `group` receives:
65+
* The subprotocol client in `group` receives:
6666
6767
```json
6868
{
@@ -87,7 +87,7 @@ message MyMessage {
8787
}
8888
```
8989

90-
* The raw client in group `group` receives the binary frame:
90+
* The simple WebSocket clients in `group` receive the binary frame:
9191

9292
```
9393
# Show in hexadecimal
@@ -114,7 +114,7 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
114114
115115
Because the JSON subprotocol client supports only text-based messaging, the binary is always Base64-encoded.
116116
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:
118118
119119
```
120120
# Show in hexadecimal
@@ -125,17 +125,17 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
125125
126126
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.
127127
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.
129129
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.
131131
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.
133133
134134
#### Case 1: Send an event with text data
135135
136136
Set `event_message.data.text_data` to `"text data"`.
137137
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:
139139
140140
```HTTP
141141
POST /upstream HTTP/1.1
@@ -158,6 +158,8 @@ text data
158158
159159
```
160160

161+
The `Content-Type` for the CloudEvents HTTP request is `text/plain`, where `dataType`=`text`.
162+
161163
#### Case 2: Send an event with protobuf data
162164

163165
Assume that you've received the following customer message:
@@ -170,7 +172,7 @@ message MyMessage {
170172

171173
Set `event_message.data.protobuf_data` to `any.pack(MyMessage)` with `value = 1`
172174

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:
174176

175177
```HTTP
176178
POST /upstream HTTP/1.1
@@ -193,6 +195,8 @@ ce-eventName: <event_name>
193195
0A 2F 74 79 70 65 2E 67 6F 6F 67 6C 65 61 70 69 73 2E 63 6F 6D 2F 61 7A 75 72 65 2E 77 65 62 70 75 62 73 75 62 2E 54 65 73 74 4D 65 73 73 61 67 65 12 02 08 01
194196
```
195197

198+
The `Content-Type` for the CloudEvents HTTP request is `application/x-protobuf`, where `dataType`=`protobuf`.
199+
196200
The data is a valid protobuf binary. You can use the following `proto` and `any.unpack()` to deserialize it:
197201

198202
```protobuf
@@ -207,7 +211,7 @@ message MyMessage {
207211

208212
Set `send_to_group_message.binary_data` to `[1, 2, 3]`.
209213

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:
211215

212216
```HTTP
213217
POST /upstream HTTP/1.1
@@ -229,7 +233,6 @@ ce-eventName: <event_name>
229233
// Just show in hexadecimal; you need to read it as binary
230234
01 02 03
231235
```
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.
234237

235238
The service declines the client if the message doesn't match the prescribed format.

articles/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ This document describes the subprotocol json.reliable.webpubsub.azure.v1.
1717
> [!NOTE]
1818
> Reliable protocols are still in preview. Some changes are expected in the future.
1919
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.
2121

2222
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*.
2323

@@ -85,9 +85,9 @@ The client implementation SHOULD always check if the `success` is `true` or `fal
8585

8686
### Message response
8787

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.
8989

90-
1. When the message is from a group
90+
1. The response message from a group:
9191

9292
```json
9393
{
@@ -101,7 +101,7 @@ Clients can receive messages published from one group the client joined, or from
101101
}
102102
```
103103

104-
1. When The message is from the server.
104+
1. The response message from the server:
105105

106106
```json
107107
{
@@ -145,7 +145,7 @@ Clients can receive messages published from one group the client joined, or from
145145
}
146146
```
147147

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 `"`.
149149

150150
#### Case 3: Sending binary data to the connection through REST API with `Content-Type`=`application/octet-stream`
151151

@@ -164,11 +164,11 @@ If the REST API is sending a string `Hello World` using `application/json` conte
164164

165165
### System response
166166

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.
168168

169169
#### Connected
170170

171-
When the connection connects to service.
171+
The response to the client connect request:
172172

173173
```json
174174
{
@@ -190,7 +190,7 @@ Find more details in [Reconnection](./howto-develop-reliable-clients.md#reconnec
190190

191191
#### Disconnected
192192

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:
194194

195195
```json
196196
{

articles/azure-web-pubsub/reference-json-webpubsub-subprotocol.md

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,32 @@ author: vicancy
55
ms.author: lianwei
66
ms.service: azure-web-pubsub
77
ms.topic: reference
8-
ms.date: 01/06/2023
8+
ms.date: 01/09/2023
99
---
1010

1111
# Azure Web PubSub supported JSON WebSocket subprotocol
1212

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*.
1414

15-
This document describes the subprotocol `json.webpubsub.azure.v1`.
1615

1716
## Overview
1817

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.
2019

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:
2221

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:
2427

2528
```javascript
2629
// PubSub WebSocket client
2730
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');
2831
```
2932

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.
3134

3235
[!INCLUDE [reference-permission](includes/reference-permission.md)]
3336

@@ -37,7 +40,7 @@ var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'j
3740

3841
## Responses
3942

40-
Messages received by the client can be `ack`, `message`, and `system`:
43+
Message types received by the client can be:
4144

4245
* ack - The response to a request containing an `ackId`.
4346
* message - Messages from the group or server.
@@ -93,7 +96,6 @@ Clients can receive messages published from a group the client has joined or fro
9396

9497
#### Case 1: Sending data `Hello World` to the connection through REST API with `Content-Type`=`text/plain`
9598

96-
9799
* A simple WebSocket client receives a text WebSocket frame with data: `Hello World`;
98100
* A PubSub WebSocket client receives:
99101

@@ -144,7 +146,7 @@ The Web PubSub service sends system related responses to client requests.
144146

145147
#### Connected
146148

147-
The responses when the client connects to service.
149+
The response to the client connect request:
148150

149151
```json
150152
{

0 commit comments

Comments
 (0)