Payloads van telemetrie, eigenschappen en opdrachten

Artikel
02/06/2024

Een apparaatmodel definieert het volgende:

Telemetrie die een apparaat naar een service verzendt.
Eigenschappen van een apparaat worden gesynchroniseerd met een service.
Opdrachten die de service op een apparaat aanroept.

Tip

Azure IoT Central is een service die de Plug en Play conventies volgt. In IoT Central maakt het apparaatmodel deel uit van een apparaatsjabloon. IoT Central ondersteunt momenteel DTDL v2 met een IoT Central-extensie. Een IoT Central-toepassing verwacht UTF-8 gecodeerde JSON-gegevens te ontvangen.

In dit artikel worden de JSON-nettoladingen beschreven die apparaten verzenden en ontvangen voor telemetrie, eigenschappen en opdrachten die zijn gedefinieerd in een DTDL-apparaatmodel.

In het artikel wordt niet elk mogelijk type telemetrie, eigenschap en nettolading van opdrachten beschreven, maar in de voorbeelden worden belangrijke typen geïllustreerd.

Elk voorbeeld toont een fragment van het apparaatmodel dat het type en de voorbeeld-JSON-nettoladingen definieert om te laten zien hoe het apparaat moet communiceren met een Plug en Play bewuste service, zoals IoT Central.

In de voorbeeld-JSON-fragmenten in dit artikel wordt DTDL V2 (Digital Twin Definition Language) gebruikt. Er zijn ook enkele DTDL-extensies die door IoT Central worden gebruikt.

Zie de Verbinding maken een voorbeeld van een IoT-Plug en Play-apparaattoepassing die wordt uitgevoerd in Linux of Windows met IoT Hub of de zelfstudie Een clienttoepassing maken en verbinden met uw Azure IoT Central-toepassing voor voorbeeldcode die enkele van deze nettoladingen bevat.

Onbewerkte gegevens weergeven

Als u IoT Central gebruikt, kunt u de onbewerkte gegevens bekijken die een apparaat naar een toepassing verzendt. Deze weergave is handig voor het oplossen van problemen met de nettolading die vanaf een apparaat wordt verzonden. Ga als volgt te werk om de onbewerkte gegevens weer te geven die een apparaat verzendt:

Navigeer naar het apparaat vanaf de pagina Apparaten .
Selecteer het tabblad Onbewerkte gegevens :

In deze weergave kunt u de kolommen selecteren die u wilt weergeven en een tijdsbereik instellen. In de kolom Niet-gemodelleerde gegevens ziet u gegevens van het apparaat die niet overeenkomen met een van de eigenschaps- of telemetriedefinities in de apparaatsjabloon.

Zie Problemen oplossen waarom gegevens van uw apparaten niet worden weergegeven in Azure IoT Central voor meer tips voor probleemoplossing.

Telemetrie

Zie DTDL-telemetrie voor meer informatie over de naamgevingsregels voor DTDL-telemetrie>. U kunt geen telemetrienaam starten met behulp van het _ teken.

Maak geen telemetrietypen met de volgende namen. IoT Central gebruikt deze gereserveerde namen intern. Als u deze namen probeert te gebruiken, negeert IoT Central uw gegevens:

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

Telemetrie in onderdelen

Als de telemetrie is gedefinieerd in een onderdeel, voegt u een aangepaste berichteigenschap $.sub toe met de naam van het onderdeel zoals gedefinieerd in het apparaatmodel. Zie Zelfstudie: Verbinding maken een IoT-Plug en Play meerdere apparaattoepassingen voor onderdelen voor meer informatie. Deze zelfstudie laat zien hoe u verschillende programmeertalen gebruikt om telemetrie van een onderdeel te verzenden.

Belangrijk

Als u telemetrie wilt weergeven van onderdelen die worden gehost in IoT Edge-modules, gebruikt u IoT Edge versie 1.2.4 of hoger. Als u een eerdere versie gebruikt, wordt telemetrie van uw onderdelen in IoT Edge-modules weergegeven als _unmodeleddata.

