Comunique-se com um hub IoT usando o protocolo MQTT

  • Artigo

Este artigo descreve como os dispositivos podem usar comportamentos MQTT com suporte para se comunicar com o Hub IoT do Azure. O Hub IoT permite que os dispositivos se comuniquem com os pontos de extremidade de dispositivo do Hub IoT usando:

  • MQTT v3.1.1 na porta TCP 8883
  • MQTT v3.1.1 sobre WebSocket na porta TCP 443.

Nota

Alguns dos recursos mencionados neste artigo, como mensagens de nuvem para dispositivo, gêmeos de dispositivo e gerenciamento de dispositivos, estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada certa do Hub IoT para sua solução.

Toda a comunicação do dispositivo com o Hub IoT deve ser protegida usando TLS/SSL. Portanto, o Hub IoT não suporta conexões não seguras pela porta TCP 1883.

Compare o suporte MQTT no Hub IoT e na Grade de Eventos

O Hub IoT não é um broker MQTT completo e não suporta todos os comportamentos especificados no padrão MQTT v3.1.1. Se sua solução precisar de MQTT, recomendamos o suporte a MQTT na Grade de Eventos do Azure. A Grade de Eventos permite a comunicação bidirecional entre clientes MQTT em tópicos hierárquicos flexíveis usando um modelo de mensagens pub-sub. Ele também permite que você roteie mensagens MQTT para serviços do Azure ou pontos de extremidade personalizados para processamento posterior.

A tabela a seguir explica as diferenças no suporte MQTT entre os dois serviços:

Hub IoT Event Grid
Modelo cliente-servidor com acoplamento estreito entre dispositivos e aplicativos em nuvem. Modelo de publicação-subscrição que separa editores e subscritores.
Suporte limitado a recursos para MQTT v3.1.1 e suporte limitado a recursos para MQTT v5 na visualização. Não está planeado mais suporte a funcionalidades. Suporte aos protocolos MQTT v3.1.1 e v5, com mais suporte a recursos e conformidade do setor planejada.
Tópicos estáticos e predefinidos. Tópicos hierárquicos personalizados com suporte a curingas.
Não há suporte para transmissões de nuvem para dispositivo e comunicação de dispositivo para dispositivo. Suporta transmissões de dispositivo para nuvem, alta distribuição de nuvem para dispositivo e padrões de comunicação de dispositivo para dispositivo.
Tamanho máximo da mensagem de 256KB. Tamanho máximo da mensagem de 512KB.

Conectando-se ao Hub IoT

Um dispositivo pode usar o protocolo MQTT para se conectar a um hub IoT usando uma das seguintes opções:

  • Os SDKs do Azure IoT.
  • O protocolo MQTT diretamente.

A porta MQTT (porta TCP 8883) está bloqueada em muitos ambientes de rede corporativos e educacionais. Se não conseguir abrir a porta 8883 no firewall, recomendamos o uso do MQTT sobre WebSockets. O MQTT sobre WebSockets se comunica pela porta 443, que quase sempre está aberta em ambientes de rede. Para saber como especificar os protocolos MQTT e MQTT sobre WebSockets ao usar os SDKs do Azure IoT, consulte Usando os SDKs de dispositivo.

Usando os SDKs do dispositivo

SDKs de dispositivo que suportam o protocolo MQTT estão disponíveis para Java, Node.js, C, C# e Python. Os SDKs de dispositivo usam o mecanismo de autenticação escolhido para estabelecer uma conexão com um hub IoT. Para usar o protocolo MQTT, o parâmetro do protocolo cliente deve ser definido como MQTT. Você também pode especificar MQTT sobre WebSockets no parâmetro de protocolo do cliente. Por padrão, os SDKs de dispositivo se conectam a um Hub IoT com o sinalizador CleanSession definido como 0 e usam QoS 1 para troca de mensagens com o hub IoT. Embora seja possível configurar a QoS 0 para uma troca de mensagens mais rápida, você deve observar que a entrega não é garantida nem reconhecida. Por esta razão, QoS 0 é muitas vezes referido como "fogo e esquecer".

