Telemetrie-, Eigenschaften- und Befehlsnutzlasten

Artikel
02/06/2024

Ein Gerätemodell definiert Folgendes:

Telemetrie, die ein Gerät an einen Dienst sendet.
Eigenschaften, die ein Gerät mit einem Dienst synchronisiert.
Befehle, die der Dienst auf einem Gerät aufruft.

Tipp

Azure IoT Central ist ein Dienst, der den Plug & Play Konventionen folgt. In IoT Central ist das Gerätemodell Teil einer Gerätevorlage. IoT Central unterstützt derzeit DTDL v2 mit einer IoT Central-Erweiterung. Eine IoT Central-Anwendung erwartet, dass UTF-8-codierte JSON-Daten empfangen werden.

In diesem Artikel werden die JSON-Nutzlasten beschrieben, die Geräte für Telemetrie, Eigenschaften und Befehle senden und empfangen, die in einem DTDL-Gerätemodell definiert sind.

Der Artikel beschreibt nicht jeden möglichen Typ von Telemetrie, Eigenschaft und Befehlsnutzlast, aber die Beispiele veranschaulichen Schlüsseltypen.

Jedes Beispiel zeigt einen Codeausschnitt aus dem Gerätemodell, der den Typ und die Beispiel-JSON-Nutzlast definiert, um zu veranschaulichen, wie das Gerät mit einem Plug & Play fähigen Dienst wie IoT Central interagieren soll.

Die Beispiel-JSON-Codeausschnitte in diesem Artikel verwenden Digital Twin Definition Language (DTDL) V2. Es gibt auch einige DTDL-Erweiterungen, die IoT Central verwendet.

Beispielgerätecode, der einige dieser verwendeten Nutzlasten zeigt, finden Sie im Verbinden einer Beispiel-IoT Plug & Play Geräteanwendung, die unter Linux oder Windows mit IoT Hub ausgeführt wird, oder das Lernprogramm zum Erstellen und Verbinden einer Clientanwendung mit Ihrem Lernprogramm zur Azure IoT Central-Anwendung.

Anzeigen von Rohdaten

Wenn Sie IoT Central verwenden, können Sie die Rohdaten anzeigen, die ein Gerät an eine Anwendung sendet. Diese Ansicht ist hilfreich bei der Behebung von Problemen mit der von einem Gerät gesendeten Nutzlast. So zeigen Sie die von einem Gerät gesendeten Rohdaten an:

Navigieren Sie auf der Seite Geräte zum Gerät.
Wählen Sie die Registerkarte Rohdaten aus:

In dieser Ansicht können Sie die anzuzeigenden Spalten auswählen und einen Zeitbereich zum Anzeigen festlegen. In der Spalte für Nicht modellierte Daten werden die Daten des Geräts angezeigt, die keiner der Definitionen für Eigenschaften oder Telemetriedaten in der Gerätevorlage entsprechen.

Weitere Tipps zur Problembehandlung finden Sie unter "Problembehandlung", warum Daten von Ihren Geräten nicht in Azure IoT Central angezeigt werden.

Telemetrie

Weitere Informationen zu den Benennungsregeln für DTDL-Telemetrie finden Sie unter DTDL> Telemetrie. Sie können einen Telemetrienamen nicht mit dem Zeichen _ beginnen.

Erstellen Sie keine Telemetrietypen mit den folgenden Namen. IoT Central verwendet diese reservierten Namen intern. Wenn Sie versuchen, diese Namen zu verwenden, ignoriert IoT Central Ihre Daten:

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

Telemetrie in Komponenten

Wenn die Telemetrie in einer Komponente definiert ist, fügen Sie eine benutzerdefinierte Nachrichteneigenschaft namens $.sub mit dem Namen der Komponente hinzu, wie im Gerätemodell definiert. Weitere Informationen finden Sie im Lernprogramm: Verbinden einer IoT Plug & Play mehreren Komponentengeräteanwendungen. In diesem Lernprogramm wird gezeigt, wie Sie verschiedene Programmiersprachen verwenden, um Telemetrie aus einer Komponente zu senden.

Wichtig

Verwenden Sie IoT Edge Version 1.2.4 oder höher, um Telemetrie von Komponenten, die in IoT Edge Modulen gehostet werden, ordnungsgemäß anzuzeigen. Wenn Sie eine frühere Version verwenden, werden Telemetrie von Ihren Komponenten in IoT Edge Modulen als _unmodeleddata angezeigt.

Telemetrie in geerbten Schnittstellen

Wenn die Telemetrie in einer geerbten Schnittstelle definiert ist, sendet Ihr Gerät die Telemetrie, als ob sie in der Stammschnittstelle definiert ist. Aufgrund des folgenden Gerätemodells:

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

Das Gerät sendet messspannungs telemetrie mit der folgenden Nutzlast. Das Gerät enthält nicht den Schnittstellennamen in der Nutzlast:

{
    "MeterVoltage": 5.07
}

Einfache Typen

Dieser Abschnitt enthält Beispiele für primitive Telemetrietypen, die ein Gerät streamen kann.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ boolean:

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

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht:

{ "BooleanTelemetry": true }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ string:

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

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ integer:

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

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht:

{ "IntegerTelemetry": 23 }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ double:

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

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht:

{ "DoubleTelemetry": 56.78 }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ dateTime:

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

Ein Geräteclient sollte die Telemetriedaten wie im folgenden Beispiel dargestellt als JSON-Code senden. Dabei müssen DateTime-Typen im ISO 8061-Format angegeben werden:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ duration:

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

Ein Geräteclient sollte die Telemetriedaten wie im folgenden Beispiel dargestellt als JSON-Code senden. Dabei müssen Zeitspannen im ISO 8061-Format angegeben werden:

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

Komplexe Typen

Dieser Abschnitt enthält Beispiele für komplexe Telemetrietypen, die ein Gerät streamen kann.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ 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"
      }
    ]
  }
}

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht. Mögliche Werte sind 0, 1 und 2, die in IoT Central als Item1, Item2 und Item3 angezeigt werden:

{ "EnumTelemetry": 1 }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ Object. Dieses Objekt enthält drei Felder mit den Typen dateTime, integer und 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"
            }
          ]
        }
      }
    ]
  }
}

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht. DateTime-Typen müssen ISO 8061-kompatibel sein. Mögliche Werte für Property3 sind 0 und 1, die in IoT Central als Item1, Item2 und Item3 angezeigt werden:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ vector:

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

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition einer Telemetrie vom Typ geopoint:

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

Hinweis

Der Geopoint-Schematyp ist Teil der IoT Central-Erweiterung für DTDL. IoT Central unterstützt zurzeit den Schematyp geopoint und den semantischen Typ location aus Gründen der Abwärtskompatibilität.

Ein Geräteclient sollte die Telemetriedaten als JSON-Code senden, der wie im folgenden Beispiel aussieht. IoT Central zeigt den Wert als Stecknadel auf einer Karte an:

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

Ereignis- und Zustandstypen

In diesem Abschnitt werden Beispiele für Telemetrieereignisse und -zustände gezeigt, die ein Gerät an eine IoT Central-Anwendung sendet.

Hinweis

Die Ereignis - und Zustandsschematypen sind Teil der IoT Central-Erweiterung für DTDL.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines integer-Ereignistyps:

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

Ein Geräteclient sollte die Ereignisdaten als JSON-Code senden, der wie im folgenden Beispiel aussieht:

{ "IntegerEvent": 74 }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines integer-Zustandstyps:

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

Ein Geräteclient sollte den Zustand als JSON-Code senden, der wie im folgenden Beispiel aussieht. Mögliche ganzzahlige Zustandswerte sind 1, 2oder 3:

{ "IntegerState": 2 }

Eigenschaften

Weitere Informationen zu den Benennungsregeln für DTDL-Eigenschaften finden Sie unter DTDL >Eigenschaft. Sie können einen Eigenschaftennamen nicht mit dem Zeichen _ beginnen.

Eigenschaften in Komponenten

Wenn die Eigenschaft in einer-Komponente definiert ist, umschließen Sie die Eigenschaft im Komponentennamen. Im folgenden Beispiel wird maxTempSinceLastReboot in der Komponente thermostat2 festgelegt. Die Markierung __t gibt an, dass dieser Abschnitt eine Komponente definiert:

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

Weitere Informationen finden Sie unter Tutorial: Erstellen einer Clientanwendung und Verbinden der Anwendung mit Ihrer Azure IoT Central-Anwendung.

Einfache Typen

Dieser Abschnitt enthält Beispiele für primitive Eigenschaftstypen, die ein Gerät an einen Dienst sendet.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines boolean-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden:

{ "BooleanProperty": false }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines long-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden:

{ "LongProperty": 439 }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines date-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden. Date-Typen müssen ISO 8061-kompatibel sein:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines duration-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden. Dabei müssen Zeitspannen ISO 8601-kompatibel sein:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines float-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden:

{ "FloatProperty": 1.9 }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines string-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden:

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

Komplexe Typen

Dieser Abschnitt enthält Beispiele für komplexe Eigenschaftstypen, die ein Gerät an einen Dienst sendet.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Enum-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden. Mögliche Werte sind 0, 1 und ‚2‘, die in IoT Central als Item1, Item2 und Item3 angezeigt werden:

{ "EnumProperty": 1 }

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Object-Eigenschaftstyps. Dieses Objekt enthält zwei Felder mit den Typen string und 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"
      }
    ]
  }
}

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines vector-Eigenschaftstyps:

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

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines geopoint-Eigenschaftstyps:

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

Hinweis

Ein Geräteclient sollte eine JSON-Nutzlast, die wie im folgenden Beispiel aussieht, als gemeldete Eigenschaft im Gerätezwilling senden:

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

Beschreibbare Eigenschaftstypen

In diesem Abschnitt werden Beispiele für schreibbare Eigenschaftstypen gezeigt, die ein Gerät von einem Dienst empfängt.