Telemetrie in overgenomen interfaces

Als de telemetrie is gedefinieerd in een overgenomen interface, verzendt uw apparaat de telemetrie alsof deze is gedefinieerd in de hoofdinterface. Gegeven het volgende apparaatmodel:

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

Het apparaat verzendt telemetrie van de meterspanning met behulp van de volgende nettolading. Het apparaat bevat niet de interfacenaam in de nettolading:

{
    "MeterVoltage": 5.07
}

Primitieve typen

In deze sectie ziet u voorbeelden van primitieve telemetrietypen die een apparaat kan streamen.

Het volgende codefragment van een apparaatmodel toont de definitie van een boolean telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld:

{ "BooleanTelemetry": true }

Het volgende codefragment van een apparaatmodel toont de definitie van een string telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld:

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

In het volgende codefragment van een apparaatmodel ziet u de definitie van een integer telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld:

{ "IntegerTelemetry": 23 }

Het volgende codefragment van een apparaatmodel toont de definitie van een double telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld:

{ "DoubleTelemetry": 56.78 }

Het volgende codefragment van een apparaatmodel toont de definitie van een dateTime telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld: DateTime typen moeten de ISO 8061-indeling hebben:

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

Het volgende codefragment van een apparaatmodel toont de definitie van een duration telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld: de duur moet de ISO 8601-indeling hebben:

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

Complexe typen

In deze sectie ziet u voorbeelden van complexe telemetrietypen die een apparaat kan streamen.

In het volgende codefragment van een apparaatmodel ziet u de definitie van een Enum telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld. Mogelijke waarden zijn 0, 1en 2 die worden weergegeven in IoT Central als Item1, Item2en Item3:

{ "EnumTelemetry": 1 }

In het volgende codefragment van een apparaatmodel wordt de definitie van een Object telemetrietype weergegeven. Dit object heeft drie velden met typen dateTime, integeren 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"
            }
          ]
        }
      }
    ]
  }
}

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld. DateTime typen moeten voldoen aan iso 8061. Mogelijke waarden zijn Property30, 1en die worden weergegeven in IoT Central als Item1, Item2en Item3:

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

Het volgende codefragment van een apparaatmodel toont de definitie van een vector telemetrietype:

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

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld:

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

Het volgende codefragment van een apparaatmodel toont de definitie van een geopoint telemetrietype:

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

Notitie

Het geopoint-schematype maakt deel uit van de IoT Central-extensie naar DTDL. IoT Central ondersteunt momenteel het geopoint-schematype en het locatiesemantische type voor achterwaartse compatibiliteit.

Een apparaatclient moet de telemetrie verzenden als JSON die eruitziet als het volgende voorbeeld. IoT Central geeft de waarde weer als een speld op een kaart:

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

Gebeurtenis- en statustypen

In deze sectie ziet u voorbeelden van telemetrie-gebeurtenissen en wordt aangegeven dat een apparaat naar een IoT Central-toepassing wordt verzonden.

Notitie

De gebeurtenis - en statusschematypen maken deel uit van de IoT Central-extensie naar DTDL.

In het volgende fragment van een apparaatmodel ziet u de definitie van een integer gebeurtenistype:

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

Een apparaatclient moet de gebeurtenisgegevens verzenden als JSON die eruitziet als het volgende voorbeeld:

{ "IntegerEvent": 74 }

In het volgende fragment van een apparaatmodel wordt de definitie van een integer statustype weergegeven:

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

Een apparaatclient moet de status verzenden als JSON die eruitziet als het volgende voorbeeld. Mogelijke statuswaarden voor gehele getallen zijn 1, 2of 3:

{ "IntegerState": 2 }

Eigenschappen