Quando um dispositivo está conectado a um hub IoT, os SDKs de dispositivo fornecem métodos que permitem que o dispositivo troque mensagens com um hub IoT.

A tabela a seguir contém links para exemplos de código para cada idioma suportado e especifica o parâmetro a ser usado para estabelecer uma conexão com o Hub IoT usando o protocolo MQTT ou MQTT sobre WebSockets.

Linguagem Parâmetro do protocolo MQTT Parâmetro do protocolo MQTT sobre WebSockets
Node.js azure-iot-device-mqtt. Mqtt azure-iot-device-mqtt. MqttWs
Java IotHubClientProtocol. MQTT IotHubClientProtocol.MQTT_WS
C MQTT_Protocol MQTT_WebSocket_Protocol
C# TransportType. Mqtt TransportType.Mqtt retorna ao MQTT sobre WebSockets se o MQTT falhar. Para especificar MQTT somente sobre WebSockets, use TransportType.Mqtt_WebSocket_Only
Python Suporta MQTT por padrão Adicionar websockets=True na chamada para criar o cliente

O fragmento a seguir mostra como especificar o protocolo MQTT sobre WebSockets ao usar o SDK do Azure IoT Node.js:

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

O fragmento a seguir mostra como especificar o protocolo MQTT sobre WebSockets ao usar o SDK Python do Azure IoT:

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

Tempo limite do keep-alive predefinido

Para garantir que uma conexão cliente/Hub IoT permaneça ativa, tanto o serviço quanto o cliente enviam regularmente um ping keep-alive um para o outro. O cliente que usa o IoT SDK envia um keep-alive no intervalo definido na tabela a seguir:

Linguagem Intervalo keep-alive padrão Configurável
Node.js 180 segundos Não
Java 230 segundos Sim
C 240 segundos Sim
C# 300 segundos* Sim
Python 60 segundos Sim

*O SDK C# define o valor padrão da propriedade MQTT KeepAliveInSeconds como 300 segundos. Na realidade, o SDK envia uma solicitação de ping quatro vezes por conjunto de duração de keep-alive. Em outras palavras, o SDK envia um ping keep-alive uma vez a cada 75 segundos.

Seguindo a especificação MQTT v3.1.1, o intervalo de ping keep-alive do Hub IoT é 1,5 vezes o valor keep-alive do cliente, no entanto, o Hub IoT limita o tempo limite máximo do servidor a 29,45 minutos (1767 segundos). Esse limite existe porque todos os serviços do Azure estão vinculados ao tempo limite de ociosidade TCP do balanceador de carga do Azure, que é de 29,45 minutos.

Por exemplo, um dispositivo usando o Java SDK envia o ping keep-alive e, em seguida, perde a conectividade de rede. 230 segundos depois, o dispositivo perde o ping keep-alive porque está offline. No entanto, o Hub IoT não fecha a conexão imediatamente - ele aguarda mais (230 * 1.5) - 230 = 115 segundos antes de desconectar o dispositivo com o erro 404104 DeviceConnectionClosedRemotely.

O valor máximo de keep-alive do cliente que você pode definir é 1767 / 1.5 = 1177 segundos. Qualquer tráfego redefine a manutenção viva. Por exemplo, uma atualização bem-sucedida do token de assinatura de acesso compartilhado (SAS) redefine o keep-alive.

Migrando um aplicativo de dispositivo do AMQP para o MQTT

Se você estiver usando os SDKs de dispositivo, mudar do uso de AMQP para MQTT requer a alteração do parâmetro de protocolo na inicialização do cliente, conforme indicado anteriormente.

