Skip to content

Commit d88e690

Browse files
kevinguo-edkevinguo-ed
authored
Updated MQTT overview
1 parent fcdb18d commit d88e690

File tree

2 files changed

+55
-95
lines changed

2 files changed

+55
-95
lines changed

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

Lines changed: 19 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,129 +1,53 @@
11
---
22
title: MQTT support in Azure Web PubSub service
3-
description: Get an overview of Azure Web PubSub's support for the MQTT protocols, understand typical use case scenarios to use MQTT in Azure Web PubSub, and learn the key benefits of MQTT in Azure Web PubSub.
3+
description: Get an overview of Azure Web PubSub's support for the MQTT protocols, understand typical use case scenarios of when to use MQTT in Azure Web PubSub, and learn the key benefits of MQTT in Azure Web PubSub.
44
keywords: MQTT, MQTT on Azure Web PubSub, MQTT over WebSocket
55
author: Y-Sindo
66
ms.author: zityang
7-
ms.date: 07/15/2024
7+
ms.date: 10/17/2024
88
ms.service: azure-web-pubsub
99
ms.topic: overview
1010
---
1111
# Overview: MQTT in Azure Web PubSub service (Preview)
1212

13-
[MQTT](https://mqtt.org/) is a lightweight pub/sub messaging protocol designed for devices with constrained resources. Azure Web PubSub service now natively supports MQTT over WebSocket transport.
14-
15-
You can use MQTT protocols in Web PubSub service for the following scenarios:
13+
> [!NOTE]
14+
> MQTT support in Azure Web PubSub is in preview stage.
1615
17-
* Pub/Sub among MQTT clients and Web PubSub native clients.
18-
* Broadcast messages to MQTT clients.
19-
* Get notifications for MQTT client lifetime events.
16+
[MQTT](https://mqtt.org/) is a lightweight pub/sub messaging protocol designed for devices with constrained resources. Azure Web PubSub service now natively supports MQTT over WebSocket transport, enabling cross-communication between MQTT web clients and other Web PubSub clients
2017

2118
This new capability addresses two key use cases:
2219

23-
1. Real-time applications with mixed protocols: You can allow clients using different real-time protocols to exchange data through the Azure Web PubSub service.
20+
1. Real-time applications with mixed protocols: You can allow clients using different protocols to exchange data in real-time through Azure Web PubSub service.
2421

25-
2. Support for additional programming languages: You can use any MQTT library to connect with the service, making it possible to integrate with applications written in languages like C++, beyond the existing SDKs in C#, JavaScript, Python, and Java.
22+
2. Support for additional programming languages: You can use any MQTT library to connect with the service, making it possible to integrate with applications written in languages like C++, beyond the available SDKs in C#, JavaScript, Python, and Java.
2623

27-
It’s important to note that this MQTT integration is a lightweight adaptation of the MQTT protocol and extends only to the features already supported by Azure Web PubSub. Some MQTT features that are not supported include:
24+
It’s important to note that this MQTT support is a lightweight adaptation of the MQTT protocol and extends only to the features already supported by Azure Web PubSub. Some MQTT features that are not supported include:
2825

2926
- Wildcard subscriptions
3027
- Retained messages
3128
- Shared subscriptions
32-
For a more comprehensive MQTT broker solution on Azure, we recommend exploring [Azure Event Grid](../event-grid/overview.md).
33-
34-
> [!NOTE]
35-
> MQTT support in Azure Web PubSub is in preview stage.
36-
37-
## Key features
38-
39-
### Standard MQTT protocols support
40-
41-
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.
42-
43-
### Cross-protocol communication
44-
45-
MQTT web clients can communicate with clients of other Web PubSub protocols. Find more details [here](./reference-mqtt-cross-protocol-communication.md)
46-
47-
### Easy MQTT adoption for current Azure Web PubSub users
48-
49-
Current users of Azure Web PubSub can use MQTT protocol with minimal modifications to their existing upstream servers. The Web PubSub REST API is already equipped to handle MQTT connections, simplifying the transition process.
50-
51-
### Client-to-server request/response model
52-
53-
In addition to the client-to-client pub/sub model provided by the MQTT protocols, Web PubSub also support a client-to-server request/response model. Basically Web PubSub converts a specific kind of MQTT application messages into HTTP requests to registered webhooks, and sends the HTTP responses as application messages back to the MQTT clients.
54-
55-
For more details, see [MQTT custom event handler protocol](./reference-mqtt-cloud-events.md#user-custom_event-event).
56-
57-
## MQTT feature support status
58-
59-
Web PubSub support MQTT protocol version 3.1.1 and 5.0. The supported features include but not limited to:
60-
61-
* All the levels of Quality Of Service including at most once, at least once and exactly once.
62-
* Persistent session. MQTT sessions are preserved for up to 30 seconds when client connections are interrupted.
63-
* Last Will & Testament
64-
* Client Certificate Authentication
29+
- Topic alias
6530

66-
### Additional features supported for MQTT 5.0
31+
For a comprehensive list of what MQTT features are supported, read [this documentaion article](./reference-mqtt-support-status.md).
6732

68-
* Message Expiry Interval and Session Expiry Interval
69-
* Subscription Identifier.
70-
* Assigned Client ID.
71-
* Flow Control
72-
* Server-Sent Disconnect
33+
For a more comprehensive MQTT broker solution on Azure, we recommend exploring [Azure Event Grid](../event-grid/overview.md).
7334

74-
### Not supported feature
35+
## Real-time data exchange patterns enabled by the MQTT support
36+
- Pub/Sub among MQTT web clients and Web PubSub native clients
37+
- Broadcast messages to MQTT web clients
38+
- Receive notifications for lifetime events of MQTT web client
7539

76-
* Wildcard subscription
77-
* Retained messages
78-
* Topic alias
79-
* Shared subscription
40+
Each data exchange pattern has a how-to guide. Refer to them to get started.
8041

8142
## How MQTT is adapted into Web PubSub's system
8243

83-
This section assumes you have basic knowledge about MQTT protocols and Web PubSub. You can find the definitions of MQTT terms in [MQTT V5.0.0 Spec](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901003). You can also learn basic concepts of Web PubSub in [Basic Concepts](./key-concepts.md).
44+
> [!NOTE]
45+
> This section assumes you have basic knowledge about MQTT protocols and Azure Web PubSub.
8446
85-
The following table shows similar or equivalent term mappings between MQTT and Web PubSub. It helps you understand how we adapt MQTT concepts into the Web PubSub's system. It's essential if you want to use the [data-plane REST API](./reference-rest-api-data-plane.md) or [client event handlers](./howto-develop-eventhandler.md) to interact with MQTT clients.
47+
Azure Web PubSub service now recognizes MQTT messages and translates them to its native protocols. The following table shows similar or equivalent term mappings between MQTT and Web PubSub. It helps you understand how we adapt MQTT concepts into the concepts found in Web PubSub It's essential if you want to use the [data-plane REST API](./reference-rest-api-data-plane.md) or [client event handlers](./howto-develop-eventhandler.md) to interact with MQTT clients.
8648

8749
[!INCLUDE [MQTT-Term-Mappings](includes/mqtt-term-mappings.md)]
8850

89-
## Client authentication and authorization
90-
91-
In general, a server to authenticate and authorize MQTT clients is required. There are two workflows supported by Web PubSub to authenticate and authorize MQTT clients.
92-
93-
* Workflow 1: The MQTT client gets a [JWT(JSON Web Token)](https://jwt.io) from somewhere with its credential, usually from an auth server. Then the client includes the token in the WebSocket upgrading request to the Web PubSub service, and the Web PubSub service validates the token and auth the client. This workflow is enabled by default.
94-
95-
![Diagram of MQTT Auth Workflow With JWT.](./media/howto-connect-mqtt-websocket-client/mqtt-jwt-auth-workflow.png)
96-
97-
* Workflow 2: The MQTT client sends an MQTT CONNECT packet after it establishes a WebSocket connection with the service, then the service calls an API in the upstream server. The upstream server can auth the client according to the username and password fields in the MQTT connection request, and the TLS certificate from the client. This workflow needs explicit configuration.
98-
<!--Add link to tutorial and configuration-->
99-
100-
![Diagram of MQTT Auth Workflow With Upstream Server.](./media/howto-connect-mqtt-websocket-client/mqtt-upstream-auth-workflow.png)
101-
102-
These two workflows can be used individually or in combination. If they're used in together, the auth result in the latter workflow would be honored by the service.
103-
104-
For details on client authentication and authorization, see [How To Connect MQTT Clients to Web PubSub](./howto-connect-mqtt-websocket-client.md).
105-
106-
## Client lifetime event notification
107-
108-
You can register event handlers to get notification when a Web PubSub client connection is started or ended, that is, an MQTT session started or ended.
109-
110-
* [Event handler in Azure Web PubSub service](./howto-develop-eventhandler.md)
111-
* [MQTT CloudEvents Protocol](./reference-mqtt-cloud-events.md)
112-
113-
## REST API support
114-
115-
You can use REST API to do the following things:
116-
117-
* Publish messages to a topic, a connection, a Web PubSub user, or all the connections.
118-
* Manage client permissions and subscriptions.
119-
120-
[REST API specification for MQTT](./reference-rest-api-mqtt.md)
121-
122-
## Event listener support
123-
124-
> [!NOTE]
125-
> Sending MQTT client events to Event Hubs is not supported yet.
126-
12751
## Next step
12852

12953
> [!div class="nextstepaction"]

‎articles/azure-web-pubsub/reference-mqtt-support-status.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: MQTT feature support status in Azure Web PubSub service
3+
description: Comprehensive list of MQTT feature supported and unsupported by Azure Web PubSub service
4+
keywords: MQTT, MQTT on Azure Web PubSub, MQTT over WebSocket
5+
author: kevinguo-ed
6+
ms.author: kevinguo
7+
ms.date: 10/17/2024
8+
ms.service: azure-web-pubsub
9+
ms.topic: reference
10+
---
11+
# MQTT feature support status in Azure Web PubSub service
12+
13+
Azure Web PubSub service supports MQTT protocol by translateing MQTT messages into its native protocol, enabling cross-communication between MQTT web clients and other Web PubSub clients. Since the MQTT support is a lightweight adaptation of the MQTT protocol, it extends only to the features already supported by Azure Web PubSub service. Refer to the list below for what's supported and not supported.
14+
15+
## Feature support for MQTT version 3.1.1 and 5.0
16+
Azure Web PubSub support MQTT protocol version 3.1.1 and 5.0. The supported features include but not limited to:
17+
18+
- All the levels of Quality Of Service including at most once, at least once and exactly once.
19+
- Persistent session. MQTT sessions are preserved for up to 30 seconds when client connections are interrupted and restored when the client re-establishes a connection with the service. Note that beyond 30 seconds, the service makes no guarantee that the session is restored.
20+
- Last will & testament
21+
- Client certificate authentication
22+
23+
## Additional features supported for MQTT 5.0
24+
25+
- Message expiry interval and session expiry interval
26+
- Subscription identifier
27+
- Assigned client ID
28+
- Flow control
29+
- Server-sent disconnect
30+
31+
## Not supported features
32+
33+
- Wildcard subscription
34+
- Retained messages
35+
- Topic alias
36+
- Shared subscription

0 commit comments

Comments
 (0)