update

Author: Y-Sindo

articles/azure-web-pubsub/howto-connect-mqtt-websocket-client.md

@@ -10,12 +10,24 @@ ms.topic: how-to
 
 # How To Connect MQTT Clients to Web PubSub
 
-MQTT is a lightweight pub/sub messaging protocol designed for devices with limited resources.
+MQTT is a lightweight pub/sub messaging protocol designed for devices with constrained resources.
 
 In this article, we introduce how to connect MQTT clients to the service, so that the clients can publish and subscribe messages.
 
 ## Connection Parameters
 
+WebSocket connection URI: `wss://{serviceName}.webpubsub.azure.com/clients/mqtt/hubs/{hub}?access_token={token}`.
+
+* {hub} is a mandatory parameter that provides isolation for different applications.
+* {token} is required by default. Alternatively, you can include the token in the `Authorization` header in the format `Bearer {token}`. You can bypass the token requirement by enabling anonymous access to the hub. <!--TODO MQTT allow anonymous access to the hub-->
+
+If client library doesn't accept a URI, then you probably need to split the information in the URI into multiple parameters:
+
+* Host: `{serviceName}.webpubsub.azure.com`
+* Path: `/clients/mqtt/hubs/{hub}?access_token={token}`
+* Port: 443
+* Transport: WebSockets with [TLS](https://wikipedia.org/wiki/Transport_Layer_Security).
+
 [!INCLUDE [MQTT-Connection-Parameters](includes/mqtt-connection-Parameters.md)]
 
 By default MQTT clients don't have any permissions to publish or subscribe to any topics. You need to grant [permissions](#permissions) to MQTT clients.
@@ -61,9 +73,49 @@ You could also configure properties for the client connection when generating th
 
 You could also add custom claims into the access token, and these values are preserved as the `claims` property in [connect upstream request body](./reference-mqtt-cloud-events.md#system-connect-event).
 
-[Server SDKs](./howto-generate-client-access-url.md#generate-from-service-sdk) provides APIs to generate the access token for the clients.
+[Server SDKs](./howto-generate-client-access-url.md#generate-from-service-sdk) provides APIs to generate the access token for MQTT clients. Note that you must specify the client protocol to `Mqtt`.
+
+# [JavaScript](#tab/javascript)
+
+1. Follow [Getting started with server SDK](./reference-server-sdk-js.md#getting-started) to create a `WebPubSubServiceClient` object `service`
+
+2. Generate Client Access URL by calling `WebPubSubServiceClient.getClientAccessToken`:
+
+     ```js
+     let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });
+     ```
+
+# [C#](#tab/csharp)
+
+1. Follow [Getting started with server SDK](./reference-server-sdk-csharp.md#getting-started) to create a `WebPubSubServiceClient` object `service`
+
+2. Generate Client Access URL by calling `WebPubSubServiceClient.GetClientAccessUri`:
+
+     ```csharp
+     var url = service.GetClientAccessUri(clientProtocol: WebPubSubClientProtocol.Mqtt);
+     ```
+
+# [Python](#tab/python)
+
+1. Follow [Getting started with server SDK](./reference-server-sdk-python.md#install-the-package) to create a `WebPubSubServiceClient` object `service`
+
+2. Generate Client Access URL by calling `WebPubSubServiceClient.get_client_access_token`:
+
+     ```python
+     token = service.get_client_access_token(client_protocol="MQTT")
+     ```
+
+# [Java](#tab/java)
+
+1. Follow [Getting started with server SDK](./reference-server-sdk-java.md#getting-started) to create a `WebPubSubServiceClient` object `service`
+
+2. Generate Client Access URL by calling `WebPubSubServiceClient.getClientAccessToken`:
 
-<!--TODO Give a simple sample for each language here, and also add link to the generation link-->
+     ```java
+     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
+     option.setWebPubSubClientAccess(WebPubSubClientProtocol.MQTT);
+     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
+     ```
 
 ### 2. Upstream Server Workflow
 

articles/azure-web-pubsub/howto-generate-client-access-url.md

@@ -38,6 +38,12 @@ The same Client Access URL can be generated by using the Web PubSub server SDK.
 
 2. Generate Client Access URL by calling `WebPubSubServiceClient.getClientAccessToken`:
 
+   - Generate MQTT client access token
+
+     ```js
+     let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });
+     ```
+
    - Configure user ID
 
      ```js
@@ -82,6 +88,12 @@ The same Client Access URL can be generated by using the Web PubSub server SDK.
 
 2. Generate Client Access URL by calling `WebPubSubServiceClient.GetClientAccessUri`:
 
+   - Generate MQTT client access token
+
+     ```csharp
+     var url = service.GetClientAccessUri(clientProtocol: WebPubSubClientProtocol.Mqtt);
+     ```
+
    - Configure user ID
 
      ```csharp
@@ -118,6 +130,12 @@ The same Client Access URL can be generated by using the Web PubSub server SDK.
 
 2. Generate Client Access URL by calling `WebPubSubServiceClient.get_client_access_token`:
 
+   - Generate MQTT client access token
+
+     ```python
+     token = service.get_client_access_token(client_protocol="MQTT")
+     ```
+
    - Configure user ID
 
      ```python
@@ -154,7 +172,15 @@ The same Client Access URL can be generated by using the Web PubSub server SDK.
 
 2. Generate Client Access URL by calling `WebPubSubServiceClient.getClientAccessToken`:
 
-   - Configure user ID
+   - Generate MQTT client access token
+
+     ```java
+     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
+     option.setWebPubSubClientAccess(WebPubSubClientProtocol.MQTT);
+     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
+     ```
+
+    - Configure user ID
 
      ```java
      GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
@@ -209,7 +235,7 @@ You can enable Microsoft Entra ID in your service and use the Microsoft Entra to
    > [!NOTE]
    > Please use the latest version of Postman. Old versions of Postman have [some issue](https://github.com/postmanlabs/postman-app-support/issues/3994#issuecomment-893453089) supporting colon `:` in path.
 
-   1. For the URI, enter `https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2024-01-01`. For MQTT clients, append query parameter `&clientType=mqtt` to the URL.
+   1. For the URI, enter `https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2024-01-01`. If you'd like to generate token for MQTT clients, append query parameter `&clientType=mqtt` to the URL.
    2. On the **Auth** tab, select **Bearer Token** and paste the Microsoft Entra token fetched in the previous step
    3. Select **Send** and you see the Client Access Token in the response:
 

articles/azure-web-pubsub/includes/mqtt-connection-parameters.md

@@ -6,18 +6,6 @@ ms.topic: include
 ms.date: 06/22/2024
 ---
 
-WebSocket connection URI: `wss://{serviceName}.webpubsub.azure.com/clients/mqtt/hubs/{hub}?access_token={token}`.
-
-* {hub} is a mandatory parameter that provides isolation for different applications.
-* {token} is required by default. Alternatively, you can include the token in the `Authorization` header in the format `Bearer {token}`. You can bypass the token requirement by enabling anonymous access to the hub. <!--TODO MQTT allow anonymous access to the hub-->
-
-If client library doesn't accept a URI, then you probably need to split the information in the URI into multiple parameters:
-
-* Host: `{serviceName}.webpubsub.azure.com`
-* Path: `/clients/mqtt/hubs/{hub}?access_token={token}`
-* Port: 443
-* Transport: WebSockets with [TLS](https://wikipedia.org/wiki/Transport_Layer_Security).
-
 There are some limitations you should follow in your [MQTT](https://mqtt.org/mqtt-specification/) clients, otherwise the connection will be rejected. These MQTT protocol parameters include:
 * Protocol versions: 3.1.1 or 5.0.
 * Client ID format

articles/azure-web-pubsub/media/quickstarts-pubsub-among-mqtt-clients/portal-mqtt-client-access-uri-generation.png

@@ -24,9 +24,9 @@ You can use MQTT protocols in Web PubSub service for the following scenarios:
 
 **Standard MQTT Protocols Support**:
 
-Web PubSub service supports MQTT 3.1.1 and 5.0 protocols in a standard way that any MQTT SDK that support WebSocket transport can connect to Web PubSub. Users who wish to use Web PubSub in a programming language that doesn't have a native Web PubSub SDK can still connect and communicate using MQTT.
+Web PubSub service supports MQTT 3.1.1 and 5.0 protocols in a standard way that any MQTT SDK with WebSocket transport support can connect to Web PubSub. Users who wish to use Web PubSub in a programming language that doesn't have a native Web PubSub SDK can still connect and communicate using MQTT.
 
-**Communication Between Various Protocols**:
+**Cross-Protocol Communication**:
 
 MQTT clients can communicate with clients of other Web PubSub protocols. Find more details [here](./reference-mqtt-cross-protocol-communication.md)
 

articles/azure-web-pubsub/overview-mqtt.md

@@ -24,7 +24,7 @@ This quickstart guide demonstrates how to
 - Install the dependencies for the language you plan to use
 
 > [!NOTE]
-> Except for the MQTT client libraires mentioned belows, you can choose any standard MQTT client libraries that meet the following requirements to connect to Web PubSub:
+> Except for the MQTT client libraries mentioned belows, you can choose any standard MQTT client libraries that meet the following requirements to connect to Web PubSub:
 > 1. Support WebSocket transport.
 > 2. Support MQTT protocol 3.1.1 or 5.0.
 
@@ -62,21 +62,17 @@ pip install paho-mqtt
 
 ## Connect to Web PubSub
 
-[!INCLUDE [MQTT-Connection-Parameters](includes/mqtt-connection-Parameters.md)]
+An MQTT uses a **Client Access URL** to connect and authenticate with your resource. This URL follows a pattern of `wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>`.
 
-A client can have a few ways to obtain the Client Access URL. For this quick start, you generate the access token with a CLI tool. It's best practice to not hard code the Client Access URL in your code. In the production world, we usually set up an app server to return this URL on demand. [Generate Client Access URL](./howto-generate-client-access-url.md) describes the practice in detail.
+A client can have a few ways to obtain the Client Access URL. It's best practice to not hard code the Client Access URL in your code. In the production world, we usually set up an app server to return this URL on demand. [Generate Client Access URL](./howto-generate-client-access-url.md) describes the practice in detail.
 
-<!--TODO Replace with portal token generation tool after it's implemented-->
+For this quick start, you can copy and paste one from Azure portal shown in the following diagram.
 
-```powershell
-npm install -g jwtgen
-jwtgen -a HS256 -s "{webpubsub_access_key}" -c "aud=wss://{service_name}.webpubsub.azure.com/clients/mqtt/hubs/{hub_name}"  -c 'role=["webpubsub.sendToGroup","webpubsub.joinLeaveGroup"]'  -e 3600000
-```
+![The diagram shows how to get MQTT client access url.](./media/quickstarts-pubsub-among-mqtt-clients/portal-mqtt-client-access-uri-generation.png)
 
-> [!NOTE]
-> This step will be replaced by the client generation tool on Azure Portal once it's implemented. If you're using other shells, make sure each element of the roles surrounded by double quotation marks.
+As shown in the preceding code, the client has the permissions to send messages to topic `group1` and to subscribe to topic `group2`.
 
-As shown in the preceding code, the client has the permissions to send messages to and subscribe to any topic.
+[!INCLUDE [MQTT-Connection-Parameters](includes/mqtt-connection-Parameters.md)]
 
 The following code shows how to connect MQTT clients to WebPubSub with MQTT protocol version 5.0, clean start, 30-seconds session expiry interval.
 
@@ -159,7 +155,7 @@ To receive messages from topics, the client
 - must subscribe to the topic it wishes to receive messages from
 - has a callback to handle message event
 
-The following code shows a client subscribes to topics named `topic1`.
+The following code shows a client subscribes to topics named `group2`.
 
 # [JavaScript](#tab/javascript)
 
@@ -168,11 +164,11 @@ The following code shows a client subscribes to topics named `topic1`.
 
 // Provide callback to the message event.
 client.on("message", async (topic, payload, packet) => {
-    concole.log(topic, payload)
+    console.log(topic, payload)
 });
 
-// Subscribe to a topic "topic".
-client.subscribe("topic1", { qos: 1 }, (err, granted) => { console.log("subscribe", granted); })
+// Subscribe to a topic.
+client.subscribe("group2", { qos: 1 }, (err, granted) => { console.log("subscribe", granted); })
 
 ```
 
@@ -182,13 +178,13 @@ client.subscribe("topic1", { qos: 1 }, (err, granted) => { console.log("subscrib
 // ...code from the last step
 
 // Provide callback to the message event.
-mqttClient.ApplicationMessageReceivedAsync += (args) =>
+client.ApplicationMessageReceivedAsync += (args) =>
 {
     Console.WriteLine($"Received message on topic '{args.ApplicationMessage.Topic}': {System.Text.Encoding.UTF8.GetString(args.ApplicationMessage.PayloadSegment)}");
     return Task.CompletedTask;
 };
 // Subscribe to a topic "topic".
-await mqttClient.SubscribeAsync("topic1", MQTTnet.Protocol.MqttQualityOfServiceLevel.AtLeastOnce);
+await client.SubscribeAsync("group2", MQTTnet.Protocol.MqttQualityOfServiceLevel.AtLeastOnce);
 ```
 
 # [Python](#tab/python)
@@ -202,7 +198,7 @@ def subscriber_on_message(client, userdata, msg):
 client.on_message = subscriber_on_message
 
 # Subscribe to a topic "topic".
-client.subscribe("topic1")
+client.subscribe("group2")
 
 # Blocking call that processes network traffic, dispatches callbacks and
 # handles reconnecting.
@@ -214,33 +210,33 @@ client.loop_forever()
 ---
 
 ## Publish a message to a group
-In the previous step, we've set up everything needed to receive messages from `topic1`, now we send messages to that group.
+In the previous step, we've set up everything needed to receive messages from `group1`, now we send messages to that group.
 
 # [JavaScript](#tab/javascript)
 
 ```javascript
 // ...code from the last step
 
-// Send message "Hello World" in the "text" format to "topic1".
-client.publish("topic1", "Hello World!")
+// Send message "Hello World" in the "text" format to "group1".
+client.publish("group1", "Hello World!")
 ```
 
 # [C#](#tab/csharp)
 
 ```csharp
 // ...code from the last step
 
-// Send message "Hello World" in the "text" format to "topic1".
-await client.PublishStringAsync("topic1", "Hello World!");
+// Send message "Hello World" in the "text" format to "group1".
+await client.PublishStringAsync("group1", "Hello World!");
 ```
 
 # [Python](#tab/python)
 
 ```python
 # ...code from the last step
 
-# Send message "Hello World" in the "text" format to "topic1".
-client.publish("topic1", "Hello World!")
+# Send message "Hello World" in the "text" format to "group1".
+client.publish("group1", "Hello World!")
 ```
 ---