Telemetrie-, Eigenschaften- und Befehlsnutzlasten

Eine Gerätevorlage in Azure IoT Central ist eine Blaupause, die Folgendes definiert:

  • Die Telemetriedaten, die ein Gerät an IoT Central sendet.
  • Die Eigenschaften, die ein Gerät mit IoT Central synchronisiert.
  • Die Befehle, die IoT Central auf einem Gerät aufruft.

In diesem Artikel werden die JSON-Nutzlasten beschrieben, die Geräte für die in einer Gerätevorlage definierten Telemetriedaten, Eigenschaften und Befehle senden und empfangen.

Wichtig

IoT Central erwartet, dass UTF-8-codierte JSON-Daten empfangen werden.

Zwar wird nicht jeder mögliche Typ von Telemetrie-, Eigenschaften- und Befehlsnutzlast beschrieben, aber die Beispiele veranschaulichen alle wichtigen 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 der IoT Central-Anwendung interagieren sollte.

Hinweis

IoT Central akzeptiert jeden gültigen JSON-Code, dieser kann aber nur dann für Visualisierungen verwendet werden, wenn er mit einer Definition im Gerätemodell übereinstimmt. Sie können Daten exportieren, die keiner Definition entsprechen, siehe Exportieren von IoT-Daten zu Cloud-Zielen mit Blob Storage.

Die JSON-Datei mit der Definition des Gerätemodells verwendet Digital Twin Definition Language (DTDL) V2.

Ein Beispiel für einen Gerätecode, der einige dieser verwendeten Nutzlasten anzeigt, finden Sie im Tutorial Erstellen einer Clientanwendung und Verbinden der Anwendung mit Ihrer Azure IoT Central-Anwendung.

Anzeigen von Rohdaten

In IoT Central 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:

  1. Navigieren Sie auf der Seite Geräte zum Gerät.

  2. Wählen Sie die Registerkarte Rohdaten aus:

    Screenshot der Ansicht „Rohdaten“

    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.

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

Telemetriezeitstempel

IoT Central verwendet beim Anzeigen von Telemetriedaten auf Dashboards und in Diagrammen standardmäßig die Uhrzeit, zu der die Nachricht in die Warteschlange eingereiht wurde. Diese Uhrzeit wird intern festgelegt, wenn IoT Central die Nachricht vom Gerät empfängt.

Ein Gerät kann die Eigenschaft iothub-creation-time-utc festlegen, wenn es eine Nachricht erstellt, die an IoT Central gesendet werden soll. Wenn diese Eigenschaft vorhanden ist, verwendet IoT Central sie beim Anzeigen von Telemetriedaten auf Dashboards und in Diagrammen.

Sie können sowohl den Zeitpunkt der Einreihung in die Warteschlange als auch die Eigenschaft iothub-creation-time-utc exportieren, wenn Sie Telemetriedaten aus Ihrer IoT Central-Anwendung exportieren.

Weitere Informationen zu Nachrichteneigenschaften finden Sie unter Systemeigenschaften von Gerät-zu-Cloud-IoT Hub-Nachrichten.

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 unter Tutorial: Erstellen einer Clientanwendung und Verbinden der Anwendung mit Ihrer Azure IoT Central-Anwendung.

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.

Einfache Typen

In diesem Abschnitt werden Beispiele für einfache Telemetrietypen gezeigt, die ein Gerät an eine IoT Central-Anwendung streamt.

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 an eine IoT Central-Anwendung streamt.

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 gehört nicht zur Digital Twins Definition Language (DTDL)-Spezifikation. 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
  }
}

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
  }
}

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.

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.

Hinweis

Die Nutzlastformate für Eigenschaften gelten für Anwendungen, die am 14.07.2020 oder danach erstellt wurden.

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 es sich um eine Komponente handelt:

{
  "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 eine IoT Central-Anwendung 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 eine IoT Central-Anwendung sendet.

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

Der Schematyp geopoint gehört nicht zur Digital Twins Definition Language (DTDL)-Spezifikation. IoT Central unterstützt zurzeit den Schematyp geopoint und den semantischen Typ location aus Gründen der Abwärtskompatibilität.

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
  }
}

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
  }
}

Beschreibbare Eigenschaftstypen

In diesem Abschnitt werden Beispiele für beschreibbare Eigenschaftstypen gezeigt, die ein Gerät von einer IoT Central-Anwendung 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 es sich um eine Komponente handelt:

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

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

IoT Central erwartet vom Gerät eine Antwort auf Aktualisierungen von beschreibbaren Eigenschaften. Die Antwortnachricht sollte die Felder ac und av enthalten. Das Feld ad ist optional. Beispiele hierzu finden Sie in den folgenden Codeausschnitten.

