Dela via

Använda IoT Central REST API till att styra enheter

  • Artikel

Med REST API för IoT Central kan du utveckla klientprogram som integreras med IoT Central-program. Du kan använda REST-API:et för att styra enheter i ditt IoT Central-program. Med REST-API:et kan du:

  • Läs det senast kända telemetrivärdet från en enhet.
  • Läsa egenskapsvärden från en enhet.
  • Ange skrivbara egenskaper på en enhet.
  • Anropa kommandon på en enhet.

I den här artikeln beskrivs hur du använder API:et /devices/{device_id} för att styra enskilda enheter. Du kan också använda jobb för att styra enheter i grupp.

En enhet kan gruppera egenskaper, telemetri och kommandon som den stöder i komponenter och moduler.

Varje IoT Central REST API-anrop kräver ett auktoriseringshuvud. Mer information finns i Autentisera och auktorisera IoT Central REST API-anrop.

Referensdokumentationen för REST API:et för IoT Central finns i Referens för Rest API för Azure IoT Central.

Information om hur du styr enheter med hjälp av IoT Central-användargränssnittet finns i

Komponenter och moduler

Med komponenter kan du gruppera och återanvända enhetsfunktioner. Mer information om komponenter och enhetsmodeller finns i modellguiden för IoT Plug and Play.

Alla enhetsmallar använder inte komponenter. Följande skärmbild visar enhetsmallen för en enkel termostat där alla funktioner definieras i ett enda gränssnitt som kallas rotkomponenten:

Skärmbild som visar en enkel termostatenhet utan komponent.

Följande skärmbild visar en enhetsmall för temperaturstyrenhet som använder komponenter. Temperaturstyrenheten har två termostatkomponenter och en komponent för enhetsinformation:

Skärmbild som visar en temperaturstyrenhet med två termostatkomponenter och en komponent för enhetsinformation.

I IoT Central refererar en modul till en IoT Edge-modul som körs på en ansluten IoT Edge-enhet. En modul kan ha en enkel modell, till exempel termostaten som inte använder komponenter. En modul kan också använda komponenter för att organisera en mer komplex uppsättning funktioner. Följande skärmbild visar ett exempel på en enhetsmall som använder moduler. Miljösensorenheten har en modul som heter SimulatedTemperatureSensor och ett ärvt gränssnitt med namnet management:

Skärmbild som visar en miljösensorenhet med en modul.

Hämta en enhetskomponent

Använd följande begäran för att hämta komponenterna från en enhet med namnet temperature-controller-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel. Matrisen value innehåller information om varje enhetskomponent:

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

Hämta en enhetsmodul

Använd följande begäran för att hämta en lista över moduler som körs på en ansluten IoT Edge-enhet med namnet environmental-sensor-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel. Matrisen med moduler innehåller endast anpassade moduler som körs på IoT Edge-enheten, inte de inbyggda $edgeAgent modulerna och $edgeHub :

{
  "value": [
    {
      "@type": [
        "Relationship",
        "EdgeModule"
      ],
      "name": "SimulatedTemperatureSensor",
      "displayName": "SimulatedTemperatureSensor"
    }
  ]
}

Använd följande begäran för att hämta en lista över komponenterna i en modul med namnet SimulatedTemperatureSensor:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

Läs telemetri

Använd följande begäran för att hämta det senast kända telemetrivärdet från en enhet som inte använder komponenter. I det här exemplet anropas thermostat-01 enheten och telemetrin kallas temperature:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/telemetry/temperature?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel:

{
  "timestamp": "2021-03-24T12:33:15.223Z",
  "value": 40.10993804456927
}

Använd följande begäran för att hämta det senast kända telemetrivärdet från en enhet som använder komponenter. I det här exemplet kallas temperature-controller-01enheten , komponenten kallas thermostat2, och telemetrin kallas temperature:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/telemetry/temperature?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel:

{
  "timestamp": "2021-03-24T12:43:44.968Z",
  "value": 70.29168040339141
}

Om enheten är en IoT Edge-enhet använder du följande begäran för att hämta det senast kända telemetrivärdet från en modul. I det här exemplet används en enhet som heter environmental-sensor-01 med en modul med namnet SimulatedTemperatureSensor och telemetri med namnet ambient. Telemetritypen ambient har temperatur- och luftfuktighetsvärden:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/telemetry/ambient?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel:

{
  "timestamp": "2021-03-25T15:44:34.955Z",
  "value": {
    "temperature": 21.18032378129676,
    "humidity": 25
  }
}

Dricks

Om du vill komma åt telemetrin från en komponent i en modul använder du /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Läsegenskaper

Använd följande begäran för att hämta egenskapsvärdena från en enhet som inte använder komponenter. I det här exemplet kallas thermostat-01enheten :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel. Den visar att enheten rapporterar ett enda egenskapsvärde:

{
  "maxTempSinceLastReboot": 93.95907131817654,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T12:47:46.7571438Z"
    }
  }
}

Använd följande begäran för att hämta egenskapsvärden från alla komponenter. I det här exemplet kallas temperature-controller-01enheten :

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/properties?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel:

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

Använd följande begäran för att hämta ett egenskapsvärde från en enskild komponent. I det här exemplet anropas temperature-controller-01 enheten och komponenten kallas thermostat2:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel:

{
  "maxTempSinceLastReboot": 24.445128131004935,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T14:03:53.787491Z"
    }
  }
}

Om enheten är en IoT Edge-enhet använder du följande begäran för att hämta egenskapsvärden från en modul. I det här exemplet används en enhet som heter environmental-sensor-01 med en modul med namnet SimulatedTemperatureSensor:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel:

{
  "$metadata": {
    "SendData": {
      "desiredValue": true,
      "desiredVersion": 1
    },
    "SendInterval": {
      "desiredValue": 10,
      "desiredVersion": 1
    }
  }
}

Dricks

Om du vill komma åt egenskaperna från en komponent i en modul använder du /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Skrivegenskaper

Vissa egenskaper är skrivbara. I exemplet termostatmodell är egenskapen targetTemperature en skrivbar egenskap.

Använd följande begäran för att skriva ett enskilt egenskapsvärde till en enhet som inte använder komponenter. I det här exemplet kallas thermostat-01enheten :

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31

Begärandetexten ser ut som i följande exempel:

{
  "targetTemperature": 65.5
}

Svaret på den här begäran ser ut som i följande exempel:

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Dricks

Om du vill uppdatera alla egenskaper på en enhet använder du PUT i stället för PATCH.

Använd följande begäran för att skriva ett enskilt egenskapsvärde till en enhet som använder komponenter. I det här exemplet anropas temperature-controller-01 enheten och komponenten kallas thermostat2:

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

Begärandetexten ser ut som i följande exempel:

{
  "targetTemperature": 65.5
}

Svaret på den här begäran ser ut som i följande exempel:

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Dricks

Om du vill uppdatera alla egenskaper för en komponent använder du PUT i stället för PATCH.

Om enheten är en IoT Edge-enhet använder du följande begäran för att skriva ett enskilt egenskapsvärde till en modul. I det här exemplet används en enhet med namnet environmental-sensor-01, en modul med namnet SimulatedTemperatureSensor, och en egenskap som heter SendInterval:

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

Begärandetexten ser ut som i följande exempel:

{
  "SendInterval": 20
}

Svaret på den här begäran ser ut som i följande exempel:

{
  "$metadata": {
    "SendInterval": {
      "desiredValue": 20
    }
  }
}

Dricks

Om du vill uppdatera alla egenskaper i en modul använder du PUT i stället för PATCH.

Uppdatera modulegenskaper

Om du använder en IoT Edge-enhet använder du följande begäran för att hämta egenskapsvärden från en modul:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/properties?api-version=2022-07-31

Om du använder en IoT Edge-enhet använder du följande begäran för att hämta egenskapsvärden från en komponent i en modul:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties?api-version=2022-07-31

Anropa kommandon

Du kan använda REST-API:et för att anropa enhetskommandon och hämta kommandohistoriken.

Använd följande begäran för att anropa ett kommando på en enhet som inte använder komponenter. I det här exemplet anropas thermostat-01 enheten och kommandot kallas getMaxMinReport:

POST https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

Begärandetexten ser ut som i följande exempel:

{
  "request": "2021-03-24T12:55:20.789Z"
}

Svaret på den här begäran ser ut som i följande exempel:

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

Om du vill visa historiken för det här kommandot använder du följande begäran:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

Svaret på den här begäran ser ut som i följande exempel:

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

Använd följande begäran för att anropa ett kommando på en enhet som använder komponenter. I det här exemplet kallas temperature-controller-01enheten , komponenten heter thermostat2och kommandot heter getMaxMinReport:

POST https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

Formaten för begärandenyttolasten och svaret är desamma som för en enhet som inte använder komponenter.

Om du vill visa historiken för det här kommandot använder du följande begäran:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

Dricks

Om du vill anropa kommandon i en komponent i en modul använder du /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Nästa steg

Nu när du har lärt dig hur du styr enheter med REST-API:et är ett föreslaget nästa steg att lära dig hur du använder REST-API:et för IoT Central för att skapa och hantera jobb.