Az IoT Central REST API használata eszközök vezérlésére

Cikk
08/08/2024

Az IoT Central REST API lehetővé teszi az IoT Central-alkalmazásokkal integrálható ügyfélalkalmazások fejlesztését. A REST API-val vezérelheti az eszközöket az IoT Central-alkalmazásban. A REST API a következőket teszi lehetővé:

Olvassa el az eszköz utolsó ismert telemetriai értékét.
Tulajdonságértékek beolvasása egy eszközről.
Írható tulajdonságok beállítása az eszközön.
Parancsok hívása egy eszközön.

Ez a cikk azt ismerteti, hogyan használhatja az API-t az /devices/{device_id} egyes eszközök vezérlésére. A feladatokat az eszközök tömeges vezérlésére is használhatja.

Az eszközök összetevőkbe és modulokba csoportosíthatják az általa támogatott tulajdonságokat, telemetriát és parancsokat.

Minden IoT Central REST API-híváshoz szükség van egy engedélyezési fejlécre. További információ: IoT Central REST API-hívások hitelesítése és engedélyezése.

Az IoT Central REST API referenciadokumentációját az Azure IoT Central REST API-referenciájában találja.

Az eszközök IoT Central felhasználói felülettel történő vezérlésének megismeréséhez lásd:

Összetevők és modulok

Az összetevők lehetővé teszik az eszközfunkciók csoportosítását és újrafelhasználását. Az összetevőkkel és az eszközmodellekkel kapcsolatos további információkért tekintse meg az IoT Plug and Play modellezési útmutatóját.

Nem minden eszközsablon használ összetevőket. Az alábbi képernyőképen egy egyszerű termosztát eszközsablonja látható, ahol az összes képesség egy gyökérösszetevő nevű felületen van definiálva:

Az alábbi képernyőképen egy összetevőket használó hőmérséklet-vezérlő eszközsablon látható. A hőmérséklet-vezérlő két termosztát-összetevővel és egy eszközinformációs összetevővel rendelkezik:

Az IoT Centralban a modul egy csatlakoztatott IoT Edge-eszközön futó IoT Edge-modulra utal. Egy modul rendelkezhet olyan egyszerű modellel, mint a termosztát, amely nem használ összetevőket. A modulok az összetevők használatával összetettebb képességeket is rendszerezhetnek. Az alábbi képernyőképen egy modulokat használó eszközsablon látható. A környezeti érzékelő eszköz egy úgynevezett SimulatedTemperatureSensor modullal és egy öröklött felülettel rendelkezik management:

Eszközösszetevő lekérése

Az összetevők egy úgynevezett temperature-controller-01eszközről való lekéréséhez használja a következő kérést:

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

A kérésre adott válasz az alábbi példához hasonlóan néz ki. A value tömb az egyes eszközösszetevők részleteit tartalmazza:

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

Eszközmodul lekérése

A következő kéréssel lekérheti a csatlakoztatott IoT Edge-eszközön environmental-sensor-01futó modulok listáját:

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

A kérésre adott válasz az alábbi példához hasonlóan néz ki. A modulok tömbje csak az IoT Edge-eszközön futó egyéni modulokat tartalmazza, a beépített $edgeAgent és $edgeHub a modulokat nem:

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

A következő kéréssel lekérheti az összetevők listáját a következő nevű SimulatedTemperatureSensormodulban:

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

Telemetriai adatok olvasása

Az alábbi kéréssel lekérheti az utolsó ismert telemetriai értéket egy olyan eszközről, amely nem használ összetevőket. Ebben a példában az eszköz neve thermostat-01 és a telemetria neve temperature:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Az alábbi kéréssel lekérheti az utolsó ismert telemetriai értéket egy olyan eszközről, amely összetevőket használ. Ebben a példában az eszköz neve temperature-controller-01, az összetevő neve thermostat2, a telemetria pedig a következő temperature:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Ha az eszköz IoT Edge-eszköz, az alábbi kéréssel kérje le az utolsó ismert telemetriai értéket egy modulból. Ez a példa egy olyan eszközt használ, amelynek a neve environmental-sensor-01 egy modul, SimulatedTemperatureSensor és a telemetria neve ambient. A ambient telemetriai típus hőmérséklet- és páratartalomértékekkel rendelkezik:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Tipp.

A modul egyik összetevőjének telemetriai adatainak eléréséhez használja /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}a következőt: .

Olvasási tulajdonságok

A következő kéréssel lekérheti a tulajdonságértékeket egy olyan eszközről, amely nem használ összetevőket. Ebben a példában az eszköz neve thermostat-01:

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

