Полезные данные телеметрии, свойств и команд

Модель устройства определяет следующее:

Данные телеметрии устройства отправляются в службу.
Свойства устройства синхронизируются со службой.
Команды, вызываемые службой на устройстве.

Подсказка

Azure IoT Central — это служба, которая соответствует соглашениям Plug and Play. В IoT Central модель устройства является частью шаблона устройства. IoT Central в настоящее время поддерживает DTDL версии 2 с расширением IoT Central. Приложение IoT Central ожидает получения данных JSON в кодировке UTF-8.

В этой статье описываются полезные данные JSON, которые устройства отправляют и получают для телеметрии, свойств и команд, определенных в модели устройства DTDL.

В статье не описаны все возможные типы телеметрии, свойств и полезных данных команд, но в примерах показаны ключевые типы.

В каждом примере показан фрагмент кода из модели устройства, который определяет тип и пример полезных данных JSON для иллюстрации того, как устройство должно взаимодействовать с службой поддержки Plug and Play, например IoT Central.

Пример фрагментов JSON в этой статье использует язык определения цифровых двойников (DTDL) версии 2. Существуют также некоторые расширения DTDL, которые использует IoT Central .

Пример кода устройства, отображающего некоторые из этих полезных данных, см. в следующем руководстве. Создание и подключение клиентского приложения к приложению Azure IoT Central.

Просмотр необработанных данных

Если вы используете IoT Central, вы можете просмотреть необработанные данные, которые устройство отправляет в приложение. Это представление полезно для устранения проблем с полезными данными, отправленными с устройства. Чтобы просмотреть необработанные данные, которое отправляет устройство, выполните следующие действия.

Перейдите к устройству на странице "Устройства".
Перейдите на вкладку "Необработанные данные ":

В этом представлении можно выбрать отображаемые столбцы и задать диапазон времени для просмотра. В столбце немоделированных данных отображаются данные с устройства, которое не соответствует ни одному свойству или определениям телеметрии в шаблоне устройства.

Дополнительные советы по устранению неполадок см. в статье "Устранение неполадок, почему данные с устройств не отображаются в Azure IoT Central".

Телеметрия

Дополнительные сведения о правилах именования телеметрии DTDL см. в статье DTDL > Telemetry. Невозможно запустить имя телеметрии с помощью символа _ .

Не создавайте типы телеметрии со следующими именами. IoT Central использует эти зарезервированные имена внутренне. Если вы пытаетесь использовать эти имена, IoT Central игнорирует данные:

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

Телеметрия в компонентах

Если данные телеметрии определены в компоненте, добавьте настраиваемое свойство сообщения, вызываемое $.sub именем компонента, как определено в модели устройства.

Это важно

Чтобы правильно отобразить данные телеметрии из компонентов, размещенных в модулях IoT Edge, используйте IoT Edge версии 1.2.4 или более поздней. Если вы используете более раннюю версию, данные телеметрии из компонентов в модулях IoT Edge отображаются как _unmodeleddata.

Телеметрия в унаследованных интерфейсах

Если данные телеметрии определены в наследуемом интерфейсе, устройство отправляет данные телеметрии, как если бы оно определено в корневом интерфейсе. Учитывая следующую модель устройства:

[
    {
        "@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"
    }
]

Устройство отправляет данные телеметрии счетчика напряжения с помощью следующей полезных данных. Устройство не включает имя интерфейса в полезные данные:

{
    "MeterVoltage": 5.07
}

Примитивные типы

В этом разделе показаны примеры примитивных типов телеметрии, которые устройство может передавать.

В следующем фрагменте кода модели устройства показано определение boolean типа телеметрии:

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

Клиент устройства должен отправить данные телеметрии в формате JSON, который выглядит следующим образом:

{ "BooleanTelemetry": true }

В следующем фрагменте кода модели устройства показано определение string типа телеметрии:

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

Клиент устройства должен отправить данные телеметрии в формате JSON, который выглядит следующим образом:

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

В следующем фрагменте кода модели устройства показано определение integer типа телеметрии:

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

Клиент устройства должен отправить данные телеметрии в формате JSON, который выглядит следующим образом:

{ "IntegerTelemetry": 23 }

В следующем фрагменте кода модели устройства показано определение double типа телеметрии:

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

Клиент устройства должен отправить данные телеметрии в формате JSON, который выглядит следующим образом:

{ "DoubleTelemetry": 56.78 }

В следующем фрагменте кода модели устройства показано определение dateTime типа телеметрии:

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

Клиент устройства должен отправлять данные телеметрии в формате JSON, который выглядит следующим образом: DateTime типы должны быть в формате ISO 8061:

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

В следующем фрагменте кода модели устройства показано определение duration типа телеметрии:

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

Клиент устройства должен отправлять данные телеметрии в формате JSON, который выглядит следующим образом: длительность должна быть в формате ISO 8601:

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

Сложные типы

В этом разделе показаны примеры сложных типов телеметрии, которые устройство может передавать.

В следующем фрагменте кода модели устройства показано определение 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"
      }
    ]
  }
}

Клиент устройства должен отправлять данные телеметрии в формате JSON, который выглядит следующим образом. Возможные значения: , 0и 1 они отображаются 2в IoT Central как Item1, Item2и Item3:

{ "EnumTelemetry": 1 }

В следующем фрагменте кода модели устройства показано определение Object типа телеметрии. Этот объект содержит три поля с типами dateTimeи integerEnum:

{
  "@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"
            }
          ]
        }
      }
    ]
  }
}

Клиент устройства должен отправлять данные телеметрии в формате JSON, который выглядит следующим образом. DateTime типы должны соответствовать стандарту ISO 8061. Возможные значения: Property3 , 0и они отображаются 1в IoT Central как Item1, Item2и Item3:

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

В следующем фрагменте кода модели устройства показано определение vector типа телеметрии:

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

Клиент устройства должен отправить данные телеметрии в формате JSON, который выглядит следующим образом:

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

В следующем фрагменте кода модели устройства показано определение geopoint типа телеметрии:

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

Замечание

Тип схемы геоточечных точек является частью расширения IoT Central для DTDL. IoT Central в настоящее время поддерживает тип схемы геоточечных точек и семантический тип расположения для обратной совместимости.

Клиент устройства должен отправлять данные телеметрии в формате JSON, который выглядит следующим образом. IoT Central отображает значение в виде закрепления на карте:

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

Типы событий и состояний

В этом разделе показаны примеры событий телеметрии и состояния, которые устройство отправляет в приложение IoT Central.

Замечание

Типы схем событий и состояний являются частью расширения IoT Central для DTDL.

В следующем фрагменте кода модели устройства показано определение integer типа события:

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

Клиент устройства должен отправлять данные события в формате JSON, который выглядит следующим образом:

{ "IntegerEvent": 74 }

В следующем фрагменте кода модели устройства показано определение 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"
      }
    ]
  }
}

Клиент устройства должен отправить состояние в формате JSON, которое выглядит следующим образом. Возможные целые значения состояния : 12или 3:

{ "IntegerState": 2 }

Свойства

Дополнительные сведения о правилах именования свойств DTDL см. в разделе "Свойство DTDL>". Невозможно запустить имя свойства с помощью символа _ .

Свойства компонентов

Если свойство определено в компоненте, заключите свойство в имя компонента. В следующем примере устанавливается maxTempSinceLastReboot компонент thermostat2 . __t Маркер указывает, что этот раздел определяет компонент:

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

Примитивные типы

В этом разделе показаны примеры примитивных типов свойств, которые устройство отправляет в службу.

В следующем фрагменте из модели устройства показано определение boolean типа свойства:

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

Клиент устройства должен отправить полезные данные JSON, которые выглядят следующим образом, как сообщаемое свойство в двойнике устройства:

{ "BooleanProperty": false }

В следующем фрагменте из модели устройства показано определение long типа свойства:

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

{ "LongProperty": 439 }

В следующем фрагменте из модели устройства показано определение date типа свойства:

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

Клиент устройства должен отправлять полезные данные JSON, которые выглядят как приведенный ниже пример как сообщаемое свойство в двойнике устройства. Date типы должны соответствовать стандарту ISO 8061:

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

В следующем фрагменте из модели устройства показано определение duration типа свойства:

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

Клиент устройства должен отправлять полезные данные JSON, которые выглядят следующим образом, как сообщаемое свойство в двойнике устройства. Длительность должна соответствовать стандарту ISO 8601 Duration:

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

В следующем фрагменте из модели устройства показано определение float типа свойства:

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

{ "FloatProperty": 1.9 }

В следующем фрагменте из модели устройства показано определение string типа свойства:

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

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

Сложные типы

В этом разделе показаны примеры сложных типов свойств, которые устройство отправляет в службу.

В следующем фрагменте из модели устройства показано определение 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"
      }
    ]
  }
}

Клиент устройства должен отправлять полезные данные JSON, которые выглядят как приведенный ниже пример как сообщаемое свойство в двойнике устройства. Возможные значения: , и они отображаются 0в IoT Central как 1, Item1и Item2: Item3

{ "EnumProperty": 1 }

В следующем фрагменте кода модели устройства показано определение Object типа свойства. Этот объект содержит два поля с типами string и 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"
      }
    ]
  }
}

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

В следующем фрагменте из модели устройства показано определение vector типа свойства:

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

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

В следующем фрагменте из модели устройства показано определение geopoint типа свойства:

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

Замечание

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

Типы свойств, доступных для записи

В этом разделе показаны примеры типов свойств, доступных для записи, получаемых устройством из службы.

Если записываемое свойство определено в компоненте, нужное сообщение свойства включает имя компонента. В следующем примере показано сообщение, запрашивающее устройство для обновления targetTemperature компонента thermostat2 . __t Маркер указывает, что этот раздел определяет компонент:

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

Устройство или модуль должны подтвердить, что они получили свойство, отправив сообщаемое свойство. Передаваемое свойство должно включать в себя:

value — фактическое значение свойства (обычно полученное значение, но устройство может решить сообщить о другом значении).
ac — код подтверждения, использующий код состояния HTTP.
av — версия подтверждения, относящаяся к $version требуемого свойства. Это значение можно найти в JSON-структуре заданного свойства.
ad — необязательное описание подтверждения.

Дополнительные сведения об этих полях см. в статье об подтверждениях > соглашений IoT Plug and Play

В следующем фрагменте из модели устройства показано определение типа свойства, допускающего string запись:

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

Устройство получает следующие полезные данные от службы:

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

Устройство должно отправлять следующие полезные данные JSON в службу после обработки обновления. Это сообщение содержит номер версии исходного обновления, полученного от службы.

Подсказка

Если служба является IoT Central, она помечает свойство как синхронизированное в пользовательском интерфейсе при получении этого сообщения:

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

В следующем фрагменте из модели устройства показано определение типа свойства, допускающего 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"
      }
    ]
  }
}

Устройство получает следующие полезные данные от службы:

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

Подсказка

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

Команды

Дополнительные сведения о правилах именования команд DTDL см. в разделе "Команда DTDL>". Невозможно запустить имя команды с помощью символа _ .

Если команда определена в компоненте, имя команды, которую получает устройство, включает имя компонента. Например, если команда вызывается getMaxMinReport и компонент вызывается thermostat2, устройство получает запрос на выполнение команды thermostat2*getMaxMinReport.

В следующем фрагменте из модели устройства показано определение команды, которая не имеет параметров, и это не ожидает, что устройство возвращает ничего:

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

Устройство получает пустую полезные данные в запросе и должно возвращать пустую полезные данные в ответе с 200 кодом HTTP-ответа, чтобы указать успешность.

Следующий фрагмент из модели устройства показывает определение команды, которая имеет целочисленный параметр, и ожидает, что устройство возвращает целочисленное значение:

{
  "@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"
}

Устройство получает целочисленное значение в качестве полезных данных запроса. Устройство должно возвращать целочисленное значение в качестве полезных данных ответа с 200 кодом ОТВЕТА HTTP, чтобы указать успешность.

В следующем фрагменте кода из модели устройства показано определение команды, которая имеет параметр объекта, и ожидает, что устройство возвращает объект. В этом примере оба объекта имеют целые и строковые поля:

{
  "@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"
}

В следующем фрагменте кода показан пример полезных данных запроса, отправленных на устройство:

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

В следующем фрагменте кода показан пример полезных данных ответа, отправленных с устройства. 200 Используйте код ответа HTTP, чтобы указать успешное выполнение:

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

Подсказка

IoT Central имеет собственные соглашения для реализации команд длительного выполнения и оффлайн-команд.

Дальнейшие действия

Теперь, когда вы узнали о полезных данных устройства, рекомендуемый следующий шаг — прочитать руководство разработчика устройств.

Last updated on 2025-03-18

Полезные данные телеметрии, свойств и команд

Просмотр необработанных данных

Телеметрия

Телеметрия в компонентах

Телеметрия в унаследованных интерфейсах

Примитивные типы

Сложные типы

Типы событий и состояний

Свойства

Свойства компонентов

Примитивные типы

Сложные типы

Типы свойств, доступных для записи

Команды

Дальнейшие действия

Дополнительные ресурсы