Telemetria, propriedade e payloads de comando

Artigo
02/06/2024

Um modelo de dispositivo define:

Telemetria que um dispositivo envia para um serviço.
Propriedades que um dispositivo sincroniza com um serviço.
Comandos que o serviço chama em um dispositivo.

Dica

O Azure IoT Central é um serviço que segue as convenções Plug and Play. No IoT Central, o modelo de dispositivo faz parte de um modelo de dispositivo. Atualmente, o IoT Central oferece suporte ao DTDL v2 com uma extensão do IoT Central. Um aplicativo IoT Central espera receber dados JSON codificados em UTF-8.

Este artigo descreve as cargas JSON que os dispositivos enviam e recebem para telemetria, propriedades e comandos definidos em um modelo de dispositivo DTDL.

O artigo não descreve todos os tipos possíveis de telemetria, propriedade e carga de comando, mas os exemplos ilustram tipos de chave.

Cada exemplo mostra um trecho do modelo de dispositivo que define o tipo e as cargas JSON de exemplo para ilustrar como o dispositivo deve interagir com um serviço com reconhecimento de Plug and Play, como o IoT Central.

Os trechos JSON de exemplo neste artigo usam DTDL (Digital Twin Definition Language) V2. Há também algumas extensões DTDL que o IoT Central usa.

Para obter o código de dispositivo de exemplo que mostra algumas dessas cargas úteis em uso, consulte o tutorial Conectar um aplicativo de dispositivo IoT Plug and Play de exemplo em execução no Linux ou Windows ao Hub IoT ou o tutorial Criar e conectar um aplicativo cliente ao seu aplicativo do Azure IoT Central.

Exibir dados brutos

Se você estiver usando o IoT Central, poderá exibir os dados brutos que um dispositivo envia para um aplicativo. Essa exibição é útil para solucionar problemas com o conteúdo enviado de um dispositivo. Para exibir os dados brutos que um dispositivo está enviando:

Na página Dispositivos, navegue até o dispositivo desejado.
Selecione a guia Dados brutos :

Nessa exibição, você pode selecionar as colunas a serem exibidas e definir um intervalo de tempo para exibição. A coluna Dados não modelados mostra dados do dispositivo que não correspondem a nenhuma propriedade ou definição de telemetria no modelo de dispositivo.

Para obter mais dicas de solução de problemas, consulte Solucionar problemas por que os dados de seus dispositivos não estão aparecendo no Azure IoT Central.

Telemetria

Para saber mais sobre as regras de nomenclatura de telemetria da DTDL, consulte Telemetria > da DTDL. Não é possível iniciar um nome de telemetria usando o caractere _.

Não crie tipos de telemetria com os nomes a seguir. O IoT Central usa esses nomes reservados internamente. Se você tentar usar esses nomes, o IoT Central ignorará seus dados:

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

Telemetria em componentes

Se a telemetria for definida em um componente, adicione uma propriedade de mensagem personalizada chamada $.sub com o nome do componente, conforme definido no modelo do dispositivo. Para saber mais, consulte Tutorial: Conectar um aplicativo de dispositivo de vários componentes do IoT Plug and Play. Este tutorial mostra como usar diferentes linguagens de programação para enviar telemetria de um componente.

Importante

Para exibir a telemetria de componentes hospedados em módulos do IoT Edge corretamente, use o IoT Edge versão 1.2.4 ou posterior. Se usar uma versão anterior, a telemetria dos componentes nos módulos do IoT Edge será exibida como _unmodeleddata.

Telemetria em interfaces herdadas

Se a telemetria for definida em uma interface herdada, o dispositivo enviará a telemetria como se estivesse definida na interface raiz. Dado o seguinte modelo de dispositivo:

[
    {
        "@id": "dtmi:contoso:device;1",
        "@type": "Interface",
        "contents": [
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": {
                    "en": "Device Name"
                },
                "name": "DeviceName",
                "schema": "string"
            }
        ],
        "displayName": {
            "en": "Contoso Device"
        },
        "extends": [
            "dtmi:contoso:sensor;1"
        ],
        "@context": [
            "dtmi:iotcentral:context;2",
            "dtmi:dtdl:context;2"
        ]
    },
    {
        "@context": [
            "dtmi:iotcentral:context;2",
            "dtmi:dtdl:context;2"
        ],
        "@id": "dtmi:contoso:sensor;1",
        "@type": [
            "Interface",
            "NamedInterface"
        ],
        "contents": [
            {
                "@type": [
                    "Telemetry",
                    "NumberValue"
                ],
                "displayName": {
                    "en": "Meter Voltage"
                },
                "name": "MeterVoltage",
                "schema": "double"
            }
        ],
        "displayName": {
            "en": "Contoso Sensor"
        },
        "name": "ContosoSensor"
    }
]

O dispositivo envia telemetria de tensão do medidor usando a seguinte carga útil. O dispositivo não inclui o nome da interface na carga útil:

{
    "MeterVoltage": 5.07
}

Tipos primitivos

Esta seção mostra exemplos de tipos de telemetria primitiva que um dispositivo pode transmitir.

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria boolean:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "BooleanTelemetry"
  },
  "name": "BooleanTelemetry",
  "schema": "boolean"
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir:

{ "BooleanTelemetry": true }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria string:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "StringTelemetry"
  },
  "name": "StringTelemetry",
  "schema": "string"
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir:

{ "StringTelemetry": "A string value - could be a URL" }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria integer:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "IntegerTelemetry"
  },
  "name": "IntegerTelemetry",
  "schema": "integer"
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir:

{ "IntegerTelemetry": 23 }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria double:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "DoubleTelemetry"
  },
  "name": "DoubleTelemetry",
  "schema": "double"
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir:

{ "DoubleTelemetry": 56.78 }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria dateTime:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "DateTimeTelemetry"
  },
  "name": "DateTimeTelemetry",
  "schema": "dateTime"
}

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir – os tipos de DateTime devem estar no formato ISO 8061:

{ "DateTimeTelemetry": "2020-08-30T19:16:13.853Z" }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria duration:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "DurationTelemetry"
  },
  "name": "DurationTelemetry",
  "schema": "duration"
}

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir – as durações devem estar no formato ISO 8601:

{ "DurationTelemetry": "PT10H24M6.169083011336625S" }

Tipos complexos

Esta seção mostra exemplos de tipos complexos de telemetria que um dispositivo pode transmitir.

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria Enum:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "EnumTelemetry"
  },
  "name": "EnumTelemetry",
  "schema": {
    "@type": "Enum",
    "displayName": {
      "en": "Enum"
    },
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Item1"
        },
        "enumValue": 0,
        "name": "Item1"
      },
      {
        "displayName": {
          "en": "Item2"
        },
        "enumValue": 1,
        "name": "Item2"
      },
      {
        "displayName": {
          "en": "Item3"
        },
        "enumValue": 2,
        "name": "Item3"
      }
    ]
  }
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir. Os valores possíveis são 0, 1 e 2 exibidos no IoT Central como Item1, Item2 e Item3:

{ "EnumTelemetry": 1 }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria Object: Esse objeto tem três campos com tipos dateTime, integer e Enum:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "ObjectTelemetry"
  },
  "name": "ObjectTelemetry",
  "schema": {
    "@type": "Object",
    "displayName": {
      "en": "Object"
    },
    "fields": [
      {
        "displayName": {
          "en": "Property1"
        },
        "name": "Property1",
        "schema": "dateTime"
      },
      {
        "displayName": {
          "en": "Property2"
        },
        "name": "Property2",
        "schema": "integer"
      },
      {
        "displayName": {
          "en": "Property3"
        },
        "name": "Property3",
        "schema": {
          "@type": "Enum",
          "displayName": {
            "en": "Enum"
          },
          "valueSchema": "integer",
          "enumValues": [
            {
              "displayName": {
                "en": "Item1"
              },
              "enumValue": 0,
              "name": "Item1"
            },
            {
              "displayName": {
                "en": "Item2"
              },
              "enumValue": 1,
              "name": "Item2"
            },
            {
              "displayName": {
                "en": "Item3"
              },
              "enumValue": 2,
              "name": "Item3"
            }
          ]
        }
      }
    ]
  }
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir. Os tipos DateTime devem ser compatíveis com ISO 8061. Os valores possíveis para Property3 são 0 e 1, e são exibidos no IoT Central como Item1, Item2 e Item3:

{
  "ObjectTelemetry": {
      "Property1": "2020-09-09T03:36:46.195Z",
      "Property2": 37,
      "Property3": 2
  }
}

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria vector:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "VectorTelemetry"
  },
  "name": "VectorTelemetry",
  "schema": "vector"
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir:

{
  "VectorTelemetry": {
    "x": 74.72395045538597,
    "y": 74.72395045538597,
    "z": 74.72395045538597
  }
}

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de telemetria geopoint:

{
  "@type": "Telemetry",
  "displayName": {
    "en": "GeopointTelemetry"
  },
  "name": "GeopointTelemetry",
  "schema": "geopoint"
}

Observação

O tipo de esquema de geoponto faz parte da extensão do IoT Central para DTDL. O IoT Central atualmente oferece suporte ao tipo de esquema geoponto e ao tipo semântico localização para compatibilidade com versões anteriores.

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir. O IoT Central exibe o valor como um marcador em um mapa:

{
  "GeopointTelemetry": {
    "lat": 47.64263,
    "lon": -122.13035,
    "alt": 0
  }
}

Tipos de evento e de estado

Esta seção mostra exemplos de eventos e estados de telemetria que um dispositivo envia para um aplicativo do IoT Central.

Observação

Os tipos de esquema de evento e estado fazem parte da extensão do IoT Central para DTDL.

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de evento integer:

{
  "@type": [
    "Telemetry",
    "Event"
  ],
  "displayName": {
    "en": "IntegerEvent"
  },
  "name": "IntegerEvent",
  "schema": "integer"
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir:

{ "IntegerEvent": 74 }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de estado integer:

{
  "@type": [
    "Telemetry",
    "State"
  ],
  "displayName": {
    "en": "IntegerState"
  },
  "name": "IntegerState",
  "schema": {
    "@type": "Enum",
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Level1"
        },
        "enumValue": 1,
        "name": "Level1"
      },
      {
        "displayName": {
          "en": "Level2"
        },
        "enumValue": 2,
        "name": "Level2"
      },
      {
        "displayName": {
          "en": "Level3"
        },
        "enumValue": 3,
        "name": "Level3"
      }
    ]
  }
}

Um cliente de dispositivo deve enviar a telemetria como JSON semelhante ao exemplo a seguir: Os valores inteiros de estado possíveis são 1, 2 ou 3:

{ "IntegerState": 2 }

Propriedades

Para saber mais sobre as regras de nomenclatura da propriedade da DTDL, consulte a Propriedade > da DTDL. Não é possível iniciar um nome de propriedade usando o caractere _.

Propriedades em componentes

Se a propriedade for definida em um componente, empacote a propriedade no nome do componente. O exemplo a seguir define o maxTempSinceLastReboot no componente thermostat2. O marcador __t indica que esta seção define um componente:

{
  "thermostat2" : {  
    "__t" : "c",  
    "maxTempSinceLastReboot" : 38.7
    } 
}

Para mais informações, consulte Tutorial: Criar e conectar um aplicativo cliente ao seu aplicativo do Azure IoT Central.

Tipos primitivos

Esta seção mostra exemplos de tipos de propriedade primitiva que um dispositivo envia a um serviço.

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade boolean:

{
  "@type": "Property",
  "displayName": {
    "en": "BooleanProperty"
  },
  "name": "BooleanProperty",
  "schema": "boolean",
  "writable": false
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo:

{ "BooleanProperty": false }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade long:

{
  "@type": "Property",
  "displayName": {
    "en": "LongProperty"
  },
  "name": "LongProperty",
  "schema": "long",
  "writable": false
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo:

{ "LongProperty": 439 }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade date:

{
  "@type": "Property",
  "displayName": {
    "en": "DateProperty"
  },
  "name": "DateProperty",
  "schema": "date",
  "writable": false
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo. Os tipos Date devem ser compatíveis com ISO 8061:

{ "DateProperty": "2020-05-17" }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade duration:

{
  "@type": "Property",
  "displayName": {
    "en": "DurationProperty"
  },
  "name": "DurationProperty",
  "schema": "duration",
  "writable": false
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo – as durações devem ser compatíveis com o formato ISO 8601:

{ "DurationProperty": "PT10H24M6.169083011336625S" }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade float:

{
  "@type": "Property",
  "displayName": {
    "en": "FloatProperty"
  },
  "name": "FloatProperty",
  "schema": "float",
  "writable": false
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo:

{ "FloatProperty": 1.9 }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade string:

{
  "@type": "Property",
  "displayName": {
    "en": "StringProperty"
  },
  "name": "StringProperty",
  "schema": "string",
  "writable": false
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo:

{ "StringProperty": "A string value - could be a URL" }

Tipos complexos

Esta seção mostra exemplos de tipos de propriedade complexos que um dispositivo envia a um serviço.

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade Enum:

{
  "@type": "Property",
  "displayName": {
    "en": "EnumProperty"
  },
  "name": "EnumProperty",
  "writable": false,
  "schema": {
    "@type": "Enum",
    "displayName": {
      "en": "Enum"
    },
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Item1"
        },
        "enumValue": 0,
        "name": "Item1"
      },
      {
        "displayName": {
          "en": "Item2"
        },
        "enumValue": 1,
        "name": "Item2"
      },
      {
        "displayName": {
          "en": "Item3"
        },
        "enumValue": 2,
        "name": "Item3"
      }
    ]
  }
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo. Os valores possíveis são 0, 1, exibidos no IoT Central como Item1, Item2e Item3:

{ "EnumProperty": 1 }

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade Object. Esse objeto tem dois campos com tipos string e integer:

{
  "@type": "Property",
  "displayName": {
    "en": "ObjectProperty"
  },
  "name": "ObjectProperty",
  "writable": false,
  "schema": {
    "@type": "Object",
    "displayName": {
      "en": "Object"
    },
    "fields": [
      {
        "displayName": {
          "en": "Field1"
        },
        "name": "Field1",
        "schema": "integer"
      },
      {
        "displayName": {
          "en": "Field2"
        },
        "name": "Field2",
        "schema": "string"
      }
    ]
  }
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo:

{
  "ObjectProperty": {
    "Field1": 37,
    "Field2": "A string value"
  }
}

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade vector:

{
  "@type": "Property",
  "displayName": {
    "en": "VectorProperty"
  },
  "name": "VectorProperty",
  "schema": "vector",
  "writable": false
}

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo:

{
  "VectorProperty": {
    "x": 74.72395045538597,
    "y": 74.72395045538597,
    "z": 74.72395045538597
  }
}

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade geopoint:

{
  "@type": "Property",
  "displayName": {
    "en": "GeopointProperty"
  },
  "name": "GeopointProperty",
  "schema": "geopoint",
  "writable": false
}

Observação

Um dispositivo cliente deve enviar um conteúdo JSON similar ao exemplo a seguir como uma propriedade relatada no dispositivo gêmeo:

{
  "GeopointProperty": {
    "lat": 47.64263,
    "lon": -122.13035,
    "alt": 0
  }
}

Tipos de propriedade graváveis

Esta seção mostra exemplos de tipos de propriedade graváveis que um dispositivo recebe de um serviço.

Se a propriedade gravável for definida em um componente, a mensagem de propriedade desejada incluirá o nome do componente. O exemplo a seguir mostra a mensagem solicitando que o dispositivo atualize o targetTemperature no componente thermostat2. O marcador __t indica que esta seção define um componente:

{
  "thermostat2": {
    "targetTemperature": {
      "value": 57
    },
    "__t": "c"
  },
  "$version": 3
}

Para saber mais, consulte Conectar um aplicativo de dispositivo de vários componentes do IoT Plug and Play.

O dispositivo ou módulo deve confirmar que recebeu a propriedade enviada a uma propriedade relatada. A propriedade reportada deve incluir:

value-o valor efetivo da propriedade (normalmente o valor recebido, mas o dispositivo pode decidir o relatório de um valor diferente).
ac-um código de confirmação que usa um código de estado HTTP.
av-uma versão da confirmação que se refere à$versionpropriedade desejada. Você pode encontrar este valor no payload JSON da propriedade desejada.
ad-uma descrição de confirmação opcional.

Para saber mais sobre esses campos, consulte Respostas de confirmação de > convenções do IoT Plug and Play

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade string gravável:

{
  "@type": "Property",
  "displayName": {
    "en": "StringPropertyWritable"
  },
  "name": "StringPropertyWritable",
  "writable": true,
  "schema": "string"
}

O dispositivo recebe a seguinte carga útil do serviço:

{  
  "StringPropertyWritable": "A string from IoT Central", "$version": 7
}

O dispositivo deve enviar a seguinte carga JSON para o serviço depois de processar a atualização. Essa mensagem inclui o número da versão da atualização original recebida do serviço.

Dica

Se o serviço for IoT Central, ele marcará a propriedade como sincronizada na interface do usuário quando receber esta mensagem:

{
  "StringPropertyWritable": {
    "value": "A string from IoT Central",
    "ac": 200,
    "ad": "completed",
    "av": 7
  }
}

O snippet de um modelo de dispositivo abaixo mostra a definição de um tipo de propriedade Enum gravável:

{
  "@type": "Property",
  "displayName": {
    "en": "EnumPropertyWritable"
  },
  "name": "EnumPropertyWritable",
  "writable": true,
  "schema": {
    "@type": "Enum",
    "displayName": {
      "en": "Enum"
    },
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Item1"
        },
        "enumValue": 0,
        "name": "Item1"
      },
      {
        "displayName": {
          "en": "Item2"
        },
        "enumValue": 1,
        "name": "Item2"
      },
      {
        "displayName": {
          "en": "Item3"
        },
        "enumValue": 2,
        "name": "Item3"
      }
    ]
  }
}

O dispositivo recebe a seguinte carga útil do serviço:

{  
  "EnumPropertyWritable":  1 , "$version": 10
}

O dispositivo deve enviar a seguinte carga JSON para o serviço depois de processar a atualização. Essa mensagem inclui o número da versão da atualização original recebida do serviço.

Dica

Se o serviço for IoT Central, ele marcará a propriedade como sincronizada na interface do usuário quando receber esta mensagem:

{
  "EnumPropertyWritable": {
    "value": 1,
    "ac": 200,
    "ad": "completed",
    "av": 10
  }
}

Comandos

Para saber mais sobre as regras de nomenclatura de comando da DTDL, consulte Comando > da DTDL. Não é possível iniciar um nome de comando usando o caractere _.

Se o comando for definido em um componente, o nome do comando que o dispositivo recebe incluirá o nome do componente. Por exemplo, se o comando for chamado getMaxMinReport e o componente for chamado thermostat2, o dispositivo receberá uma solicitação para executar um comando chamado thermostat2*getMaxMinReport.

O snippet de um modelo de dispositivo abaixo mostra a definição de um comando que não tem parâmetros e que não espera que o dispositivo retorne algo:

{
  "@type": "Command",
  "displayName": {
    "en": "CommandBasic"
  },
  "name": "CommandBasic"
}

O dispositivo recebe um conteúdo vazio na solicitação e deve retornar um conteúdo vazio na resposta com um código de resposta HTTP 200 para indicar êxito.

O snippet de um modelo de dispositivo abaixo mostra a definição de um comando que tem um parâmetro inteiro e que espera que o dispositivo retorne um valor inteiro:

{
  "@type": "Command",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "RequestParam"
    },
    "name": "RequestParam",
    "schema": "integer"
  },
  "response": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "ResponseParam"
    },
    "name": "ResponseParam",
    "schema": "integer"
  },
  "displayName": {
    "en": "CommandSimple"
  },
  "name": "CommandSimple"
}

