Payload di telemetria, proprietà e comandi

Articolo
02/06/2024

Un modello di dispositivo definisce:

Telemetria inviata da un dispositivo a un servizio.
Le proprietà di un dispositivo si sincronizzano con un servizio.
Comandi che il servizio chiama su un dispositivo.

Suggerimento

Azure IoT Central è un servizio che segue le convenzioni plug and play. In IoT Central il modello di dispositivo fa parte di un modello di dispositivo. IoT Central supporta attualmente DTDL v2 con un'estensione IoT Central. Un'applicazione IoT Central prevede di ricevere dati JSON con codifica UTF-8.

Questo articolo descrive i payload JSON che i dispositivi inviano e ricevono per dati di telemetria, proprietà e comandi definiti in un modello di dispositivo DTDL.

L'articolo non descrive tutti i tipi possibili di dati di telemetria, proprietà e payload dei comandi, ma gli esempi illustrano i tipi di chiave.

Ogni esempio mostra un frammento di codice del modello di dispositivo che definisce il tipo e i payload JSON di esempio per illustrare come il dispositivo deve interagire con un servizio compatibile con Plug and Play, ad esempio IoT Central.

I frammenti JSON di esempio in questo articolo usano Digital Twin Definition Language (DTDL) v2. Esistono anche alcune estensioni DTDL usate da IoT Central .

Per il codice del dispositivo di esempio che mostra alcuni di questi payload in uso, vedere l'Connessione esercitazione Creare e connettere un'applicazione del dispositivo di esempio Plug and Play IoT in esecuzione in Linux o Windows per hub IoT o l'esercitazione Creare e connettere un'applicazione client all'applicazione Azure IoT Central.

Visualizzare dati non elaborati

Se si usa IoT Central, è possibile visualizzare i dati non elaborati inviati da un dispositivo a un'applicazione. Questa visualizzazione è utile per la risoluzione dei problemi relativi al payload inviato da un dispositivo. Per visualizzare i dati non elaborati inviati da un dispositivo:

Passare al dispositivo dalla pagina Dispositivi .
Selezionare la scheda Dati non elaborati :

In questa visualizzazione è possibile selezionare le colonne da visualizzare e impostare un intervallo di tempo da visualizzare. La colonna Dati senza modello contiene i dati del dispositivo che non corrispondono ad alcuna definizione di proprietà o di telemetria nel modello di dispositivo.

Per altri suggerimenti per la risoluzione dei problemi, vedere Risolvere i problemi relativi ai dati dei dispositivi non visualizzati in Azure IoT Central.

Telemetria

Per altre informazioni sulle regole di denominazione dei dati di telemetria DTDL, vedere DTDL Telemetry (Telemetria DTDL>). Non è possibile avviare un nome di telemetria usando il _ carattere .

Non creare tipi di telemetria con i nomi seguenti. IoT Central usa internamente questi nomi riservati. Se si tenta di usare questi nomi, IoT Central ignorerà i dati:

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

Telemetria nei componenti

Se i dati di telemetria vengono definiti in un componente, aggiungere una proprietà del messaggio personalizzata denominata $.sub con il nome del componente come definito nel modello di dispositivo. Per altre informazioni, vedere Esercitazione: Connessione un Plug and Play IoT più applicazioni per dispositivi componenti. Questa esercitazione illustra come usare linguaggi di programmazione diversi per inviare dati di telemetria da un componente.

Importante

Per visualizzare correttamente i dati di telemetria dai componenti ospitati nei moduli IoT Edge, usare IoT Edge versione 1.2.4 o successiva. Se si usa una versione precedente, i dati di telemetria dei componenti nei moduli IoT Edge vengono visualizzati come _unmodeleddata.

Telemetria nelle interfacce ereditate

Se i dati di telemetria sono definiti in un'interfaccia ereditata, il dispositivo invia i dati di telemetria come se fosse definito nell'interfaccia radice. Dato il modello di dispositivo seguente:

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

Il dispositivo invia i dati di telemetria della tensione del contatore usando il payload seguente. Il dispositivo non include il nome dell'interfaccia nel payload:

{
    "MeterVoltage": 5.07
}

Tipi primitivi

Questa sezione illustra esempi di tipi di telemetria primitivi che un dispositivo può trasmettere.

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un boolean tipo di telemetria:

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

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente:

