Charges utiles de télémétrie, de propriétés et de commandes

Article
02/06/2024

Un modèle d’appareil définit les éléments suivants :

Télémétrie qu’un appareil envoie à un service.
Propriétés qu’un appareil synchronise avec un service.
Commandes que le service appelle sur un appareil.

Conseil

Azure IoT Central est un service qui suit les conventions de Plug-and-Play. Dans IoT Central, le modèle d’appareil fait partie d’un modèle d’appareil. IoT Central prend actuellement en charge DTDL v2 avec une extension IoT Central. Une application IoT Central s’attend à recevoir des données JSON encodées UTF-8.

Cet article décrit les charges utiles JSON que les appareils envoient et reçoivent pour la télémétrie, les propriétés et les commandes définies dans un modèle d’appareil DTDL.

L’article ne décrit pas tous les types possibles de données de télémétrie, de propriété et de charge utile de commande, mais les exemples illustrent les types de clés.

Chaque exemple montre un extrait de code du modèle d’appareil qui définit le type et l’exemple de charge utile JSON pour illustrer la façon dont l’appareil doit interagir avec un service prenant en charge Plug-and-Play comme IoT Central.

Les exemples d’extraits de code JSON de cet article utilisent Digital Twin Definition Language (DTDL) V2. Il existe également certaines extensions DTDL qu’IoT Central utilise.

Pour obtenir un exemple de code d’appareil montrant certaines de ces charges utiles en cours d’utilisation, consultez la Connecter un exemple d’application d’appareil IoT Plug-and-Play s’exécutant sur Linux ou Windows vers IoT Hub ou le didacticiel Créer et connecter une application cliente à votre didacticiel d’application Azure IoT Central.

Voir les données brutes

Si vous utilisez IoT Central, vous pouvez afficher les données brutes qu’un appareil envoie à une application. Cette vue est utile pour résoudre les problèmes liés à la charge utile envoyée à partir d’un appareil. Pour afficher les données brutes envoyées par un appareil :

Accédez à l’appareil à partir de la page Appareils.
Sélectionnez l’onglet Données brutes :

Dans cette vue, vous pouvez sélectionner les colonnes à afficher et définir une plage de temps à afficher. La colonne Données démodélisées affiche les données de l’appareil qui ne correspondent à aucune définition de propriété ou de télémétrie dans le modèle d’appareil.

Pour plus d’informations sur la résolution des problèmes, consultez la raison pour laquelle les données de vos appareils ne s’affichent pas dans Azure IoT Central.

Télémétrie

Pour en savoir plus sur les règles de nommage des données de télémétrie DTDL, consultez DTDL > Télémétrie. Un nom de données de télémétrie ne peut pas commencer par le caractère _.

Ne créez pas de types de télémétrie avec les noms suivants. IoT Central utilise ces noms réservés en interne. Si vous essayez d’utiliser ces noms, IoT Central ignorera vos données :

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

Télémétrie dans les composants

Si la télémétrie est définie dans un composant, ajoutez une propriété de message personnalisée appelée $.sub avec le nom du composant tel que défini dans le modèle d’appareil. Pour plus d’informations, consultez Tutoriel : Connecter un IoT Plug-and-Play plusieurs applications d’appareil composant. Ce tutoriel montre comment utiliser différents langages de programmation pour envoyer des données de télémétrie à partir d’un composant.

Important

Pour afficher correctement la télémétrie des composants hébergés dans des modules IoT Edge, utilisez IoT Edge version 1.2.4 ou ultérieure. Si vous utilisez une version antérieure, la télémétrie de vos composants dans des modules IoT Edge s’affiche comme _unmodeleddata.

Télémétrie dans les interfaces héritées

Si la télémétrie est définie dans une interface héritée, votre appareil envoie les données de télémétrie comme si elles sont définies dans l’interface racine. Étant donné le modèle d’appareil suivant :

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

L’appareil envoie les données de télémétrie de tension du compteur à l’aide de la charge utile suivante. L’appareil n’inclut pas le nom de l’interface dans la charge utile :

{
    "MeterVoltage": 5.07
}

Types primitifs

Cette section présente des exemples de types de télémétrie primitifs qu’un appareil peut diffuser en continu.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie boolean :

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

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant :

{ "BooleanTelemetry": true }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie string :

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

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie integer :

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

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant :

{ "IntegerTelemetry": 23 }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie double :

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

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant :

{ "DoubleTelemetry": 56.78 }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie dateTime :

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

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant – les types DateTime doivent être au format ISO 8061 :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie duration :

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

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant – les durées doivent être au format ISO 8601 :

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

Types complexes

Cette section présente des exemples de types de télémétrie complexes qu’un appareil peut diffuser en continu.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie 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"
      }
    ]
  }
}

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant. Les valeurs possibles sont 0, 1 et 2. Elles s’affichent dans IoT Central en tant que Item1, Item2 et Item3 :

{ "EnumTelemetry": 1 }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie Object. Cet objet a trois champs avec des types dateTime, integer et 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"
            }
          ]
        }
      }
    ]
  }
}

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant. Les types DateTime doivent être conformes à ISO 8061. Les valeurs possibles pour Property3 sont 0 et 1. Elles s’affichent dans IoT Central en tant que Item1, Item2 et Item3 :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie vector :

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

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de télémétrie geopoint :

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

Remarque

Le type de schéma geopoint fait partie de l’extension IoT Central à DTDL. Actuellement, IoT Central prend en charge le type de schéma geopoint et le type sémantique location à des fins de compatibilité descendante.

Un client d’appareil doit envoyer la télémétrie au format JSON comme dans l’exemple suivant. IoT Central affiche la valeur sous la forme d’une épingle sur une carte :

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

Types d’événements et d’états

Cette section présente des exemples d’événements et d’états de télémétrie qu’un appareil transmet à une application IoT Central.

Remarque

Les types de schémas d’événement et d’état font partie de l’extension IoT Central à DTDL.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type d'événement integer :

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

Un client d’appareil doit envoyer les données de l’événement au format JSON comme dans l’exemple suivant :

{ "IntegerEvent": 74 }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type d'état integer :

{
  "@type": [
    "Telemetry",
    "State"
  ],
  "displayName": {
    "en": "IntegerState"
  },
  "name": "IntegerState",
  "schema": {
    "@type": "Enum",
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Level1"
        },
        "enumValue": 1,
        "name": "Level1"
      },
      {
        "displayName": {
          "en": "Level2"
        },
        "enumValue": 2,
        "name": "Level2"
      },
      {
        "displayName": {
          "en": "Level3"
        },
        "enumValue": 3,
        "name": "Level3"
      }
    ]
  }
}

Un client d’appareil doit envoyer l’état au format JSON comme dans l’exemple suivant. Les valeurs d’état entières possibles sont 1, 2 ou 3 :

{ "IntegerState": 2 }

Propriétés

Pour en savoir plus sur les règles de nommage des propriétés DTDL, consultez DTDL > Propriété. Un nom de propriété ne peut pas commencer par le caractère _.

Propriétés dans les composants

Si la propriété est définie dans un composant, encapsulez la propriété dans le nom du composant. L'exemple suivant définit la propriété maxTempSinceLastReboot dans le composant thermostat2. Le marqueur __t indique que cette section définit un composant :

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

Pour plus d’informations, consultez Tutoriel : Créer et connecter une application cliente à votre application Azure IoT Central.

Types primitifs

Cette section présente des exemples de types de propriétés primitifs qu’un appareil envoie à un service.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété boolean :

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

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil :

{ "BooleanProperty": false }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété long :

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

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil :

{ "LongProperty": 439 }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété date :

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

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil. Les types Date doivent être conformes à ISO 8061 :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété duration :

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

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil – les durées doivent être conformes à la durée selon ISO 8601 :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété float :

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

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil :

{ "FloatProperty": 1.9 }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété string :

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

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil :

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

Types complexes

Cette section présente des exemples de types de propriétés complexes qu’un appareil envoie à un service.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété Enum :

{
  "@type": "Property",
  "displayName": {
    "en": "EnumProperty"
  },
  "name": "EnumProperty",
  "writable": false,
  "schema": {
    "@type": "Enum",
    "displayName": {
      "en": "Enum"
    },
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Item1"
        },
        "enumValue": 0,
        "name": "Item1"
      },
      {
        "displayName": {
          "en": "Item2"
        },
        "enumValue": 1,
        "name": "Item2"
      },
      {
        "displayName": {
          "en": "Item3"
        },
        "enumValue": 2,
        "name": "Item3"
      }
    ]
  }
}

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil. Les valeurs possibles sont 0 et 1. Elles s’affichent dans IoT Central en tant que Item1, Item2 et Item3 :

{ "EnumProperty": 1 }

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété Object. Cet objet a deux champs avec des types string et 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"
      }
    ]
  }
}

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété vector :

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

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété geopoint :

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

Remarque

Un client d’appareil doit envoyer une charge utile JSON ressemblant à l’exemple suivant en tant que propriété signalée dans le jumeau d'appareil :

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

Types de propriétés accessibles en écriture

Cette section présente des exemples de types de propriétés accessibles en écriture qu’un appareil reçoit d’un service.

Si la propriété accessible en écriture est définie dans un composant, le message de propriété souhaité comprend le nom du composant. L’exemple suivant montre le message demandant à l’appareil de mettre à jour targetTemperature dans le composant thermostat2. Le marqueur __t indique que cette section définit un composant :

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

Pour plus d’informations, consultez Connecter un IoT Plug-and-Play plusieurs applications d’appareil composant.

L’appareil ou le module doit confirmer qu’il a reçu la propriété en envoyant une propriété rapportée. La propriété rapportée doit inclure :

value : valeur réelle de la propriété (en général, la valeur reçue, mais l’appareil peut décider de signaler une autre valeur).
ac : code d’accusé de réception qui utilise un code d’état HTTP.
av : version d’accusé de réception qui fait référence à la $version de la propriété souhaitée. Vous pouvez trouver cette valeur dans la charge utile JSON de la propriété souhaitée.
ad : description facultative de l’accusé de réception.

Pour en savoir plus sur ces champs, consultez IoT Plug-and-Play conventions > des réponses d’accusé de réception

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété string accessible en écriture :

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

L’appareil reçoit la charge utile suivante du service :

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

L’appareil doit envoyer la charge utile JSON suivante au service une fois qu’il traite la mise à jour. Ce message inclut le numéro de version de la mise à jour d’origine reçue du service.

Conseil

Si le service est IoT Central, il marque la propriété comme synchronisée dans l’interface utilisateur lorsqu’elle reçoit ce message :

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

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’un type de propriété Enum accessible en écriture :

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

L’appareil reçoit la charge utile suivante du service :

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

L’appareil doit envoyer la charge utile JSON suivante au service une fois qu’il traite la mise à jour. Ce message inclut le numéro de version de la mise à jour d’origine reçue du service.

Conseil

Si le service est IoT Central, il marque la propriété comme synchronisée dans l’interface utilisateur lorsqu’elle reçoit ce message :

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

Commandes

Pour en savoir plus sur les règles de nommage des commandes DTDL, consultez DTDL > Commande. Un nom de commande ne peut pas commencer par le caractère _.

Si la commande est définie dans un composant, le nom de la commande que l’appareil reçoit comprend le nom du composant. Par exemple, si la commande est appelée getMaxMinReport et que le composant est appelé thermostat2, l’appareil reçoit une requête pour exécuter une commande appelée thermostat2*getMaxMinReport.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’une commande qui n’a pas de paramètres et n’attend pas que l’appareil retourne quoi que ce soit :

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

L’appareil reçoit une charge utile vide dans la requête et doit retourner une charge utile vide dans la réponse avec un code de réponse HTTP 200 pour indiquer la réussite de l’opération.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’une commande qui a un paramètre entier et attend que l’appareil retourne une valeur entière :

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

L’appareil reçoit une valeur entière en tant que charge utile de la requête. L’appareil doit retourner une valeur entière en tant que charge utile de réponse avec un code de réponse HTTP 200 pour indiquer la réussite.

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’une commande qui a un paramètre objet et attend que l’appareil retourne un objet. Dans cet exemple, les deux objets ont des champs des types entier et chaîne :

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

L’extrait de code suivant montre un exemple de charge utile de requête envoyée à l’appareil :

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

L’extrait de code suivant montre un exemple de charge utile de réponse envoyée par l’appareil. Utilisez un code de réponse HTTP 200 pour indiquer la réussite :

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

Conseil

IoT Central a ses propres conventions pour implémenter des commandes longues et des commandes hors connexion.

Étapes suivantes

Maintenant que vous avez découvert les charges utiles de l’appareil, une suggestion d’étapes suivantes consiste à lire le guide du développeur d’appareils.

Charges utiles de télémétrie, de propriétés et de commandes

Voir les données brutes

Télémétrie

Télémétrie dans les composants

Télémétrie dans les interfaces héritées

Types primitifs

Types complexes

Types d’événements et d’états

Propriétés

Propriétés dans les composants

Types primitifs

Types complexes

Types de propriétés accessibles en écriture

Commandes

Étapes suivantes

Ressources supplémentaires