Criar e ler mensagens do Hub IoT

  • Artigo

Para dar suporte à interoperabilidade perfeita 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. Eles podem ser usados no roteamento de 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 do dispositivo para nuvem do Hub IoT são mais semelhantes a eventos de Hubs de Eventos do que a mensagens do Barramento de Serviço na medida em que há um alto volume de eventos passando pelo serviço que pode ser lido por vários leitores.

Uma mensagem do Hub IoT consiste em:

  • Um conjunto predeterminado de propriedades do sistema, conforme listado abaixo.

  • 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. Confira os guias do desenvolvedor MQTT e AMQP relacionados para obter detalhes.

Os valores e nomes de propriedade podem conter apenas caracteres alfanuméricos ASCII mais {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} quando você envia mensagens de dispositivo para nuvem usando o protocolo HTTPS ou envia mensagens da nuvem para dispositivo.

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 obter mais informações, consulte os aprimoramentos de mensagens.

Para obter mais informações de como codificar e decodificar mensagens enviadas usando diferentes protocolos, confira SDKs de IoT do Azure.

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 os dados sejam processados corretamente no destino (por exemplo, JSON processado como uma cadeia de caracteres analisável e não como dados binários codificados em Base64), você precisa fornecer 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, você precisa fornecer um objeto JSON válido para a mensagem e definir a propriedade de tipo de conteúdo da mensagem como application/json;charset=utf-8.

Um corpo de mensagem válido e roteável pode ser semelhante ao seguinte:

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

Propriedades de Sistema das mensagens D2C do Hub IoT

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 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. 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. Quando as mensagens são geradas pelo Hub IoT, são definidas como {iot hub name}. 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 de aplicativo de mensagens D2C do Hub IoT

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, 2021-04-21T11:30:16-07:00 é inválido:

{
  "applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
  "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 de Sistema das mensagens C2D do Hub IoT

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 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. 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, são definidas como {iot hub name}. 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 das 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. Consulte a tabela a seguir para obter detalhes sobre esses nomes.

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