使用 MQTT 协议与 DPS 通信Communicate with your DPS using the MQTT protocol

DPS 可让设备使用以下协议来与 DPS 设备终结点通信:DPS enables devices to communicate with the DPS device endpoint using:

DPS 不是功能完备的 MQTT 中转站,并未支持 MQTT v3.1.1 标准中指定的所有行为。DPS is not a full-featured MQTT broker and does not support all the behaviors specified in the MQTT v3.1.1 standard. 本文介绍设备如何使用受支持的 MQTT 行为通过 DPS 进行通信。This article describes how devices can use supported MQTT behaviors to communicate with DPS.

所有通过 DPS 进行的设备通信都必须使用 TLS/SSL 来保护。All device communication with DPS must be secured using TLS/SSL. 因此,DPS 不支持通过端口 1883 进行的不安全的连接。Therefore, DPS doesn't support non-secure connections over port 1883.

备注

DPS 目前不支持通过 MQTT 协议使用 TPM 证明机制的设备。DPS does not currently support devices using TPM attestation mechanism over the MQTT protocol.

连接到 DPSConnecting to DPS

设备可以通过以下任意选项使用 MQTT 协议连接到 DPS。A device can use the MQTT protocol to connect to a DPS using any of the following options.

直接使用 MQTT 协议(作为设备)Using the MQTT protocol directly (as a device)

如果设备无法使用设备 SDK,仍可使用端口 8883 上的 MQTT 协议连接到公共设备终结点。If a device cannot use the device SDKs, it can still connect to the public device endpoints using the MQTT protocol on port 8883. CONNECT 数据包中,设备应使用以下值:In the CONNECT packet, the device should use the following values:

  • 对于 ClientId 字段,使用 registrationIdFor the ClientId field, use registrationId.

  • 对于 Username 字段,使用 {idScope}/registrations/{registration_id}/api-version=2019-03-31,其中 {idScope} 是 DPS 的 idScopeFor the Username field, use {idScope}/registrations/{registration_id}/api-version=2019-03-31, where {idScope} is the idScope of the DPS.

  • “密码” 字段使用 SAS 令牌。For the Password field, use a SAS token. 对于 HTTPS 和 AMQP 协议,SAS 令牌的格式是相同的:The format of the SAS token is the same as for both the HTTPS and AMQP protocols:

    SharedAccessSignature sr={URL-encoded-resourceURI}&sig={signature-string}&se={expiry}&skn=registration resourceURI 应采用 {idScope}/registrations/{registration_id} 格式。SharedAccessSignature sr={URL-encoded-resourceURI}&sig={signature-string}&se={expiry}&skn=registration The resourceURI should be in the format {idScope}/registrations/{registration_id}. 策略名称应是 registrationThe policy name should be registration.

    备注

    如果使用 X.509 证书身份验证,则不需要使用 SAS 令牌密码。If you use X.509 certificate authentication, SAS token passwords are not required.

    有关如何生成 SAS 令牌的详细信息,请参阅控制对 DPS 的访问的安全令牌部分。For more information about how to generate SAS tokens, see the security tokens section of Control access to DPS.

下面列出了 DPS 特定于实现的行为:The following is a list of DPS implementation-specific behaviors:

  • DPS 不支持将 CleanSession 标志设置为 0 的功能。DPS does not support the functionality of CleanSession flag being set to 0.

  • 当设备应用使用 QoS 2 订阅主题时,DPS 会在 SUBACK 包中授予最高 QoS 级别 1。When a device app subscribes to a topic with QoS 2, DPS grants maximum QoS level 1 in the SUBACK packet. 之后,DPS 会使用 QoS 1 将消息传送到设备。After that, DPS delivers messages to the device using QoS 1.

TLS/SSL 配置TLS/SSL configuration

若要直接使用 MQTT 协议,客户端必须通过 TLS 1.2 进行连接。To use the MQTT protocol directly, your client must connect over TLS 1.2. 尝试跳过此步骤失败并显示连接错误。Attempts to skip this step fail with connection errors.

注册设备Registering a device

若要通过 DPS 注册某个设备,该设备应使用 $dps/registrations/res/# 作为主题筛选器进行订阅。To register a device through DPS, a device should subscribe using $dps/registrations/res/# as a Topic Filter. 主题筛选器中的多级通配符 # 仅用于允许设备接收主题名称中的其他属性。The multi-level wildcard # in the Topic Filter is used only to allow the device to receive additional properties in the topic name. DPS 不允许使用 #? 通配符筛选子主题。DPS does not allow the usage of the # or ? wildcards for filtering of subtopics. 由于 DPS 不是一般用途的发布-订阅消息传送中转站,因此它仅支持存档的主题名称和主题筛选器。Since DPS is not a general-purpose pub-sub messaging broker, it only supports the documented topic names and topic filters.

设备应使用 $dps/registrations/PUT/iotdps-register/?$rid={request_id} 作为主题名称向 DPS 发布 register 消息。The device should publish a register message to DPS using $dps/registrations/PUT/iotdps-register/?$rid={request_id} as a Topic Name. 有效负载应包含 JSON 格式的设备注册对象。The payload should contain the Device Registration object in JSON format. 如果成功,设备将在 $dps/registrations/res/202/?$rid={request_id}&retry-after=x 主题名称中收到响应,其中,x 是以秒为单位的 retry-after 值。In a successful scenario, the device will receive a response on the $dps/registrations/res/202/?$rid={request_id}&retry-after=x topic name where x is the retry-after value in seconds. 响应的有效负载将包含 JSON 格式的 RegistrationOperationStatus 对象。The payload of the response will contain the RegistrationOperationStatus object in JSON format.

轮询注册操作状态Polling for registration operation status

设备必须定期轮询服务,以接收设备注册操作的结果。The device must poll the service periodically to receive the result of the device registration operation. 假设设备已如前所述订阅 $dps/registrations/res/# 主题,则它可以将 get operationstatus 消息发布到 $dps/registrations/GET/iotdps-get-operationstatus/?$rid={request_id}&operationId={operationId} 主题名称。Assuming that the device has already subscribed to the $dps/registrations/res/# topic as indicated above, it can publish a get operationstatus message to the $dps/registrations/GET/iotdps-get-operationstatus/?$rid={request_id}&operationId={operationId} topic name. 此消息中的操作 ID 应是在上一步骤中的 RegistrationOperationStatus 响应消息中收到的值。The operation ID in this message should be the value received in the RegistrationOperationStatus response message in the previous step. 如果成功,服务将在 $dps/registrations/res/200/?$rid={request_id} 主题中做出响应。In the successful case, the service will respond on the $dps/registrations/res/200/?$rid={request_id} topic. 响应的有效负载将包含 RegistrationOperationStatus 对象。The payload of the response will contain the RegistrationOperationStatus object. 如果在经过与 retry-after 期限相等的延迟时间后响应代码为 202,则设备应不断地轮询服务。The device should keep polling the service if the response code is 202 after a delay equal to the retry-after period. 如果服务返回 200 状态代码,则表示设备注册操作成功。The device registration operation is successful if the service returns a 200 status code.

通过 Websocket 进行连接Connecting over Websocket

通过 Websocket 进行连接时,请将子协议指定为 mqttWhen connecting over Websocket, specify the subprotocol as mqtt. 遵循 RFC 6455Follow RFC 6455.

后续步骤Next steps

若要了解有关 MQTT 协议的详细信息,请参阅 MQTT 文档To learn more about the MQTT protocol, see the MQTT documentation.

若要进一步探索 DPS 的功能,请参阅:To further explore the capabilities of DPS, see: