Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
L'API REST IoT Central consente di sviluppare applicazioni client che si integrano con le applicazioni IoT Central. È possibile usare l'API REST per controllare i dispositivi nell'applicazione IoT Central. L'API REST consente di:
- Leggere l'ultimo valore di telemetria noto da un dispositivo.
- Legge 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 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.
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 semplice termostato in cui tutte le funzionalità sono definite in una singola interfaccia denominata Componente radice:
Lo screenshot seguente mostra un modello di dispositivo regolatore di temperatura che usa i componenti. Il regolatore di temperatura ha due componenti termostato e un componente di informazioni sul 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 come il termostato che non usa componenti. Un modulo può anche usare componenti per organizzare un insieme 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 matrice value 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 esecuzione nel dispositivo IoT Edge, non i moduli predefiniti $edgeAgent e $edgeHub:
{
"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, il dispositivo è chiamato thermostat-01 e i dati di telemetria sono 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 è chiamato temperature-controller-01, il componente è chiamato thermostat2 e i dati di telemetria sono chiamati 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 dati di telemetria denominati ambient. Il tipo di dati di telemetria ambient 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à
Gli esempi seguenti usano dispositivi gemelli per leggere i valori delle proprietà da un dispositivo. Per informazioni sui dispositivi gemelli e sul ruolo del $metadata campo, vedere Introduzione ai dispositivi gemelli.
Usare la richiesta seguente per recuperare i valori delle proprietà da un dispositivo che non usa componenti. In questo esempio, il dispositivo è 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"
}
}
}
Usare la richiesta seguente per recuperare i valori delle proprietà da tutti i componenti. In questo esempio, il dispositivo è 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
}
}
Usare la richiesta seguente per recuperare un valore della proprietà da un singolo componente. In questo esempio, il dispositivo è chiamato temperature-controller-01 e il componente è 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 le proprietà
Gli esempi seguenti usano i device twins per scrivere i valori delle proprietà di un dispositivo. Per informazioni sui dispositivi gemelli e sul ruolo del $metadata campo, vedere Introduzione ai dispositivi gemelli.
Alcune proprietà sono scrivibili. Nel modello di termostato d’esempio, la proprietà targetTemperature è 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 è 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 è chiamato temperature-controller-01 e il componente è 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à in 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 SimulatedTemperatureSensor e una proprietà denominata SendInterval:
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 in un dispositivo che non usa componenti. In questo esempio è chiamato thermostat-01 il dispositivo e il comando è 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 in un dispositivo che usa componenti. In questo esempio, il dispositivo è chiamato temperature-controller-01, il componente è chiamato thermostat2 e il comando è chiamato 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 in un modulo, usare /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.