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 ao dispositivo. Esses recursos podem ser usados nas mensagens de dispositivo para nuvem e nas mensagens de nuvem para dispositivo.
Observação
Alguns dos recursos mencionados neste artigo, como mensagens de nuvem para dispositivo, dispositivos gêmeos e gerenciamento de dispositivo estão disponíveis somente na camada Standard do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.
O Hub IoT implementa mensagens de dispositivo para nuvem usando um padrão de sistema de mensagens de streaming. As mensagens de dispositivo para nuvem do Hub IoT são mais semelhantes a eventos de Hubs de Eventos do que mensagens do Barramento de Serviço por haver um alto 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 posteriormente 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 precisar desserializar o corpo da mensagem. O Hub IoT nunca modifica essas propriedades.
Um corpo da mensagem, que pode ser qualquer tipo de dados.
Cada protocolo de dispositivo implementa as propriedades de configuração de maneiras diferentes. Para obter mais informações, consulte os guias do desenvolvedor Guia de protocolo MQTT e Guia de 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 de propriedades e valores só podem conter caracteres alfanuméricos ASCII, além de ! # $ % & ' * + - . ^ _ ` | ~.
As mensagens de dispositivo para a nuvem com o Hub IoT têm as seguintes características:
As mensagens do dispositivo para a nuvem são duráveis e mantidas em um ponto de extremidade de mensagens/eventos padrão do Hub IoT por até sete dias.
As mensagens de 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 o particionamento arbitrário. As mensagens do dispositivo para a nuvem são particionadas com base em sua deviceIdde origem.
Conforme explicado em Controlar o acesso ao IoT Hub, Hub IoT permite a autenticação por dispositivo e controle de acesso.
Você pode carimbar as mensagens com as informações que entrarão nas propriedades do aplicativo. Para saber mais, confira Enriquecimentos de mensagem.
Observação
Cada protocolo do Hub IoT fornece uma propriedade de tipo de conteúdo de mensagem que é respeitada durante o roteamento de dados para pontos de extremidade personalizados. Para que seus dados sejam tratados corretamente no destino (por exemplo, JSON sendo tratado como uma cadeia de caracteres analisável em vez de dados binários codificados em Base64), forneça o tipo de conteúdo e o conjunto de caracteres apropriados para a mensagem.
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 de dispositivo para nuvem
| Propriedade | Descrição | Configurável pelo usuário? | Palavra-chave para consulta de roteamento |
|---|---|---|---|
| message-id | Um identificador configurável pelo usuário para a mensagem utilizada para padrões de resposta à solicitação. Formato: uma cadeia de caracteres que diferencia maiúsculas de minúsculas (com até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits mais - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Sim | messageId |
| iothub-enqueuedtime | Data e hora em que a mensagem Dispositivo para Nuvem foi recebida pelo Hub IoT. | Não | enqueuedTime |
| user-id | Uma ID usada para especificar a origem das mensagens. | Sim | userId |
| iothub-connection-device-id | Uma ID definida pelo Hub IoT em mensagens do dispositivo para a nuvem. Contém a deviceId do dispositivo que enviou a mensagem. | Não | connectionDeviceId |
| iothub-connection-module-id | Uma ID definida pelo Hub IoT em mensagens do dispositivo para a nuvem. Contém a moduleId do dispositivo que enviou a mensagem. | Não | connectionModuleId |
| iothub-connection-auth-generation-id | Uma ID definida pelo Hub IoT em mensagens do dispositivo para a nuvem. Contém a connectionDeviceGenerationId (de acordo com as Propriedades de identidade de dispositivo) do dispositivo que enviou a mensagem. | Não | connectionDeviceGenerationId |
| iothub-connection-auth-method | Um método de autenticação definido pelo Hub IoT em mensagens do dispositivo para a nuvem. Essa propriedade contém informações sobre o método de autenticação usado para autenticar o dispositivo que envia a mensagem. | Não | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Permite que o dispositivo envie a hora de criação do evento ao enviar dados em um lote. | Yes | creation-time-utc |
| iothub-creation-time-utc | Permite que o dispositivo envie a hora de criação do evento ao enviar uma mensagem em um determinado horário. | Yes | creation-time-utc |
| dt-dataschema | Esse valor é definido pelo hub IoT em mensagens do dispositivo para a nuvem. Ele contém a ID do modelo do dispositivo definida na conexão do dispositivo. | Não | $dt-dataschema |
| dt-subject | O nome do componente que está enviando as mensagens do dispositivo para a nuvem. | Sim | $dt-subject |
Propriedades do aplicativo de mensagens de dispositivo para nuvem
Um uso comum das propriedades de aplicativo é enviar um carimbo de data/hora a partir do dispositivo usando a propriedade iothub-creation-time-utc 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 de nuvem para dispositivo
| Propriedade | Descrição | Configurável pelo usuário? |
|---|---|---|
| message-id | Um identificador configurável pelo usuário para a mensagem utilizada para padrões de resposta à solicitação. Formato: uma cadeia de caracteres que diferencia maiúsculas de minúsculas (com até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits mais - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Sim |
| número de sequência | Um número (exclusivo por fila de dispositivos) atribuído pelo Hub IoT a cada mensagem da nuvem para o dispositivo. | Não |
| para | Um destino especificado em mensagens Da nuvem para o dispositivo . | Não |
| absolute-expiry-time | Data e hora de expiração da mensagem. | Yes |
| correlation-id | Uma cadeia de propriedade em uma mensagem de resposta que geralmente contém a MessageId da solicitação em padrões de solicitação-resposta. | Sim |
| user-id | Uma ID usada para especificar a origem das mensagens. Quando as mensagens são geradas pelo Hub IoT, a ID do usuário é o nome do hub IoT. | Sim |
| iothub-ack | Um gerador de mensagem de comentários. Essa propriedade é usada em mensagens da nuvem para o dispositivo para solicitar ao Hub IoT a geração de mensagens de comentários como resultado do consumo da mensagem pelo dispositivo. Valores possíveis: nenhum (padrão): nenhuma mensagem de comentários é gerada, positivo: ocorrerá o recebimento de uma mensagem de comentários se a mensagem estiver completa, negativo: ocorrerá o recebimento de uma mensagem de comentários se a mensagem expirar (ou se a contagem máxima de entrega tiver sido atingida) sem ser concluída pelo dispositivo ou total: positivos e negativos. | Sim |
Nomes de propriedades do sistema
Os nomes das propriedades do sistema variam de acordo com o ponto de extremidade para o qual as mensagens estão sendo roteadas.
| Nome das propriedades do sistema | Hubs de Eventos | Armazenamento do Azure | Barramento de Serviço | Grade de Eventos |
|---|---|---|---|---|
| ID da mensagem | message-id | messageId | MessageId | message-id |
| Id de Usuário | user-id | userId | UserId | user-id |
| Id do dispositivo de conexão | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Id do módulo de conexão | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| ID de geração de autenticação de conexão | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Método de autenticação de conexão | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | content-type | contentType | ContentType | iothub-content-type |
| contentEncoding | content-encoding | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | N/D | iothub-enqueuedtime |
| CorrelationId | correlation-id | correlationId | CorrelationId | correlation-id |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Tamanho da mensagem
O Hub IoT mede o tamanho da mensagem independentemente do protocolo, considerando apenas a carga 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.
Valores e nomes de propriedade são limitados a caracteres ASCII, portanto, o comprimento das cadeias de caracteres é igual ao tamanho em bytes.
Propriedades antifalsificação
Para evitar a falsificação em mensagens do dispositivo para a nuvem, o Hub IoT carimba todas as mensagens com as seguintes propriedades:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
As duas primeiras contêm a deviceId e a generationId do dispositivo de origem, conforme as Propriedades de identidade do dispositivo.
A propriedade iothub-connection-auth-method contém um objeto JSON serializado com as seguintes propriedades:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Próximas etapas
- Para obter informações sobre limites de tamanho de mensagem no Hub IoT, confira Cotas e limitação do Hub IoT.
- Para saber como criar e ler mensagens do Hub IoT em várias linguagens de programação, confira os Inícios Rápidos.
- Para saber mais sobre a estrutura de eventos não telemétricos gerados por Hub IoT, consulte Esquemas de eventos não telemétricos do Hub IoT.