A kérésre adott válasz az alábbi példához hasonlóan néz ki. Azt mutatja, hogy az eszköz egyetlen tulajdonságértéket jelent:

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

A következő kéréssel lekérheti a tulajdonságértékeket az összes összetevőből. Ebben a példában az eszköz neve temperature-controller-01:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

A következő kéréssel egy tulajdonságértéket kérhet le egy adott összetevőtől. Ebben a példában az eszköz neve temperature-controller-01 és az összetevő neve thermostat2:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Ha az eszköz IoT Edge-eszköz, a következő kéréssel kérheti le a tulajdonságértékeket egy modulból. Ez a példa a következő nevű modullal SimulatedTemperatureSensorhívott environmental-sensor-01 eszközt használja:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Tipp.

Ha egy modul egyik összetevőjének tulajdonságaihoz szeretne hozzáférni, használja /devices/{deviceId}/modules/{moduleName}/components/{componentName}/propertiesa következőt: .

Írási tulajdonságok

Néhány tulajdonság írható. A példa termosztátmodellben a targetTemperature tulajdonság írható tulajdonság.

A következő kéréssel egyéni tulajdonságértéket írhat olyan eszközre, amely nem használ összetevőket. Ebben a példában az eszköz neve thermostat-01:

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

A kérelem törzse a következő példához hasonlóan néz ki:

{
  "targetTemperature": 65.5
}

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Tipp.

Az eszköz összes tulajdonságának frissítéséhez használja ahelyettPATCH, hogy PUT a .

A következő kéréssel egyéni tulajdonságértéket írhat egy olyan eszközre, amely összetevőket használ. Ebben a példában az eszköz neve temperature-controller-01 és az összetevő neve thermostat2:

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

A kérelem törzse a következő példához hasonlóan néz ki:

{
  "targetTemperature": 65.5
}

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Tipp.

Az összetevők összes tulajdonságának frissítéséhez használja ahelyettPATCH, hogy PUT a .

Ha az eszköz egy IoT Edge-eszköz, a következő kéréssel írjon be egy egyéni tulajdonságértéket egy modulba. Ez a példa egy úgynevezett environmental-sensor-01eszközt, egy úgynevezett SimulatedTemperatureSensormodult és egy következő nevű SendIntervaltulajdonságot használ:

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

A kérelem törzse a következő példához hasonlóan néz ki:

{
  "SendInterval": 20
}

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Tipp.

A modul összes tulajdonságának frissítéséhez használja ahelyettPATCH, hogy PUT a .

Modul tulajdonságainak frissítése

Ha IoT Edge-eszközt használ, a következő kéréssel kérheti le a tulajdonságértékeket egy modulból:

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

Ha IoT Edge-eszközt használ, a következő kéréssel kérheti le a tulajdonságértékeket egy modul egyik összetevőjében:

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

Hívási parancsok

A REST API-val meghívhatja az eszközparancsokat, és lekérheti a parancselőzményeket.

Az alábbi kéréssel meghívhat egy olyan parancsot az eszközön, amely nem használ összetevőket. Ebben a példában az eszköz neve thermostat-01 és a parancs neve getMaxMinReport:

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

A kérelem törzse a következő példához hasonlóan néz ki:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

A parancs előzményeinek megtekintéséhez használja a következő kérést:

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

A kérésre adott válasz a következő példához hasonlóan néz ki:

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

Az alábbi kéréssel meghívhat egy parancsot az összetevőket használó eszközön. Ebben a példában az eszköz neve temperature-controller-01, az összetevő neve thermostat2, a parancs pedig getMaxMinReporta következő:

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

A kérelem hasznos adatainak és válaszainak formátuma megegyezik az összetevőket nem használó eszközök formátumával.

A parancs előzményeinek megtekintéséhez használja a következő kérést:

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

Tipp.

Ha parancsokat szeretne meghívni egy modul egyik összetevőjében, használja /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}a következőt: .

Következő lépések

Most, hogy megtanulta, hogyan vezérelheti az eszközöket a REST API-val, a következő javasolt lépés az IoT Central REST API használata a feladatok létrehozásához és kezeléséhez.

Megosztás a következőn keresztül:

Az IoT Central REST API használata eszközök vezérlésére

Összetevők és modulok

Eszközösszetevő lekérése

Eszközmodul lekérése

Telemetriai adatok olvasása

Olvasási tulajdonságok

Írási tulajdonságok

Modul tulajdonságainak frissítése

Hívási parancsok

Következő lépések

Visszajelzés

További források