Wenn die beschreibbare Eigenschaft in einer Komponente definiert ist, enthält die gewünschte Eigenschaftsnachricht den Komponentennamen. Das folgende Beispiel zeigt die Nachricht, in der das Gerät zum Aktualisieren von targetTemperature in der Komponente thermostat2 aufgefordert wird. Die Markierung __t gibt an, dass dieser Abschnitt eine Komponente definiert:

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

Weitere Informationen finden Sie unter Verbinden einer IoT Plug & Play mehreren Komponentengeräteanwendungen.

Das Gerät oder Modul muss bestätigen, dass es die Eigenschaft erhalten hat, indem es eine gemeldete Eigenschaft sendet. Die gemeldete Eigenschaft muss Folgendes enthalten:

value: den tatsächlichen Wert der Eigenschaft (in der Regel der empfangene Wert, aber das Gerät kann bei Bedarf einen anderen Wert melden).
ac: einen Bestätigungscode, der einen HTTP-Statuscode enthält
av: eine Bestätigungsversion, die auf die $version der gewünschten Eigenschaft verweist. Sie finden diesen Wert in den JSON-Nutzdaten der gewünschten Eigenschaft.
ad: eine optionale Beschreibung der Bestätigung

Weitere Informationen zu diesen Feldern finden Sie unter IoT Plug & Play Konventionen > zur Bestätigung von Antworten

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines beschreibbaren string-Eigenschaftstyps:

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

Das Gerät empfängt die folgende Nutzlast vom Dienst:

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

Das Gerät sollte die folgende JSON-Nutzlast nach dem Verarbeiten des Updates an den Dienst senden. Diese Nachricht enthält die Versionsnummer des ursprünglichen Updates, das vom Dienst empfangen wurde.

Tipp

Wenn der Dienst IoT Central ist, kennzeichnet er die Eigenschaft als synchronisiert in der Benutzeroberfläche, wenn er diese Nachricht empfängt:

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

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines beschreibbaren Enum-Eigenschaftstyps:

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

Das Gerät empfängt die folgende Nutzlast vom Dienst:

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

Tipp

Wenn der Dienst IoT Central ist, kennzeichnet er die Eigenschaft als synchronisiert in der Benutzeroberfläche, wenn er diese Nachricht empfängt:

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

Befehle

Weitere Informationen zu den Benennungsregeln für DTDL-Befehle finden Sie unter DTDL > Befehl. Sie können einen Befehlsnamen nicht mit dem Zeichen _ beginnen.

Wenn der Befehl in einer Komponente definiert ist, enthält der Name des vom Gerät empfangenen Befehls den Komponentennamen. Beispiel: Wenn der Befehl getMaxMinReport und die Komponente thermostat2 lautet, empfängt das Gerät eine Anforderung zum Ausführen eines Befehls namens thermostat2*getMaxMinReport.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Befehls, der weder Parameter aufweist noch eine Rückgabe vom Gerät erwartet:

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

Das Gerät empfängt in der Anforderung eine leere Nutzlast und sollte in der Antwort eine leere Nutzlast mit dem HTTP-Antwortcode 200 zur Angabe von Erfolg zurückgeben.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Befehls, der einen Parameter vom Typ „integer“ aufweist und die Rückgabe eines ganzzahligen Werts vom Gerät erwartet:

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

Das Gerät empfängt einen ganzzahligen Wert als Anforderungsnutzlast. Das Gerät sollte einen ganzzahligen Wert als Antwortnutzlast mit dem HTTP-Antwortcode 200 zur Angabe von Erfolg zurückgeben.

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Befehls, der einen Parameter vom Typ „Object“ aufweist und die Rückgabe eines Objekts vom Gerät erwartet. In diesem Beispiel enthalten beide Objekte ganzzahlige Felder und Zeichenfolgenfelder:

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

Der folgende Codeausschnitt zeigt ein Beispiel für eine Anforderungsnutzlast, die an das Gerät gesendet wird:

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

Der folgende Codeausschnitt zeigt ein Beispiel für eine Antwortnutzlast, die vom Gerät gesendet wurde. Verwenden Sie den HTTP-Antwortcode 200 zur Angabe von Erfolg:

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

Tipp

IoT Central verfügt über eigene Konventionen für die Implementierung von Langausführungsbefehlen und Offlinebefehlen.

Nächste Schritte

Nachdem Sie nun mehr über Gerätenutzlasten gelernt haben, finden Sie in der Anleitung für Geräteentwickler die nächsten Schritte.

Telemetrie-, Eigenschaften- und Befehlsnutzlasten

Anzeigen von Rohdaten

Telemetrie

Telemetrie in Komponenten

Telemetrie in geerbten Schnittstellen

Einfache Typen

Komplexe Typen

Ereignis- und Zustandstypen

Eigenschaften

Eigenschaften in Komponenten

Einfache Typen

Komplexe Typen

Beschreibbare Eigenschaftstypen

Befehle

Nächste Schritte

Zusätzliche Ressourcen