Come usare l'API REST IoT Central per controllare i dispositivi
L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. È possibile usare l'API REST per controllare dispositivi nell'applicazione IoT Central. L'API REST di IoT Central consente di:
- Leggere l'ultimo valore di telemetria noto da un dispositivo.
- Leggere i valori delle proprietà da un dispositivo.
- Impostare proprietà scrivibili in un dispositivo.
- Chiamare comandi in un dispositivo.
Questo articolo descrive come usare l'API /devices/{device_id} per controllare i singoli dispositivi. È anche possibile usare i processi per controllare i dispositivi in blocco.
Un dispositivo può raggruppare le proprietà, i dati di telemetria e i comandi supportati in componenti e moduli.
Ogni chiamata API REST di IoT Central richiede un'intestazione di autorizzazione. Per altre informazioni, vedere Come autenticare e autorizzare le chiamate API REST di IoT Central.
Per la documentazione di riferimento per l'API REST di IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.
Suggerimento
È possibile usare Postman per provare le chiamate API REST descritte in questo articolo. Scaricare la raccolta Postman di IoT Central e importarla in Postman. Nella raccolta sarà necessario impostare variabili come il sottodominio dell'app e il token di amministratore.
Per informazioni su come controllare i dispositivi usando l'interfaccia utente di IoT Central, vedere
- Usare le proprietà in una soluzione Azure IoT Central.
- Come usare i comandi in una soluzione Azure IoT Central().
Componenti e moduli
I componenti consentono di raggruppare e riutilizzare le funzionalità dei dispositivi. Per altre informazioni sui componenti e sui modelli di dispositivo, vedere la guida alla modellazione Plug and Play IoT.
Non tutti i modelli di dispositivo usano componenti. Lo screenshot seguente mostra il modello di dispositivo per un termostato semplice in cui tutte le funzionalità sono definite in una singola interfaccia denominataComponente radice:
Lo screenshot seguente mostra un modello di dispositivo del controller della temperatura che usa i componenti. Il controller di temperatura ha due componenti termostato e un componente informativo del dispositivo:
In IoT Central un modulo fa riferimento a un modulo IoT Edge in esecuzione in un dispositivo IoT Edge connesso. Un modulo può avere un modello semplice, ad esempio il termostato che non usa componenti. Un modulo può anche usare componenti per organizzare un set di funzionalità più complesso. Lo screenshot seguente mostra un esempio di modello di dispositivo che usa i moduli. Il dispositivo sensore ambientale ha un modulo denominato SimulatedTemperatureSensor e un'interfaccia ereditata denominata management:
Ottenere un componente del dispositivo
Usare la richiesta seguente per recuperare i componenti da un dispositivo denominato temperature-controller-01:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente. La value matrice contiene i dettagli di ogni componente del dispositivo:
{
"value": [
{
"@type": "Component",
"name": "thermostat1",
"displayName": "Thermostat One",
"description": "Thermostat One of Two."
},
{
"@type": "Component",
"name": "thermostat2",
"displayName": "Thermostat Two",
"description": "Thermostat Two of Two."
},
{
"@type": "Component",
"name": "deviceInformation",
"displayName": "Device Information interface",
"description": "Optional interface with basic device hardware information."
}
]
}
Ottenere un modulo del dispositivo
Usare la richiesta seguente per recuperare un elenco di moduli in esecuzione in un dispositivo IoT Edge connesso denominato environmental-sensor-01:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente. La matrice di moduli include solo moduli personalizzati in $edgeAgent esecuzione nel dispositivo IoT Edge, non i moduli e $edgeHub predefiniti:
{
"value": [
{
"@type": [
"Relationship",
"EdgeModule"
],
"name": "SimulatedTemperatureSensor",
"displayName": "SimulatedTemperatureSensor"
}
]
}
Usare la richiesta seguente per recuperare un elenco dei componenti in un modulo denominato SimulatedTemperatureSensor:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31
Leggere i dati di telemetria
Usare la richiesta seguente per recuperare l'ultimo valore di telemetria noto da un dispositivo che non usa componenti. In questo esempio viene chiamato thermostat-01 il dispositivo e i dati di telemetria vengono chiamati temperature:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/telemetry/temperature?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente:
{
"timestamp": "2021-03-24T12:33:15.223Z",
"value": 40.10993804456927
}
Usare la richiesta seguente per recuperare l'ultimo valore di telemetria noto da un dispositivo che usa componenti. In questo esempio il dispositivo viene chiamato , il componente viene chiamato temperature-controller-01thermostat2e i dati di telemetria sono denominati temperature:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/telemetry/temperature?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente:
{
"timestamp": "2021-03-24T12:43:44.968Z",
"value": 70.29168040339141
}
Se il dispositivo è un dispositivo IoT Edge, usare la richiesta seguente per recuperare l'ultimo valore di telemetria noto da un modulo. Questo esempio usa un dispositivo denominato environmental-sensor-01 con un modulo denominato SimulatedTemperatureSensor e i dati di telemetria denominati ambient. Il ambient tipo di telemetria ha valori di temperatura e umidità:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/telemetry/ambient?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente:
{
"timestamp": "2021-03-25T15:44:34.955Z",
"value": {
"temperature": 21.18032378129676,
"humidity": 25
}
}
Suggerimento
Per accedere ai dati di telemetria da un componente in un modulo, usare /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.
Leggere le proprietà
Usare la richiesta seguente per recuperare i valori delle proprietà da un dispositivo che non usa componenti. In questo esempio il dispositivo viene chiamato thermostat-01:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente. Mostra che il dispositivo segnala un singolo valore della proprietà:
{
"maxTempSinceLastReboot": 93.95907131817654,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T12:47:46.7571438Z"
}
}
}
Utilizzare la richiesta seguente per recuperare i valori delle proprietà da tutti i componenti. In questo esempio il dispositivo viene chiamato temperature-controller-01:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/properties?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente:
{
"serialNumber": "Explicabo animi nihil qui facere sit explicabo nisi.",
"$metadata": {
"serialNumber": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
},
"thermostat1": {
"maxTempSinceLastReboot": 79.7290121339184,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
}
},
"thermostat2": {
"maxTempSinceLastReboot": 54.214860556320424,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
}
},
"deviceInformation": {
"manufacturer": "Eveniet culpa sed sit omnis.",
"$metadata": {
"manufacturer": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"model": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"swVersion": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"osName": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"processorArchitecture": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"processorManufacturer": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"totalStorage": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"totalMemory": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
},
"model": "Necessitatibus id ab dolores vel eligendi fuga.",
"swVersion": "Ut minus ipsum ut omnis est asperiores harum.",
"osName": "Atque sit omnis eum sapiente eum tenetur est dolor.",
"processorArchitecture": "Ratione enim dolor iste iure.",
"processorManufacturer": "Aliquam eligendi sit ipsa.",
"totalStorage": 36.02825898541592,
"totalMemory": 55.442695395750505
}
}
Utilizzare la richiesta seguente per recuperare un valore della proprietà da un singolo componente. In questo esempio il dispositivo viene chiamato temperature-controller-01 e il componente viene chiamato thermostat2:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente:
{
"maxTempSinceLastReboot": 24.445128131004935,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T14:03:53.787491Z"
}
}
}
Se il dispositivo è un dispositivo IoT Edge, usare la richiesta seguente per recuperare i valori delle proprietà da un modulo. Questo esempio usa un dispositivo denominato environmental-sensor-01 con un modulo denominato SimulatedTemperatureSensor:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente:
{
"$metadata": {
"SendData": {
"desiredValue": true,
"desiredVersion": 1
},
"SendInterval": {
"desiredValue": 10,
"desiredVersion": 1
}
}
}
Suggerimento
Per accedere alle proprietà da un componente in un modulo, usare /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.
Scrivere proprietà
Alcune proprietà sono scrivibili. Nel modello termostato di esempio, la targetTemperature proprietà è una proprietà scrivibile.
Usare la richiesta seguente per scrivere un singolo valore di proprietà in un dispositivo che non usa componenti. In questo esempio il dispositivo viene chiamato thermostat-01:
PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31
Il corpo della richiesta è simile all'esempio seguente:
{
"targetTemperature": 65.5
}
La risposta a questa richiesta è simile all'esempio seguente:
{
"$metadata": {
"targetTemperature": {
"desiredValue": 65.5
}
}
}
Suggerimento
Per aggiornare tutte le proprietà in un dispositivo, usare PUT invece di PATCH.
Usare la richiesta seguente per scrivere un singolo valore di proprietà in un dispositivo che usa componenti. In questo esempio il dispositivo viene chiamato temperature-controller-01 e il componente viene chiamato thermostat2:
PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31
Il corpo della richiesta è simile all'esempio seguente:
{
"targetTemperature": 65.5
}
La risposta a questa richiesta è simile all'esempio seguente:
{
"$metadata": {
"targetTemperature": {
"desiredValue": 65.5
}
}
}
Suggerimento
Per aggiornare tutte le proprietà di un componente, usare PUT anziché PATCH.
Se il dispositivo è un dispositivo IoT Edge, usare la richiesta seguente per scrivere un singolo valore della proprietà in un modulo. Questo esempio usa un dispositivo denominato environmental-sensor-01, un modulo denominato e una proprietà denominata SimulatedTemperatureSensorSendInterval:
PUT https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31
Il corpo della richiesta è simile all'esempio seguente:
{
"SendInterval": 20
}
La risposta a questa richiesta è simile all'esempio seguente:
{
"$metadata": {
"SendInterval": {
"desiredValue": 20
}
}
}
Suggerimento
Per aggiornare tutte le proprietà in un modulo, usare PUT anziché PATCH.
Aggiornare le proprietà del modulo
Se si usa un dispositivo IoT Edge, usare la richiesta seguente per recuperare i valori delle proprietà da un modulo:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/properties?api-version=2022-07-31
Se si usa un dispositivo IoT Edge, usare la richiesta seguente per recuperare i valori delle proprietà da un componente in un modulo:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties?api-version=2022-07-31
Chiamare i comandi
È possibile usare l'API REST per chiamare i comandi del dispositivo e recuperare la cronologia dei comandi.
Usare la richiesta seguente per chiamare un comando nel dispositivo che non usa componenti. In questo esempio viene chiamato thermostat-01 il dispositivo e il comando viene chiamato getMaxMinReport:
POST https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31
Il corpo della richiesta è simile all'esempio seguente:
{
"request": "2021-03-24T12:55:20.789Z"
}
La risposta a questa richiesta è simile all'esempio seguente:
{
"response": {
"maxTemp": 21.002000799562367,
"minTemp": 73.09674605264892,
"avgTemp": 59.54553991653756,
"startTime": "2022-02-28T15:02:56.789Z",
"endTime": "2021-05-05T03:50:56.412Z"
},
"responseCode": 200
}
Per visualizzare la cronologia per questo comando, usare la richiesta seguente:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31
La risposta a questa richiesta è simile all'esempio seguente:
{
"value": [
{
"response": {
"maxTemp": 71.43744908819954,
"minTemp": 51.29986610160005,
"avgTemp": 39.577384387771744,
"startTime": "2021-06-20T00:38:17.620Z",
"endTime": "2022-01-07T22:30:41.104Z"
},
"responseCode": 200
}
]
}
Usare la richiesta seguente per chiamare un comando nel dispositivo che usa componenti. In questo esempio il dispositivo viene chiamato , il componente viene chiamato temperature-controller-01thermostat2e il comando è denominato getMaxMinReport:
POST https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31
I formati del payload e della risposta della richiesta sono gli stessi di un dispositivo che non usa componenti.
Per visualizzare la cronologia per questo comando, usare la richiesta seguente:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31
Suggerimento
Per chiamare i comandi in un componente di un modulo, usare /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.
Passaggi successivi
Dopo aver appreso come controllare i dispositivi con l'API REST, un passaggio successivo consigliato consiste nell'apprendere come usare l'API REST di IoT Central per creare e gestire processi.