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 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

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 denominata Componente radice:

Screenshot che mostra un semplice dispositivo termostato senza componenti.

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:

Screenshot che mostra un dispositivo del controller della temperatura con due componenti termostato e un componente 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, 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:

Screenshot che mostra un dispositivo sensore ambientale con un modulo.

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.