Ao fazer isso, certifique-se de verificar os seguintes itens:

  • AMQP retorna erros para muitas condições, enquanto MQTT encerra a conexão. Como resultado, sua lógica de tratamento de exceções pode exigir algumas alterações.

  • O MQTT não suporta as operações de rejeição ao receber mensagens da nuvem para o dispositivo. Se o seu aplicativo back-end precisar receber uma resposta do aplicativo do dispositivo, considere o uso de métodos diretos.

  • AMQP não é suportado no Python SDK.

Usando o protocolo MQTT diretamente (como um dispositivo)

Se um dispositivo não puder usar os SDKs do dispositivo, ele ainda poderá se conectar aos pontos de extremidade do dispositivo público usando o protocolo MQTT na porta 8883.

No pacote CONNECT, o dispositivo deve usar os seguintes valores:

  • Para o campo ClientId , use o deviceId.

  • Para o campo Nome de usuário , use {iotHub-hostname}/{device-id}/?api-version=2021-04-12, onde {iotHub-hostname} está o completo CName do hub IoT.

    Por exemplo, se o nome do seu hub IoT for contoso.azure-devices.net e se o nome do seu dispositivo for MyDevice01, o campo Nome de usuário completo deverá conter:

    contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

    Recomenda-se incluir a versão api no campo. Caso contrário, pode causar comportamentos inesperados.

  • Para o campo Senha , use um token SAS. O formato do token SAS é o mesmo dos protocolos HTTPS e AMQP:

    SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

    Nota

    Se você usar a autenticação de certificado X.509, as senhas de token SAS não serão necessárias. Para obter mais informações, consulte Tutorial: Criar e carregar certificados para teste e siga as instruções de código na seção de configuração TLS/SSL.

    Para obter mais informações sobre como gerar tokens SAS, consulte a seção Usar tokens SAS como um dispositivo de Controlar o acesso ao Hub IoT usando assinaturas de acesso compartilhado.

    Você também pode usar a extensão multiplataforma do Hub IoT do Azure para Visual Studio Code ou o comando de extensão CLI az iot hub generate-sas-token para gerar rapidamente um token SAS. Em seguida, você pode copiar e colar o token SAS em seu próprio código para fins de teste.

Para obter um tutorial sobre como usar MQTT diretamente, consulte Usar MQTT para desenvolver um cliente de dispositivo IoT sem usar um SDK de dispositivo.

Usando a extensão do Hub IoT do Azure para Visual Studio Code

  1. Na barra lateral, expanda o nó Dispositivos na seção Hub IoT do Azure.

  2. Clique com o botão direito do mouse em seu dispositivo IoT e selecione Gerar token SAS para dispositivo no menu de contexto.

  3. Insira o tempo de expiração, em horas, para o token SAS na caixa de entrada e selecione a tecla Enter.

  4. O token SAS é criado e copiado para a área de transferência.

    O token SAS gerado tem a seguinte estrutura:

    HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

    A parte deste token a ser usada como o campo Senha para se conectar usando MQTT é:

    SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

O aplicativo de dispositivo pode especificar uma mensagem Will no pacote CONNECT . O aplicativo de dispositivo deve usar devices/{device-id}/messages/events/ ou devices/{device-id}/messages/events/{property-bag} como o nome do tópico Will para definir as mensagens Will a serem encaminhadas como uma mensagem de telemetria. Nesse caso, se a conexão de rede estiver fechada, mas um pacote DISCONNECT não tiver sido recebido anteriormente do dispositivo, o Hub IoT enviará a mensagem Will fornecida no pacote CONNECT para o canal de telemetria. O canal de telemetria pode ser o ponto de extremidade padrão de Eventos ou um ponto de extremidade personalizado definido pelo roteamento do Hub IoT. A mensagem tem a propriedade iothub-MessageType com um valor de Will atribuído a ela.

Usando o protocolo MQTT diretamente (como um módulo)

Você pode se conectar ao Hub IoT através do MQTT usando uma identidade de módulo, semelhante à conexão ao Hub IoT como um dispositivo. Para obter mais informações sobre como se conectar ao Hub IoT sobre MQTT como um dispositivo, consulte Usando o protocolo MQTT diretamente (como um dispositivo). No entanto, você precisa usar os seguintes valores:

  • Defina o ID do cliente como {device-id}/{module-id}.

  • Se estiver autenticando com nome de usuário e senha, defina o nome de usuário e <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 use o token SAS associado à identidade do módulo como sua senha.

  • Use devices/{device-id}/modules/{module-id}/messages/events/ como um tópico para publicar telemetria.

  • Use devices/{device-id}/modules/{module-id}/messages/events/ como tópico WILL.

  • Use devices/{device-id}/modules/{module-id}/# como um tópico para receber mensagens.

  • Os tópicos gêmeos GET e PATCH são idênticos para módulos e dispositivos.

  • O tópico de status gêmeo é idêntico para módulos e dispositivos.

Para obter mais informações sobre como usar o MQTT com módulos, consulte Publicar e assinar com o IoT Edge e saiba mais sobre o ponto de extremidade MQTT do hub IoT Edge.

Exemplos usando MQTT sem um SDK do Azure IoT

O repositório de exemplo MQTT da IoT contém exemplos de C/C++, Python e CLI que mostram como enviar mensagens de telemetria, receber mensagens da nuvem para o dispositivo e usar gêmeos de dispositivo sem usar os SDKs de dispositivo do Azure.

Os exemplos C/C++ usam a biblioteca Eclipse Mosquitto , o exemplo Python usa Eclipse Paho e os exemplos CLI usam mosquitto_pub.

Para saber mais, consulte Tutorial - Usar MQTT para desenvolver um cliente de dispositivo IoT.

Configuração TLS/SSL

Para usar o protocolo MQTT diretamente, seu cliente deve se conectar por TLS/SSL. As tentativas de ignorar esta etapa falham com erros de conexão.

Para estabelecer uma conexão TLS, talvez seja necessário baixar e fazer referência ao certificado raiz DigiCert que o Azure usa. Entre 15 de fevereiro e 15 de outubro de 2023, o Hub IoT do Azure está migrando seu certificado raiz TLS do Certificado Raiz DigiCert Baltimore para o DigiCert Global Root G2. Durante o período de migração, você deve ter ambos os certificados em seus dispositivos para garantir a conectividade. Para obter mais informações sobre a migração, consulte Migrar recursos de IoT para uma nova raiz de certificado TLS Para obter mais informações sobre esses certificados, consulte o site da Digicert.

O exemplo a seguir demonstra como implementar essa configuração, usando a versão Python da biblioteca Paho MQTT pela Eclipse Foundation.

Primeiro, instale a biblioteca Paho a partir do seu ambiente de linha de comando:

pip install paho-mqtt

Em seguida, implemente o cliente em um script Python. Substitua esses espaços reservados no seguinte trecho de código:

  • <local path to digicert.cer> é o caminho para um arquivo local que contém o certificado raiz DigiCert. Você pode criar esse arquivo copiando as informações do certificado de certs.c no SDK do Azure IoT para C. Inclua as linhas -----BEGIN CERTIFICATE----- e -----END CERTIFICATE-----, remova as " marcas no início e no final de cada linha e remova os \r\n caracteres no final de cada linha.

  • <device id from device registry> é a ID de um dispositivo que você adicionou ao seu hub IoT.

  • <generated SAS token> é um token SAS para o dispositivo criado conforme descrito anteriormente neste artigo.

  • <iot hub name> o nome do seu hub IoT.

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"


def on_connect(client, userdata, flags, rc):
    print("Device connected with result code: " + str(rc))


def on_disconnect(client, userdata, rc):
    print("Device disconnected with result code: " + str(rc))


def on_publish(client, userdata, mid):
    print("Device sent message")


client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()

