Criar e ler mensagens do Hub IoT

Para dar suporte à interoperabilidade entre protocolos, o Hub IoT define um conjunto comum de recursos de mensagens que estão disponíveis em todos os protocolos voltados para o dispositivo. Esses recursos podem ser usados em mensagens de dispositivo para nuvem e mensagens de nuvem para dispositivo.

O Hub IoT implementa mensagens de dispositivo para nuvem usando um padrão de mensagens de streaming. As mensagens de dispositivo para nuvem do Hub IoT são mais parecidas com eventos de Hubs de Eventos do que mensagens do Service Bus, pois há um grande volume de eventos passando pelo serviço que vários leitores podem ler.

Uma mensagem do Hub IoT consiste em:

• Um conjunto predeterminado de propriedades do sistema, conforme descrito mais adiante neste artigo.

• Um conjunto de propriedades do aplicativo. Um dicionário de propriedades de cadeia de caracteres que o aplicativo pode definir e acessar, sem a necessidade de desserializar o corpo da mensagem. O Hub IoT nunca modifica essas propriedades.

• Um corpo de mensagem, que pode ser qualquer tipo de dados.

Cada protocolo de dispositivo implementa propriedades de configuração de maneiras diferentes. Para obter mais informações, consulte o guia do protocolo MQTT e os guias do desenvolvedor do guia do protocolo AMQP para obter detalhes.

Quando você envia mensagens de dispositivo para nuvem usando o protocolo HTTPS ou envia mensagens de nuvem para dispositivo, os nomes e valores de propriedade só podem conter caracteres alfanuméricos ASCII, além ! # $ % & ' * + - . ^ _ ` | ~ de .

As mensagens de dispositivo para nuvem com o Hub IoT têm as seguintes características:

• As mensagens de dispositivo para nuvem são duráveis e retidas no ponto de extremidade de mensagens/eventos padrão de um hub IoT por até sete dias.

• As mensagens do dispositivo para a nuvem podem ter, no máximo, 256 KB e podem ser agrupadas em lotes para otimizar os envios. Os lotes podem ter, no máximo, 256 KB.

• O Hub IoT não permite particionamento arbitrário. As mensagens de dispositivo para nuvem são particionadas com base em seu deviceId de origem.

• Conforme explicado em Controlar o acesso ao Hub IoT, o Hub IoT permite a autenticação por dispositivo e o controle de acesso.

• Você pode carimbar mensagens com informações que vão para as propriedades do aplicativo. Para obter mais informações, consulte Enriquecimento de mensagens.

Para usar o corpo da mensagem em uma consulta de roteamento do Hub IoT, forneça um objeto JSON válido para a mensagem e defina a propriedade de tipo de conteúdo da mensagem como application/json;charset=utf-8.

O exemplo a seguir mostra um corpo de mensagem válido e roteável:

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

Propriedades do sistema de mensagens do dispositivo para a nuvem

Propriedades do aplicativo de mensagens do dispositivo para a nuvem

Um uso comum das propriedades do aplicativo é enviar um carimbo de data/hora do dispositivo usando a iothub-creation-time-utc propriedade para registrar quando a mensagem foi enviada pelo dispositivo. O formato deste carimbo de data/hora deve ser UTC sem informações de fuso horário. Por exemplo, 2021-04-21T11:30:16Z é válido, mas 2021-04-21T11:30:16-07:00 é inválido.

{
  "applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
  "messageSource":"telemetry",
  "deviceId":"sample-device-01",
  "schema":"default@v1",
  "templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
  "enqueuedTime":"2021-01-29T16:45:39.143Z",
  "telemetry":{
    "temperature":8.341033560421833
  },
  "messageProperties":{
    "iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
  },
  "enrichments":{}
}

Propriedades do sistema de mensagens da nuvem para o dispositivo

Nomes de propriedades do sistema

Os nomes das propriedades do sistema variam com base no ponto de extremidade para o qual as mensagens estão sendo roteadas.

Tamanho da mensagem

O Hub IoT mede o tamanho da mensagem de forma independente de protocolo, considerando apenas a carga útil real. O tamanho em bytes é calculado como a soma dos seguintes valores:

• O tamanho do corpo em bytes.
• O tamanho em bytes de todos os valores das propriedades do sistema de mensagens.
• O tamanho em bytes de todos os nomes e valores de propriedade do usuário.

Os nomes e valores de propriedade são limitados a caracteres ASCII, portanto, o comprimento das cadeias de caracteres é igual ao tamanho em bytes.

Propriedades anti-falsificação

Para evitar falsificação de dispositivo em mensagens de dispositivo para nuvem, o Hub IoT carimba todas as mensagens com as seguintes propriedades:

• iothub-connection-device-id
• iothub-connection-auth-geração-id
• iothub-connection-auth-método

Os dois primeiros contêm o deviceId e generationId do dispositivo de origem, de acordo com as propriedades de identidade do dispositivo.

A propriedade iothub-connection-auth-method contém um objeto serializado JSON, com as seguintes propriedades:

{
  "scope": "{ hub | device | module }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

Próximos passos

• Para obter informações sobre limites de tamanho de mensagem no Hub IoT, consulte Cotas e limitação do Hub IoT.
• Para saber como criar e ler mensagens do Hub IoT em várias linguagens de programação, consulte os Inícios rápidos.
• Para saber mais sobre a estrutura de eventos não telemétricos gerados pelo Hub IoT, consulte Esquemas de eventos não telemétricos do Hub IoT.