Zie de DTDL-eigenschap voor meer informatie over de naamgevingsregels voor DTDL-eigenschappen>. U kunt een eigenschapsnaam niet starten met behulp van het _ teken.

Eigenschappen in onderdelen

Als de eigenschap is gedefinieerd in een onderdeel, verpakt u de eigenschap in de naam van het onderdeel. In het volgende voorbeeld wordt het maxTempSinceLastRebootthermostat2 onderdeel ingesteld. De markering __t geeft aan dat deze sectie een onderdeel definieert:

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

Zie Zelfstudie: Een clienttoepassing maken en verbinden met uw Azure IoT Central-toepassing voor meer informatie.

Primitieve typen

In deze sectie ziet u voorbeelden van primitieve eigenschapstypen die een apparaat naar een service verzendt.

In het volgende fragment van een apparaatmodel wordt de definitie van een boolean eigenschapstype weergegeven:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel:

{ "BooleanProperty": false }

In het volgende fragment van een apparaatmodel wordt de definitie van een long eigenschapstype weergegeven:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel:

{ "LongProperty": 439 }

In het volgende fragment van een apparaatmodel wordt de definitie van een date eigenschapstype weergegeven:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel. Date typen moeten voldoen aan iso 8061:

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

In het volgende fragment van een apparaatmodel wordt de definitie van een duration eigenschapstype weergegeven:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel: duur moet voldoen aan de ISO 8601-duur:

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

In het volgende fragment van een apparaatmodel wordt de definitie van een float eigenschapstype weergegeven:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel:

{ "FloatProperty": 1.9 }

In het volgende fragment van een apparaatmodel wordt de definitie van een string eigenschapstype weergegeven:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel:

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

Complexe typen

In deze sectie ziet u voorbeelden van complexe eigenschapstypen die een apparaat naar een service verzendt.

In het volgende fragment van een apparaatmodel ziet u de definitie van een Enum eigenschapstype:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel. Mogelijke waarden zijn 0, 1en die worden weergegeven in IoT Central als Item1, Item2en Item3:

{ "EnumProperty": 1 }

In het volgende fragment van een apparaatmodel wordt de definitie van een Object eigenschapstype weergegeven. Dit object heeft twee velden met typen string en 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"
      }
    ]
  }
}

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel:

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

In het volgende fragment van een apparaatmodel ziet u de definitie van een vector eigenschapstype:

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

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel:

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

In het volgende fragment van een apparaatmodel wordt de definitie van een geopoint eigenschapstype weergegeven:

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

Notitie

Een apparaatclient moet een JSON-nettolading verzenden die eruitziet als het volgende voorbeeld als een gerapporteerde eigenschap in de apparaatdubbel:

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

Schrijfbare eigenschapstypen

In deze sectie ziet u voorbeelden van beschrijfbare eigenschapstypen die een apparaat van een service ontvangt.

Als de beschrijfbare eigenschap is gedefinieerd in een onderdeel, bevat het bericht van de gewenste eigenschap de onderdeelnaam. In het volgende voorbeeld ziet u het bericht waarin het apparaat wordt aangevraagd om het targetTemperature in het thermostat2 onderdeel bij te werken. De markering __t geeft aan dat deze sectie een onderdeel definieert:

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

Zie Verbinding maken een IoT-Plug en Play meerdere apparaattoepassingen voor onderdelen voor meer informatie.

Het apparaat of de module moet bevestigen dat deze de eigenschap heeft ontvangen door een gerapporteerde eigenschap te verzenden. De gerapporteerde eigenschap moet het volgende omvatten:

value - de werkelijke waarde van de eigenschap (meestal de ontvangen waarde, maar het apparaat kan besluiten om een andere waarde te rapporteren).
ac - een bevestigingscode die gebruikmaakt van een HTTP-statuscode.
av - een bevestigingsversie die verwijst naar de $version gewenste eigenschap. U vindt deze waarde in de JSON-nettolading van de gewenste eigenschap.
ad - een optionele bevestigingsbeschrijving.

