Telemetrie-, Eigenschaften- und Befehlsnutzlasten

Artikel
02/06/2024

Ein Gerätemodell definiert Folgendes:

Die Telemetriedaten, die ein Gerät an einen Dienst sendet.
Die Eigenschaften, die ein Gerät mit einem Dienst synchronisiert.
Die 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 ein Gerätemodell Teil der 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 die in einem DTDL-Gerätemodell definierten Telemetriedaten, Eigenschaften und Befehle senden und empfangen.

Zwar wird nicht jeder mögliche Typ von Telemetrie-, Eigenschaften- und Befehlsnutzlast beschrieben, aber die Beispiele veranschaulichen wichtige Typen.

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

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

Ein Beispiel für Gerätecode, der einige dieser gerade verwendeten Nutzlasten zeigt, finden Sie in den Tutorials Verbinden einer unter Linux oder Windows ausgeführten IoT Plug & Play-Beispielgeräteanwendung mit IoT Hub und Erstellen einer Clientanwendung und Verbinden der Anwendung mit Ihrer 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 Behandeln von Problemen, 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 Tutorial: Herstellen einer Verbindung zwischen einer IoT Plug & Play-Geräteanwendung mit mehreren Komponenten. In diesem Tutorial 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. Betrachten Sie das folgende Gerätemodell:

[
    {
        "@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 Spannungstelemetrie der Verbrauchseinheit mit der folgenden Nutzlast. Das Gerät enthält nicht den Schnittstellennamen in der Nutzlast:

{
    "MeterVoltage": 5.07
}

Einfache Typen

In diesem Abschnitt werden Beispiele für einfache Telemetrietypen gezeigt, 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

In diesem Abschnitt werden Beispiele für komplexe Telemetrietypen gezeigt, 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 Schematyp geopoint 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 Schematypen Ereignis und Status 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. Der Marker __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

In diesem Abschnitt werden Beispiele für einfache Eigenschaftstypen gezeigt, 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

In diesem Abschnitt werden Beispiele für komplexe Eigenschaftstypen gezeigt, 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 beschreibbare 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. Der Marker __t gibt an, dass dieser Abschnitt eine Komponente definiert:

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

Weitere Informationen finden Sie unter Herstellen einer Verbindung zwischen einer IoT Plug & Play-Geräteanwendung mit mehreren Komponenten.

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 > Bestätigungsantworten.

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 nach Verarbeitung des Updates die folgende JSON-Nutzlast 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 in der Benutzeroberfläche als synchronisiert, wenn diese Meldung empfangen wird:

{
  "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 in der Benutzeroberfläche als synchronisiert, wenn diese Meldung empfangen wird:

{
  "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 Befehlen mit langer Ausführungsdauer und Offlinebefehlen.

Nächste Schritte

Nachdem Sie nun mehr über Gerätenutzlasten erfahren haben, finden Sie im Leitfaden für Geräteentwickler die nächsten Schritte.

Teilen über

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

Feedback

Zusätzliche Ressourcen