O dispositivo recebe um valor inteiro como o conteúdo da solicitação. O dispositivo deve retornar um valor inteiro como o conteúdo de resposta com um código de resposta HTTP 200 para indicar êxito.

O snippet de um modelo de dispositivo abaixo mostra a definição de um comando que tem um parâmetro de objeto e que espera que o dispositivo retorne um objeto: Neste exemplo, os dois objetos têm campos inteiros e de cadeia de caracteres:

{
  "@type": "Command",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "RequestParam"
    },
    "name": "RequestParam",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "Field1"
          },
          "name": "Field1",
          "schema": "integer"
        },
        {
          "displayName": {
            "en": "Field2"
          },
          "name": "Field2",
          "schema": "string"
        }
      ]
    }
  },
  "response": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "ResponseParam"
    },
    "name": "ResponseParam",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "Field1"
          },
          "name": "Field1",
          "schema": "integer"
        },
        {
          "displayName": {
            "en": "Field2"
          },
          "name": "Field2",
          "schema": "string"
        }
      ]
    }
  },
  "displayName": {
    "en": "CommandComplex"
  },
  "name": "CommandComplex"
}

O snippet abaixo mostra um exemplo de conteúdo de solicitação enviado para o dispositivo:

{ "Field1": 56, "Field2": "A string value" }

O snippet abaixo mostra um exemplo de conteúdo de resposta enviado pelo dispositivo: Use um código de resposta HTTP 200 para indicar êxito:

{ "Field1": 87, "Field2": "Another string value" }

Dica

O IoT Central tem suas próprias convenções para implementar comandos de longa execução e comandos offline.

Próximas etapas

Agora que você aprendeu sobre cargas úteis do dispositivo, uma próxima etapa sugerida é ler o Guia do desenvolvedor do dispositivo.

Telemetria, propriedade e payloads de comando

Exibir dados brutos

Telemetria

Telemetria em componentes

Telemetria em interfaces herdadas

Tipos primitivos

Tipos complexos

Tipos de evento e de estado

Propriedades

Propriedades em componentes

Tipos primitivos

Tipos complexos

Tipos de propriedade graváveis

Comandos

Próximas etapas

Recursos adicionais