Para autenticar usando um certificado de dispositivo, atualize o trecho de código anterior com as alterações especificadas no trecho de código a seguir. Para obter mais informações sobre como se preparar para a autenticação baseada em certificados, consulte a seção Obter um certificado de autoridade de certificação X.509 de Autenticar dispositivos usando certificados de autoridade de certificação X.509.

# Create the client as before
# ...

# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=None)

# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)

# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)

Enviar mensagens do dispositivo para a nuvem

Depois que um dispositivo se conecta, ele pode enviar mensagens para o Hub IoT usando devices/{device-id}/messages/events/ ou devices/{device-id}/messages/events/{property-bag} como um Nome de Tópico. O {property-bag} elemento permite que o dispositivo envie mensagens com outras propriedades em um formato codificado por url. Por exemplo:

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

Nota

Este {property_bag} elemento usa a mesma codificação que cadeias de caracteres de consulta no protocolo HTTPS.

Nota

Se você estiver roteando mensagens D2C para uma conta de Armazenamento do Azure e quiser aproveitar a codificação JSON, deverá especificar as informações de Tipo de Conteúdo e Codificação de Conteúdo, incluindo $.ct=application%2Fjson&$.ce=utf-8, como parte da mencionada {property_bag} na nota anterior.

O formato desses atributos é específico do protocolo. O Hub IoT traduz esses atributos em suas propriedades de sistema correspondentes. Para obter mais informações, consulte a seção Propriedades do sistema da sintaxe da consulta de roteamento de mensagens do Hub IoT.

A lista a seguir descreve comportamentos específicos de implementação do Hub IoT:

  • O Hub IoT não suporta mensagens QoS 2. Se um aplicativo de dispositivo publicar uma mensagem com QoS 2, o Hub IoT fechará a conexão de rede.

  • O Hub IoT não persiste Reter mensagens. Se um dispositivo enviar uma mensagem com o sinalizador RETAIN definido como 1, o Hub IoT adicionará a propriedade do aplicativo mqtt-retain à mensagem. Nesse caso, em vez de persistir a mensagem de retenção, o Hub IoT a passa para o aplicativo de back-end.

  • O Hub IoT suporta apenas uma conexão MQTT ativa por dispositivo. Qualquer nova conexão MQTT em nome do mesmo ID de dispositivo faz com que o Hub IoT descarte a conexão existente e 400027 ConnectionForcefullyClosedOnNewConnection é registrado nos Logs do Hub IoT

  • Para rotear mensagens com base no corpo da mensagem, você deve primeiro adicionar a propriedade 'contentType' (ct) ao final do tópico MQTT e definir seu valor como sendo application/json;charset=utf-8 mostrado no exemplo a seguir. Para obter mais informações sobre o roteamento de mensagens com base nas propriedades da mensagem ou no corpo da mensagem, consulte a documentação da sintaxe da consulta de roteamento de mensagens do Hub IoT.

    devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

Para obter mais informações, consulte Enviar mensagens de dispositivo para nuvem e de nuvem para dispositivo com o Hub IoT.

Receber mensagens da nuvem para o dispositivo

Para receber mensagens do Hub IoT, um dispositivo deve se inscrever usando devices/{device-id}/messages/devicebound/# como um Filtro de Tópico. O curinga # de vários níveis no Filtro de Tópicos é usado apenas para permitir que o dispositivo receba mais propriedades no nome do tópico. O Hub IoT não permite o uso de curingas # ou ? para filtragem de subtópicos. Como o Hub IoT não é um agente de mensagens pub-sub de uso geral, ele suporta apenas os nomes de tópicos documentados e filtros de tópicos. Um dispositivo só pode subscrever cinco tópicos de cada vez.

O dispositivo não recebe mensagens do Hub IoT até que tenha se inscrito com êxito em seu ponto de extremidade específico do dispositivo, representado pelo filtro de devices/{device-id}/messages/devicebound/# tópico. Depois que uma assinatura é estabelecida, o dispositivo recebe mensagens da nuvem para o dispositivo que foram enviadas para ele após o tempo da assinatura. Se o dispositivo se conectar com o sinalizador CleanSession definido como 0, a assinatura será mantida em sessões diferentes. Nesse caso, da próxima vez que o dispositivo se conectar com o CleanSession 0 , ele receberá todas as mensagens pendentes enviadas a ele enquanto estiver desconectado. No entanto, se o dispositivo usar o sinalizador CleanSession definido como 1 , ele não receberá nenhuma mensagem do Hub IoT até se inscrever no ponto de extremidade do dispositivo.

O Hub IoT entrega mensagens com o Nomedevices/{device-id}/messages/devicebound/ do Tópico ou devices/{device-id}/messages/devicebound/{property-bag} quando há propriedades de mensagem. {property-bag} Contém pares chave/valor codificados por URL de propriedades de mensagem. Somente as propriedades do aplicativo e as propriedades do sistema configuráveis pelo usuário (como messageId ou correlationId) são incluídas no pacote de propriedades. Os nomes de propriedade do sistema têm o prefixo $, as propriedades do aplicativo usam o nome da propriedade original sem prefixo. Para obter mais informações sobre o formato do pacote de propriedades, consulte Enviando mensagens do dispositivo para a nuvem.

Em mensagens de nuvem para dispositivo, os valores no pacote de propriedades são representados como na tabela a seguir:

Valor do imóvel Representação Description
null key Apenas a chave aparece no saco do imóvel
cadeia vazia key= A chave seguida por um sinal de igual sem valor
valor não nulo, não vazio key=value A chave seguida por um sinal de igual e o valor

O exemplo a seguir mostra um conjunto de propriedades que contém três propriedades de aplicativo: prop1 com um valor de null; prop2, uma corda vazia (""); e prop3 com um valor de "uma corda".

/?prop1&prop2=&prop3=a%20string

Quando um aplicativo de dispositivo se inscreve em um tópico com QoS 2, o Hub IoT concede QoS máximo de nível 1 no pacote SUBACK . Depois disso, o Hub IoT entrega mensagens para o dispositivo usando QoS 1.

Recuperando as propriedades de um gêmeo de dispositivo

Primeiro, um dispositivo assina $iothub/twin/res/#o , para receber as respostas da operação. Em seguida, ele envia uma mensagem vazia para o tópico $iothub/twin/GET/?$rid={request id}, com um valor preenchido para ID de solicitação. Em seguida, o serviço envia uma mensagem de resposta contendo os dados gêmeos do dispositivo no tópico $iothub/twin/res/{status}/?$rid={request-id}, usando o mesmo ID de solicitação da solicitação.

O ID da solicitação pode ser qualquer valor válido para um valor de propriedade de mensagem e o status é validado como um inteiro. Para obter mais informações, consulte Enviar mensagens de dispositivo para nuvem e de nuvem para dispositivo com o Hub IoT.

O corpo da resposta contém a seção de propriedades do gêmeo do dispositivo, conforme mostrado no exemplo de resposta a seguir:

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

Os códigos de status possíveis são:

Status Description
200 Com êxito
429 Demasiados pedidos (limitados). Para obter mais informações, consulte Limitação do Hub IoT
5** Erros de servidor

Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT).

Atualizar propriedades relatadas do gêmeo do dispositivo

Para atualizar as propriedades relatadas, o dispositivo emite uma solicitação ao Hub IoT por meio de uma publicação sobre um tópico MQTT designado. Depois que o Hub IoT processa a solicitação, ele responde ao status de sucesso ou falha da operação de atualização por meio de uma publicação para outro tópico. O dispositivo pode se inscrever neste tópico para notificá-lo sobre o resultado de sua solicitação de atualização gêmea. Para implementar esse tipo de interação solicitação/resposta no MQTT, usamos a noção de ID de solicitação ($rid) fornecida inicialmente pelo dispositivo em sua solicitação de atualização. Esse ID de solicitação também é incluído na resposta do Hub IoT para permitir que o dispositivo correlacione a resposta à sua solicitação anterior específica.

