Partilhar via

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.

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 e o tamanho certos do Hub IoT para sua solução.

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 com 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 dado.

Cada protocolo de dispositivo implementa propriedades de configuração de maneiras diferentes. Para obter mais informações, consulte Comunicar-se com um hub IoT usando o protocolo MQTT e Comunicar-se com seu hub IoT usando o protocolo AMQP.

Ao enviar mensagens de dispositivo para a nuvem usando o protocolo HTTPS, ou ao enviar mensagens da nuvem para o dispositivo, os nomes e valores das propriedades 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 padrão de mensagens/eventos de um hub IoT durante 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 no seu deviceId de origem.

  • Conforme explicado em Controlar o acesso ao Hub IoT usando a ID do Microsoft Entra, o Hub IoT habilita a autenticação por dispositivo e o controle de acesso.

  • Você pode carimbar mensagens com informações que vão para as propriedades da aplicação. Para obter mais informações, consulte Enriquecimento de mensagens para mensagens do Hub IoT do dispositivo para a nuvem.

Nota

Cada protocolo do Hub IoT fornece uma propriedade de tipo de conteúdo de mensagem, que é respeitada ao rotear 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 do dispositivo para a nuvem

Propriedade Descrição Definido pelo Utilizador? Palavra-chave para
consulta de encaminhamento
ID da mensagem Um identificador configurável pelo usuário para a mensagem usada para padrões de solicitação-resposta. Formato: Uma cadeia sensível a maiúsculas e minúsculas (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits mais - : . + % _ # * ? ! ( ) , = @ ; $ '. Sim ID de mensagem
iothub-enqueuedtime Data e hora em que o Hub IoT recebe a mensagem do dispositivo para a nuvem . Não enqueuedTime
ID de utilizador Um ID usado para especificar a origem das mensagens. Sim ID de Utilizador
id-do-dispositivo-de-conexão-do-iothub Um ID definido pelo Hub IoT em mensagens de dispositivo para nuvem. Ele contém o deviceId do dispositivo que enviou a mensagem. Não IdDoDispositivoDeConexão
iothub-conexão-módulo-id Um ID definido pelo Hub IoT em mensagens de dispositivo para nuvem. Ele contém o moduleId do dispositivo que enviou a mensagem. Não ID do Módulo de Conexão
iothub-connection-auth-gen-id Um ID definido pelo Hub IoT em mensagens de dispositivo para nuvem. Ele contém o connectionDeviceGenerationId (de acordo com as propriedades de identidade do dispositivo) do dispositivo que enviou a mensagem. Não idDeGeraçãoDeDispositivoDeConexão
método de autenticação de conexão do iothub Um método de autenticação definido pelo Hub IoT em mensagens de dispositivo para nuvem. Esta propriedade contém informações sobre o método de autenticação usado para autenticar o dispositivo que envia a mensagem. Não MétodoDeAutenticaçãoDeConexão
iothub-app-iothub-hora-de-criação-utc Permite que o dispositivo envie o tempo de criação do evento ao enviar dados em lote. Sim data/hora de criação-utc
iothub-hora-de-criação-utc Permite que o dispositivo envie o tempo de criação do evento ao enviar uma mensagem de cada vez. Sim data/hora de criação-utc
Esquema de Dados DT O hub IoT define esse valor em mensagens de dispositivo para nuvem. Ele contém o ID do modelo do dispositivo definido na conexão do dispositivo. Não $dt-dataschema
dt-sujeito O nome do componente que está enviando as mensagens do dispositivo para a nuvem. Sim $dt-sujeito

Propriedades da aplicação de mensagens de dispositivo para a nuvem

Um uso comum das propriedades da aplicação é enviar uma marca temporal do dispositivo usando a iothub-creation-time-utc propriedade para registrar quando o dispositivo envia a mensagem. 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

Propriedade Descrição Definido pelo Utilizador?
ID da mensagem Um identificador configurável pelo usuário para a mensagem usada para padrões de solicitação-resposta. Formato: Uma cadeia sensível a maiúsculas e minúsculas (até 128 caracteres) de caracteres alfanuméricos ASCII de 7 bits mais - : . + % _ # * ? ! ( ) , = @ ; $ '. Sim
número-sequência Um número (exclusivo por fila de dispositivos) atribuído pelo Hub IoT a cada mensagem de nuvem para dispositivo. Não
para Um destino especificado em mensagens da nuvem para o dispositivo . Não
tempo de expiração absoluto Data e hora de expiração da mensagem. Sim
ID de Correlação Uma propriedade de cadeia de caracteres numa mensagem de resposta que normalmente contém o MessageId do pedido, em padrões pedido-resposta. Sim
ID de utilizador Um ID usado para especificar a origem das mensagens. Quando o Hub IoT gera mensagens, o ID do usuário é o nome do hub IoT. Sim
IOTHUB-ACK Um gerador de mensagens de feedback. Essa propriedade é usada em mensagens da nuvem para o dispositivo para solicitar que o Hub IoT gere mensagens de feedback como resultado do consumo da mensagem pelo dispositivo. Valores possíveis: nenhum (padrão): nenhuma mensagem de feedback é gerada, positivo: recebe uma mensagem de feedback se a mensagem foi concluída, negativo: recebe uma mensagem de feedback se a mensagem expirou (ou a contagem máxima de entrega foi atingida) sem ser concluída pelo dispositivo, ou completa: positiva e negativa. Sim

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.

Nome da propriedade do sistema Hubs de Eventos Armazenamento do Azure Barramento de Serviço Event Grid
ID da mensagem ID da mensagem ID de mensagem ID de Mensagem ID da mensagem
ID do utilizador ID de utilizador ID de Utilizador Id do usuário ID de utilizador
ID do dispositivo de conexão id-do-dispositivo-de-conexão-do-iothub IdDoDispositivoDeConexão id-do-dispositivo-de-conexão-do-iothub id-do-dispositivo-de-conexão-do-iothub
ID do módulo de conexão iothub-conexão-módulo-id ID do Módulo de Conexão iothub-conexão-módulo-id iothub-conexão-módulo-id
ID de geração de autenticação de conexão iothub-connection-auth-gen-id idDeGeraçãoDeDispositivoDeConexão iothub-connection-auth-gen-id iothub-connection-auth-gen-id
Método de autenticação de conexão método de autenticação de conexão do iothub MétodoDeAutenticaçãoDeConexão método de autenticação de conexão do iothub método de autenticação de conexão do iothub
tipo de conteúdo tipo de conteúdo tipo de conteúdo Tipo de conteúdo iothub-content-type
codificação de conteúdo codificação de conteúdo codificação de conteúdo Codificação de conteúdo iothub-codificação de conteúdo
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime N/A iothub-enqueuedtime
CorrelationId ID de Correlação correlationId CorrelationId ID de Correlação
Esquema de Dados DT Esquema de Dados DT Esquema de Dados DT Esquema de Dados DT Esquema de Dados DT
dt-sujeito dt-sujeito dt-sujeito dt-sujeito dt-sujeito

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 propriedades do utilizador.

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-de-ID
  • iothub-connection-auth-método

Os dois primeiros contêm o deviceId e o 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

  • Last updated on