ac ist ein numerisches Feld, in dem die Werte in der folgenden Tabelle verwendet werden:

Wert Bezeichnung BESCHREIBUNG
'ac': 200 Abgeschlossen Der Vorgang einer Eigenschaftsänderung wurde erfolgreich abgeschlossen.
'ac': 202 oder 'ac': 201 Ausstehend Der Vorgang einer Eigenschaftsänderung ist ausstehend oder in Bearbeitung.
'ac': 203 Ausstehend Der Eigenschaftsänderungsvorgang wurde vom Gerät initiiert.
'ac': 4xx Fehler Die angeforderte Eigenschaftsänderung war ungültig oder fehlerhaft
'ac': 5xx Fehler Beim Verarbeiten der angeforderten Änderung ist auf dem Gerät ein unerwarteter Fehler aufgetreten.

av ist die an das Gerät gesendete Versionsnummer.

ad ist eine Beschreibung der Optionszeichenfolge.

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 von IoT Central:

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

Das Gerät sollte nach Verarbeitung des Updates die folgende JSON-Nutzlast an IoT Central senden. Diese Nachricht enthält die Versionsnummer des ursprünglichen Updates, das von IoT Central empfangen wurde. Wenn IoT Central diese Nachricht empfängt, kennzeichnet es die Eigenschaft in der Benutzeroberfläche als synchronisiert:

{
  "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 von IoT Central:

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

Das Gerät sollte nach Verarbeitung des Updates die folgende JSON-Nutzlast an IoT Central senden. Diese Nachricht enthält die Versionsnummer des ursprünglichen Updates, das von IoT Central empfangen wurde. Wenn IoT Central diese Nachricht empfängt, kennzeichnet es die Eigenschaft in der Benutzeroberfläche als synchronisiert:

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

Zeitintensive Befehle

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Befehls. Der Befehl hat einen ganzzahligen Parameter und erwartet, dass das Gerät einen ganzzahligen Wert zurückgibt:

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

Das Gerät empfängt einen ganzzahligen Wert als Anforderungsnutzlast. Wenn das Gerät Zeit zum Verarbeiten dieses Befehls benötigt, sollte es eine leere Antwortnutzlast mit dem HTTP-Antwortcode 202 zurückgeben, um anzugeben, dass es die Anforderung zur Verarbeitung akzeptiert hat.

Wenn das Gerät die Verarbeitung der Anforderung abgeschlossen hat, sollte es eine Eigenschaft an IoT Central senden, die wie im folgenden Beispiel aussieht. Der Eigenschaftsname muss mit dem Befehlsnamen identisch sein:

{
  "LongRunningCommandSimple": {
    "value": 87
  }
}

Offlinebefehle

In der IOT Central-Webbenutzeroberfläche können Sie die Option Warteschlange (falls offline) für einen Befehl auswählen. Offlinebefehle sind unidirektionale Benachrichtigungen von Ihrer Lösung an ein Gerät, die übermittelt werden, sobald das Gerät eine Verbindung herstellt. Offlinebefehle können einen Anforderungsparameter enthalten, geben aber keine Antwort zurück.

Offlinebefehle werden als durable markiert, wenn Sie das Modell als DTDL exportieren.

Offline Befehle verwenden Cloud-zu-Gerät-Nachrichten von IoT Hub, um den Befehl und die Nutzlast an das Gerät zu senden.

Die Nutzlast der Nachricht, die das Gerät empfängt, ist der Rohwert des Parameters. Der Name des IoT Central-Befehls wird in der benutzerdefinierten Eigenschaft method-name gespeichert. Die folgende Tabelle zeigt einige Beispielnutzlasten:

IoT Central Anforderungsschema Beispielnutzlast, die vom Gerät empfangen wurde
Kein Anforderungsparameter @
Double 1.23
String sample string
Object {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Der folgende Codeausschnitt aus einem Gerätemodell zeigt die Definition eines Befehls. Der Befehl enthält einen Objektparameter mit einem „DateTime“-Feld und einer Enumeration:

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

Wenn Sie die Option Warteschlange (falls offline) in der Benutzeroberfläche der Gerätevorlage für den Befehl im vorherigen Codeausschnitt aktivieren, enthält die vom Gerät empfangene Meldung die folgenden Eigenschaften:

Eigenschaftenname Beispielwert
custom_properties {'method-name': 'GenerateDiagnostics'}
data {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Nächste Schritte

Nachdem Sie sich mit Gerätevorlagen vertraut gemacht haben, finden Sie im Leitfaden zur IoT Central-Gerätekonnektivität weitere Informationen dazu, wie Sie Geräte bei IoT Central registrieren und wie IoT Central Geräteverbindungen schützt.