A sequência a seguir descreve como um dispositivo atualiza as propriedades relatadas no gêmeo de dispositivo no Hub IoT:

  1. Um dispositivo deve primeiro se inscrever no $iothub/twin/res/# tópico para receber as respostas da operação do Hub IoT.

  2. Um dispositivo envia uma mensagem que contém a atualização gêmea do dispositivo para o $iothub/twin/PATCH/properties/reported/?$rid={request-id} tópico. Esta mensagem inclui um valor de ID de solicitação.

  3. Em seguida, o serviço envia uma mensagem de resposta que contém o novo valor ETag para a coleção de propriedades relatadas no tópico $iothub/twin/res/{status}/?$rid={request-id}. Essa mensagem de resposta usa a mesma ID de solicitação que a solicitação.

O corpo da mensagem de solicitação contém um documento JSON que contém novos valores para propriedades relatadas. Cada membro no documento JSON atualiza ou adiciona o membro correspondente no documento do gêmeo do dispositivo. Um membro definido para null excluir o membro do objeto que contém. Por exemplo:

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

Os códigos de status possíveis são:

Status Description
204 Sucesso (nenhum conteúdo é devolvido)
400 Mau pedido. JSON malformado
429 Muitas solicitações (limitadas), de acordo com a limitação do Hub IoT
5** Erros de servidor

O trecho de código Python a seguir demonstra o processo de atualização de propriedades relatadas gêmeas sobre MQTT usando o cliente Paho MQTT:

from paho.mqtt import client as mqtt

# authenticate the client with IoT Hub (not shown here)

client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
               rid, twin_reported_property_patch, qos=0)

Após o sucesso do processo de atualização de propriedades relatadas de gêmeos no trecho de código anterior, a mensagem de publicação do Hub IoT tem o seguinte tópico: $iothub/twin/res/204/?$rid=1&$version=6, onde 204 é o código de status que indica sucesso, $rid=1 corresponde ao ID de solicitação fornecido pelo dispositivo no código e $version corresponde à seção de propriedades relatadas dos gêmeos de dispositivo após a atualização.

Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT).

Receber notificações de atualização de propriedades desejadas

Quando um dispositivo está conectado, o Hub IoT envia notificações para o tópico $iothub/twin/PATCH/properties/desired/?$version={new-version}, que contêm o conteúdo da atualização realizada pelo back-end da solução. Por exemplo:

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

Quanto às atualizações de propriedade, null os valores significam que o membro do objeto JSON está sendo excluído. Além disso, $version indica a nova versão da seção de propriedades desejadas do gêmeo.

Importante

O Hub IoT gera notificações de alteração somente quando os dispositivos estão conectados. Certifique-se de implementar o fluxo de reconexão do dispositivo para manter as propriedades desejadas sincronizadas entre o Hub IoT e o aplicativo do dispositivo.

Para obter mais informações, veja Understand and use device twins in IoT Hub (Compreender e utilizar dispositivos duplos no Hub IoT).

Responder a um método direto

Primeiro, um dispositivo tem de subscrever o $iothub/methods/POST/#. O Hub IoT envia solicitações de método para o tópico $iothub/methods/POST/{method-name}/?$rid={request-id}, com um JSON válido ou um corpo vazio.

Para responder, o dispositivo envia uma mensagem com um JSON válido ou corpo vazio para o tópico $iothub/methods/res/{status}/?$rid={request-id}. Nessa mensagem, o ID da solicitação deve corresponder ao da mensagem de solicitação e o status deve ser um inteiro.

Para obter mais informações, consulte Compreender e invocar métodos diretos do Hub IoT.

Próximos passos

Para saber mais sobre como usar o MQTT, consulte:

Para saber mais sobre como usar SDKs de dispositivos IoT, consulte:

Para saber mais sobre como planejar sua implantação do Hub IoT, consulte: