Partilhar via


Payloads de comandos, propriedades e telemetria

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.

Gorjeta

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 suporta DTDL v2 com uma extensão do IoT Central. Um aplicativo do IoT Central espera receber dados JSON codificados em UTF-8.

Este artigo descreve as cargas úteis 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 útil de comando, mas os exemplos ilustram os tipos de chave.

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

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

Para obter um 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. Esta vista é útil para resolver problemas com a carga útil enviada a partir de um dispositivo. Para visualizar os dados brutos que um dispositivo está enviando:

  1. Navegue até o dispositivo na página Dispositivos .

  2. Selecione a guia Dados brutos :

    Captura de tela que mostra a exibição de dados brutos.

    Nessa exibição, você pode selecionar as colunas a serem exibidas e definir um intervalo de tempo para exibir. 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 DTDL, consulte Telemetria DTDL>. Não é possível iniciar um nome de telemetria usando o _ caractere.

Não crie tipos de telemetria com os seguintes nomes. 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 de dispositivo. Para saber mais, consulte Tutorial: Conectar um IoT Plug and Play vários aplicativos de dispositivo componente. Este tutorial mostra como usar diferentes linguagens de programação para enviar telemetria de um componente.

Importante

Para exibir corretamente a telemetria de componentes hospedados em módulos do IoT Edge, use o IoT Edge versão 1.2.4 ou posterior. Se você usar uma versão anterior, a telemetria de seus 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 primitivos de telemetria que um dispositivo pode transmitir.

O seguinte trecho de um modelo de dispositivo mostra a definição de um boolean tipo de telemetria:

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

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir:

{ "BooleanTelemetry": true }

O seguinte trecho de um modelo de dispositivo mostra a definição de um string tipo de telemetria:

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

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir:

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

O trecho a seguir de um modelo de dispositivo mostra a definição de um integer tipo de telemetria:

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

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir:

{ "IntegerTelemetry": 23 }

O seguinte trecho de um modelo de dispositivo mostra a definição de um double tipo de telemetria:

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

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir:

{ "DoubleTelemetry": 56.78 }

O seguinte trecho de um modelo de dispositivo mostra a definição de um dateTime tipo de telemetria:

{
  "@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 - DateTime os tipos devem estar no formato ISO 8061:

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um duration tipo de telemetria:

{
  "@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 trecho a seguir de um modelo de dispositivo mostra a definição de um Enum tipo de telemetria:

{
  "@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 que se parece com o exemplo a seguir. Os valores possíveis são 0, 1e 2 que são exibidos no IoT Central como Item1, Item2e Item3:

{ "EnumTelemetry": 1 }

O trecho a seguir de um modelo de dispositivo mostra a definição de um Object tipo de telemetria. Este objeto tem três campos com os tipos dateTime, integere 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 que se parece com o exemplo a seguir. DateTime os tipos devem estar em conformidade com a norma ISO 8061. Os valores possíveis para Property3 são 0, 1, e que são exibidos no IoT Central como Item1, Item2e Item3:

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um vector tipo de telemetria:

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

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir:

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um geopoint tipo de telemetria:

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

Nota

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

Um cliente de dispositivo deve enviar a telemetria como JSON que se parece com o exemplo a seguir. O IoT Central exibe o valor como um pino em um mapa:

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

Tipos de evento e estado

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

Nota

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um integer tipo de evento:

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

Um cliente de dispositivo deve enviar os dados do evento como JSON que se parece com o exemplo a seguir:

{ "IntegerEvent": 74 }

O seguinte trecho de um modelo de dispositivo mostra a definição de um integer tipo de estado:

{
  "@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 o estado como JSON que se parece com o exemplo a seguir. Os possíveis valores de estado inteiro são 1, 2ou 3:

{ "IntegerState": 2 }

Propriedades

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

Propriedades em componentes

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

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

Para saber mais, 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 para um serviço.

O seguinte trecho de um modelo de dispositivo mostra a definição de um boolean tipo de propriedade:

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo:

{ "BooleanProperty": false }

O seguinte trecho de um modelo de dispositivo mostra a definição de um long tipo de propriedade:

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo:

{ "LongProperty": 439 }

O seguinte trecho de um modelo de dispositivo mostra a definição de um date tipo de propriedade:

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo. Date os tipos devem estar em conformidade com a norma ISO 8061:

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um duration tipo de propriedade:

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo - as durações devem ser compatíveis com a ISO 8601 Duration:

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um float tipo de propriedade:

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo:

{ "FloatProperty": 1.9 }

O seguinte trecho de um modelo de dispositivo mostra a definição de um string tipo de propriedade:

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo:

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

Tipos complexos

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um Enum tipo de propriedade:

{
  "@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 cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo. Os valores possíveis são 0, 1e que são exibidos no IoT Central como Item1, Item2e Item3:

{ "EnumProperty": 1 }

O trecho a seguir de um modelo de dispositivo mostra a definição de um Object tipo de propriedade. Este 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 cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo:

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um vector tipo de propriedade:

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo:

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

O seguinte trecho de um modelo de dispositivo mostra a definição de um geopoint tipo de propriedade:

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

Nota

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

Um cliente de dispositivo deve enviar uma carga JSON que se parece com o exemplo a seguir como uma propriedade relatada no gêmeo do dispositivo:

{
  "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 thermostat2 componente. 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 IoT Plug and Play vários aplicativos de dispositivo componente.

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

  • value - o valor real da propriedade (normalmente o valor recebido, mas o dispositivo pode decidir relatar um valor diferente).
  • ac - um código de reconhecimento que usa um código de status HTTP.
  • av - uma versão de reconhecimento que se refere ao $version do imóvel desejado. Você pode encontrar esse valor na propriedade desejada JSON payload.
  • ad - uma descrição opcional do agradecimento.

Para saber mais sobre esses campos, consulte Convenções > IoT Plug and Play Respostas de agradecimento

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

{
  "@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. Esta mensagem inclui o número da versão da atualização original recebida do serviço.

Gorjeta

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 trecho a seguir de um modelo de dispositivo mostra a definição de um tipo de propriedade gravável Enum :

{
  "@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. Esta mensagem inclui o número da versão da atualização original recebida do serviço.

Gorjeta

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 do comando DTDL, consulte Comando 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 inclui o nome do componente. Por exemplo, se o comando é chamado getMaxMinReport e o componente é chamado thermostat2, o dispositivo recebe uma solicitação para executar um comando chamado thermostat2*getMaxMinReport.

O trecho a seguir de um modelo de dispositivo mostra a definição de um comando que não tem parâmetros e que não espera que o dispositivo retorne nada:

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

O dispositivo recebe uma carga vazia na solicitação e deve retornar uma carga vazia na resposta com um código de 200 resposta HTTP para indicar sucesso.

O trecho a seguir de um modelo de dispositivo 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 a carga útil da solicitação. O dispositivo deve retornar um valor inteiro como a carga útil de resposta com um 200 código de resposta HTTP para indicar sucesso.

O trecho a seguir de um modelo de dispositivo mostra a definição de um comando que tem um parâmetro object e que espera que o dispositivo retorne um objeto. Neste exemplo, ambos os 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 trecho a seguir mostra um exemplo de carga útil de solicitação enviada para o dispositivo:

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

O trecho a seguir mostra um exemplo de carga útil de resposta enviada do dispositivo. Use um código de 200 resposta HTTP para indicar sucesso:

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

Gorjeta

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

Próximos passos

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