|
1 | 1 | --- |
2 | 2 | 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. |
4 | 4 | keywords: MQTT, MQTT on Azure Web PubSub, MQTT over WebSocket |
5 | 5 | author: Y-Sindo |
6 | 6 | ms.author: zityang |
7 | | -ms.date: 07/15/2024 |
| 7 | +ms.date: 10/17/2024 |
8 | 8 | ms.service: azure-web-pubsub |
9 | 9 | ms.topic: overview |
10 | 10 | --- |
11 | | -# Overview: MQTT in Azure Web PubSub service (Preview) |
12 | | - |
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: |
16 | | - |
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. |
| 11 | +# MQTT in Azure Web PubSub service (Preview) |
20 | 12 |
|
21 | 13 | > [!NOTE] |
22 | 14 | > MQTT support in Azure Web PubSub is in preview stage. |
23 | 15 |
|
24 | | -## Key features |
25 | | - |
26 | | -### Standard MQTT protocols support |
27 | | - |
28 | | -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. |
29 | | - |
30 | | -### Cross-protocol communication |
31 | | - |
32 | | -MQTT clients can communicate with clients of other Web PubSub protocols. Find more details [here](./reference-mqtt-cross-protocol-communication.md) |
33 | | - |
34 | | -### Easy MQTT adoption for current Web PubSub users |
35 | | - |
36 | | -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. |
| 16 | +## Overview |
| 17 | +[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 |
37 | 18 |
|
38 | | -### Client-to-server request/response model |
| 19 | +This new capability addresses two key use cases: |
| 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. |
39 | 21 |
|
40 | | -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. |
| 22 | +2. Support for more 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. |
41 | 23 |
|
42 | | -For more details, see [MQTT custom event handler protocol](./reference-mqtt-cloud-events.md#user-custom_event-event). |
| 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 aren't supported include: |
| 25 | +- Wildcard subscriptions |
| 26 | +- Retained messages |
| 27 | +- Shared subscriptions |
| 28 | +- Topic alias |
43 | 29 |
|
44 | | -## MQTT feature support status |
| 30 | +For a comprehensive list of what MQTT features are supported, read [this documentation article](./reference-mqtt-support-status.md). |
45 | 31 |
|
46 | | -Web PubSub support MQTT protocol version 3.1.1 and 5.0. The supported features include but not limited to: |
| 32 | +For a more comprehensive MQTT broker solution on Azure, we recommend exploring [Azure Event Grid](../event-grid/overview.md). |
47 | 33 |
|
48 | | -* All the levels of Quality Of Service including at most once, at least once and exactly once. |
49 | | -* Persistent session. MQTT sessions are preserved for up to 30 seconds when client connections are interrupted. |
50 | | -* Last Will & Testament |
51 | | -* Client Certificate Authentication |
52 | | - |
53 | | -### Additional features supported for MQTT 5.0 |
54 | | - |
55 | | -* Message Expiry Interval and Session Expiry Interval |
56 | | -* Subscription Identifier. |
57 | | -* Assigned Client ID. |
58 | | -* Flow Control |
59 | | -* Server-Sent Disconnect |
60 | | - |
61 | | -### Not supported feature |
62 | | - |
63 | | -* Wildcard subscription |
64 | | -* Retained messages |
65 | | -* Topic alias |
66 | | -* Shared subscription |
| 34 | +## Real-time data exchange patterns enabled by the MQTT support |
| 35 | +- Pub/Sub among MQTT web clients and Web PubSub native clients |
| 36 | +- Broadcast messages to MQTT web clients |
| 37 | +- Receive notifications for lifetime events of MQTT web client |
67 | 38 |
|
68 | 39 | ## How MQTT is adapted into Web PubSub's system |
69 | 40 |
|
70 | | -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). |
| 41 | +> [!NOTE] |
| 42 | +> This section assumes you have basic knowledge about MQTT protocols and Azure Web PubSub. |
71 | 43 |
|
72 | | -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. |
| 44 | +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 those 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 web clients. |
73 | 45 |
|
74 | 46 | [!INCLUDE [MQTT-Term-Mappings](includes/mqtt-term-mappings.md)] |
75 | 47 |
|
76 | | -## Client authentication and authorization |
77 | | - |
78 | | -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. |
79 | | - |
80 | | -* 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. |
81 | | - |
82 | | - |
83 | | - |
84 | | -* 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. |
85 | | -<!--Add link to tutorial and configuration--> |
86 | | - |
87 | | - |
88 | | - |
89 | | -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. |
90 | | - |
91 | | -For details on client authentication and authorization, see [How To Connect MQTT Clients to Web PubSub](./howto-connect-mqtt-websocket-client.md). |
92 | | - |
93 | | -## Client lifetime event notification |
94 | | - |
95 | | -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. |
96 | | - |
97 | | -* [Event handler in Azure Web PubSub service](./howto-develop-eventhandler.md) |
98 | | -* [MQTT CloudEvents Protocol](./reference-mqtt-cloud-events.md) |
99 | | - |
100 | | -## REST API support |
101 | | - |
102 | | -You can use REST API to do the following things: |
103 | | - |
104 | | -* Publish messages to a topic, a connection, a Web PubSub user, or all the connections. |
105 | | -* Manage client permissions and subscriptions. |
106 | | - |
107 | | -[REST API specification for MQTT](./reference-rest-api-mqtt.md) |
108 | | - |
109 | | -## Event listener support |
110 | | - |
111 | | -> [!NOTE] |
112 | | -> Sending MQTT client events to Event Hubs is not supported yet. |
113 | | -
|
114 | 48 | ## Next step |
115 | 49 |
|
116 | | -> [!div class="nextstepaction"] |
117 | | -> [Quickstart: Pub/Sub among MQTT clients](./quickstarts-pubsub-among-mqtt-clients.md) |
118 | | -
|
119 | 50 | > [!div class="nextstepaction"] |
120 | 51 | > [How To Connect MQTT Clients to Web PubSub](./howto-connect-mqtt-websocket-client.md) |
| 52 | +> [!div class="nextstepaction"] |
| 53 | +> [Quickstart: Pub/Sub among MQTT clients](./howto-mqtt-pubsub-among-mqtt-clients.md) |
| 54 | +
|
0 commit comments