Zie Voor meer informatie over deze velden ioT Plug en Play conventies bevestigingsreacties >

In het volgende fragment van een apparaatmodel ziet u de definitie van een beschrijfbaar string eigenschapstype:

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

Het apparaat ontvangt de volgende nettolading van de service:

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

Het apparaat moet de volgende JSON-nettolading naar de service verzenden nadat de update is verwerkt. Dit bericht bevat het versienummer van de oorspronkelijke update die van de service is ontvangen.

Tip

Als de service IoT Central is, wordt de eigenschap gemarkeerd als gesynchroniseerd in de gebruikersinterface wanneer deze het volgende bericht ontvangt:

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

In het volgende fragment van een apparaatmodel ziet u de definitie van een beschrijfbaar Enum eigenschapstype:

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

Het apparaat ontvangt de volgende nettolading van de service:

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

Het apparaat moet de volgende JSON-nettolading naar de service verzenden nadat de update is verwerkt. Dit bericht bevat het versienummer van de oorspronkelijke update die van de service is ontvangen.

Tip

Als de service IoT Central is, wordt de eigenschap gemarkeerd als gesynchroniseerd in de gebruikersinterface wanneer deze het volgende bericht ontvangt:

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

Opdrachten

Zie DTDL > Command voor meer informatie over de DTDL-opdrachtnaamgevingsregels. U kunt een opdrachtnaam niet starten met behulp van het _ teken.

Als de opdracht is gedefinieerd in een onderdeel, bevat de naam van de opdracht die het apparaat ontvangt de onderdeelnaam. Als de opdracht bijvoorbeeld wordt aangeroepen getMaxMinReport en het onderdeel wordt aangeroepen thermostat2, ontvangt het apparaat een aanvraag om een opdracht uit te voeren met de naam thermostat2*getMaxMinReport.

In het volgende codefragment van een apparaatmodel ziet u de definitie van een opdracht die geen parameters heeft en die niet verwacht dat het apparaat iets retourneert:

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

Het apparaat ontvangt een lege nettolading in de aanvraag en moet een lege nettolading in het antwoord retourneren met een 200 HTTP-antwoordcode om aan te geven dat het is gelukt.

Het volgende codefragment van een apparaatmodel toont de definitie van een opdracht met een parameter voor een geheel getal en die verwacht dat het apparaat een geheel getal retourneert:

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

Het apparaat ontvangt een geheel getal als de nettolading van de aanvraag. Het apparaat moet een geheel getal retourneren als de nettolading van het antwoord met een 200 HTTP-antwoordcode om aan te geven dat het is gelukt.

Het volgende codefragment van een apparaatmodel toont de definitie van een opdracht met een objectparameter en die verwacht dat het apparaat een object retourneert. In dit voorbeeld hebben beide objecten gehele getallen en tekenreeksvelden:

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

In het volgende codefragment ziet u een voorbeeld van de nettolading van de aanvraag die naar het apparaat is verzonden:

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

In het volgende codefragment ziet u een voorbeeld van de nettolading van het antwoord dat vanaf het apparaat is verzonden. Gebruik een 200 HTTP-antwoordcode om aan te geven dat het is gelukt:

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

Tip

IoT Central heeft zijn eigen conventies voor het implementeren van langlopende opdrachten en offlineopdrachten.

Volgende stappen

Nu u meer hebt geleerd over nettoladingen van apparaten, kunt u de handleiding voor apparaatontwikkelaars lezen.

Payloads van telemetrie, eigenschappen en opdrachten

Onbewerkte gegevens weergeven

Telemetrie

Telemetrie in onderdelen

Telemetrie in overgenomen interfaces

Primitieve typen

Complexe typen

Gebeurtenis- en statustypen

Eigenschappen

Eigenschappen in onderdelen

Primitieve typen

Complexe typen

Schrijfbare eigenschapstypen

Opdrachten

Volgende stappen

Aanvullende resources