{ "BooleanTelemetry": true }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un string tipo di telemetria:

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

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un integer tipo di telemetria:

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

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente:

{ "IntegerTelemetry": 23 }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un double tipo di telemetria:

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

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente:

{ "DoubleTelemetry": 56.78 }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un dateTime tipo di telemetria:

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

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente: DateTime i tipi devono essere in formato ISO 8061:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un duration tipo di telemetria:

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

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente: le durate devono essere in formato ISO 8601:

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

Tipi complessi

Questa sezione illustra esempi di tipi di telemetria complessi che un dispositivo può trasmettere in streaming.

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un Enum tipo di telemetria:

{
  "@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 del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente. I valori possibili sono 0, 1e 2 visualizzati in IoT Central come Item1, Item2e Item3:

{ "EnumTelemetry": 1 }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un Object tipo di telemetria. Questo oggetto ha tre campi con tipi dateTime, integere 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 del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente. DateTime i tipi devono essere conformi a ISO 8061. I valori possibili per Property3 sono 0, 1e visualizzati in IoT Central come Item1, Item2e Item3:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un vector tipo di telemetria:

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

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un geopoint tipo di telemetria:

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

Nota

Il tipo di schema del punto geografico fa parte dell'estensione IoT Central in DTDL. IoT Central supporta attualmente il tipo di schema geopoint e il tipo semantico di posizione per la compatibilità con le versioni precedenti.

Un client del dispositivo deve inviare i dati di telemetria come JSON simile all'esempio seguente. IoT Central visualizza il valore come segnaposto su una mappa:

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

Tipi di evento e stato

Questa sezione illustra esempi di eventi di telemetria e indica che un dispositivo invia a un'applicazione IoT Central.

Nota

I tipi di schema di eventi e stato fanno parte dell'estensione IoT Central a DTDL.

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un integer tipo di evento:

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

Un client del dispositivo deve inviare i dati dell'evento come JSON simile all'esempio seguente:

{ "IntegerEvent": 74 }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un integer tipo di stato:

{
  "@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 del dispositivo deve inviare lo stato come JSON simile all'esempio seguente. I valori di stato integer possibili sono 1, 2o 3:

{ "IntegerState": 2 }

Proprietà

Per altre informazioni sulle regole di denominazione delle proprietà DTDL, vedere Proprietà DTDL>. Non è possibile avviare un nome di proprietà usando il _ carattere .

Proprietà nei componenti

Se la proprietà è definita in un componente, eseguire il wrapping della proprietà nel nome del componente. Nell'esempio seguente viene impostato l'oggetto maxTempSinceLastReboot thermostat2 nel componente . L'indicatore __t indica che questa sezione definisce un componente:

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

Per altre informazioni, vedere Esercitazione: Creare e connettere un'applicazione client all'applicazione Azure IoT Central.

Tipi primitivi

Questa sezione illustra esempi di tipi di proprietà primitivi inviati da un dispositivo a un servizio.

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un boolean tipo di proprietà:

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

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello:

{ "BooleanProperty": false }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un long tipo di proprietà:

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

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello:

{ "LongProperty": 439 }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un date tipo di proprietà:

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

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello. Date I tipi devono essere conformi a ISO 8061:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un duration tipo di proprietà:

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

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello. Le durate devono essere conformi alla durata ISO 8601:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un float tipo di proprietà:

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

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello:

{ "FloatProperty": 1.9 }

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un string tipo di proprietà:

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

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello:

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

Tipi complessi

Questa sezione illustra esempi di tipi di proprietà complessi inviati da un dispositivo a un servizio.

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un Enum tipo di proprietà:

{
  "@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 del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello. I valori possibili sono 0, 1e visualizzati in IoT Central come Item1, Item2e Item3:

{ "EnumProperty": 1 }

Il frammento di codice seguente di un modello di dispositivo mostra la definizione di un Object tipo di proprietà. Questo oggetto ha due campi con tipi string e 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 del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un vector tipo di proprietà:

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

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un geopoint tipo di proprietà:

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

Nota

Un client del dispositivo deve inviare un payload JSON simile all'esempio seguente come proprietà segnalata nel dispositivo gemello:

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

Tipi di proprietà scrivibili

Questa sezione illustra esempi di tipi di proprietà scrivibili ricevuti da un dispositivo da un servizio.

Se la proprietà scrivibile è definita in un componente, il messaggio della proprietà desiderato include il nome del componente. L'esempio seguente mostra il messaggio che richiede al dispositivo di aggiornare targetTemperature nel thermostat2 componente. L'indicatore __t indica che questa sezione definisce un componente:

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

Per altre informazioni, vedere Connessione un Plug and Play IoT più applicazioni per dispositivi componenti.

Il dispositivo o il modulo deve confermare che ha ricevuto la proprietà inviando una proprietà segnalata. La proprietà segnalata deve includere:

value - valore effettivo della proprietà (in genere il valore ricevuto, ma il dispositivo può decidere di segnalare un valore diverso).
ac : codice di riconoscimento che usa un codice di stato HTTP.
av : una versione di riconoscimento che fa riferimento all'oggetto $version della proprietà desiderata. È possibile trovare questo valore nel payload JSON della proprietà desiderata.
ad : una descrizione facoltativa del riconoscimento.

Per altre informazioni su questi campi, vedere Plug and Play IoT convenzioni risposte > di riconoscimento

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un tipo di proprietà scrivibile string :

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

Il dispositivo riceve il payload seguente dal servizio:

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

Il dispositivo deve inviare il payload JSON seguente al servizio dopo l'elaborazione dell'aggiornamento. Questo messaggio include il numero di versione dell'aggiornamento originale ricevuto dal servizio.

Suggerimento

Se il servizio è IoT Central, contrassegna la proprietà come sincronizzata nell'interfaccia utente quando riceve questo messaggio:

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

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un tipo di proprietà scrivibile Enum :

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

Il dispositivo riceve il payload seguente dal servizio:

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

Suggerimento

Se il servizio è IoT Central, contrassegna la proprietà come sincronizzata nell'interfaccia utente quando riceve questo messaggio:

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

Comandi

Per altre informazioni sulle regole di denominazione dei comandi DTDL, vedere Comando DTDL>. Non è possibile avviare un nome di comando usando il _ carattere .

Se il comando è definito in un componente, il nome del comando ricevuto dal dispositivo include il nome del componente. Ad esempio, se il comando viene chiamato e il componente viene chiamato getMaxMinReport thermostat2, il dispositivo riceve una richiesta per eseguire un comando denominato thermostat2*getMaxMinReport.

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un comando senza parametri e che non prevede che il dispositivo restituisca nulla:

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

Il dispositivo riceve un payload vuoto nella richiesta e deve restituire un payload vuoto nella risposta con un codice di risposta HTTP per indicare l'esito 200 positivo.

Il frammento di codice seguente da un modello di dispositivo mostra la definizione di un comando con un parametro integer e che prevede che il dispositivo restituisca un valore intero:

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

Il dispositivo riceve un valore intero come payload della richiesta. Il dispositivo deve restituire un valore intero come payload della risposta con un 200 codice di risposta HTTP per indicare l'esito positivo.

Il frammento di codice seguente di un modello di dispositivo mostra la definizione di un comando con un parametro oggetto e che prevede che il dispositivo restituisca un oggetto. In questo esempio entrambi gli oggetti hanno campi integer e stringa:

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

Il frammento di codice seguente mostra un payload di richiesta di esempio inviato al dispositivo:

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

Il frammento di codice seguente mostra un payload di risposta di esempio inviato dal dispositivo. Usare un 200 codice di risposta HTTP per indicare l'esito positivo:

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

Suggerimento

IoT Central ha le proprie convenzioni per l'implementazione di comandi con esecuzione prolungata e comandi offline.

Passaggi successivi

Dopo aver appreso le informazioni sui payload dei dispositivi, è consigliabile seguire i passaggi successivi per leggere la Guida per sviluppatori di dispositivi.

Condividi tramite

Payload di telemetria, proprietà e comandi

Visualizzare dati non elaborati

Telemetria

Telemetria nei componenti

Telemetria nelle interfacce ereditate

Tipi primitivi

Tipi complessi

Tipi di evento e stato

Proprietà

Proprietà nei componenti

Tipi primitivi

Tipi complessi

Tipi di proprietà scrivibili

Comandi

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive