Sdílet prostřednictvím

Řízení zařízení s využitím rozhraní IoT Central REST API

  • Článek

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. Rozhraní REST API můžete použít k řízení zařízení v aplikaci IoT Central. Rozhraní REST API umožňuje:

  • Přečtěte si poslední známou hodnotu telemetrie ze zařízení.
  • Čtení hodnot vlastností ze zařízení
  • Nastavte zapisovatelné vlastnosti na zařízení.
  • Volání příkazů na zařízení

Tento článek popisuje, jak používat /devices/{device_id} rozhraní API k řízení jednotlivých zařízení. Úlohy můžete také použít k hromadnému řízení zařízení.

Zařízení může seskupit vlastnosti, telemetrii a příkazy, které podporuje, do komponent a modulů.

Každé volání rozhraní REST API služby IoT Central vyžaduje autorizační hlavičku. Další informace najdete v tématu Ověřování a autorizace volání rozhraní REST API služby IoT Central.

Referenční dokumentaci k rozhraní IoT Central REST API najdete v referenčních informacích k rozhraní REST API služby Azure IoT Central.

Tip

Pomocí nástroje Postman můžete vyzkoušet volání rozhraní REST API popsaná v tomto článku. Stáhněte si kolekci IoT Central Postman a naimportujte ji do Postmanu. V kolekci budete muset nastavit proměnné, jako je subdoména vaší aplikace a token správce.

Informace o tom, jak ovládat zařízení pomocí uživatelského rozhraní IoT Central, najdete v tématu

Komponenty a moduly

Komponenty umožňují seskupovat a opakovaně používat funkce zařízení. Další informace o komponentách a modelech zařízení najdete v průvodci modelováním technologie Plug and Play IoT.

Ne všechny šablony zařízení používají komponenty. Následující snímek obrazovky ukazuje šablonu zařízení pro jednoduchý termostat , kde jsou všechny možnosti definované v jediném rozhraní nazývaném Kořenová komponenta:

Screenshot that shows a simple no component thermostat device.

Následující snímek obrazovky ukazuje šablonu zařízení kontroleru teploty, která používá komponenty. Kontroler teploty má dvě součásti termostatu a informační komponentu zařízení:

Screenshot that shows a temperature controller device with two thermostat components and a device information component.

V IoT Central se modul odkazuje na modul IoT Edge spuštěný na připojeném zařízení IoT Edge. Modul může mít jednoduchý model, jako je termostat, který nepoužívá součásti. Modul může také použít komponenty k uspořádání složitější sady funkcí. Následující snímek obrazovky ukazuje příklad šablony zařízení, která používá moduly. Zařízení senzoru prostředí má volané SimulatedTemperatureSensor modul a zděděné rozhraní s názvem management:

Screenshot that shows an environmental sensor device with a module.

Získání komponenty zařízení

Pomocí následujícího požadavku načtěte komponenty z volanou temperature-controller-01zařízení:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu. Pole value obsahuje podrobnosti o jednotlivých komponentách zařízení:

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

Získání modulu zařízení

Pomocí následujícího požadavku načtěte seznam modulů spuštěných na připojeném zařízení IoT Edge s názvem environmental-sensor-01:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu. Pole modulů zahrnuje jenom vlastní moduly spuštěné na zařízení IoT Edge, nikoli integrované $edgeAgent moduly a $edgeHub moduly:

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

Pomocí následujícího požadavku načtěte seznam komponent v modulu s názvem SimulatedTemperatureSensor:

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

Čtení telemetrie

Pomocí následujícího požadavku načtěte poslední známou hodnotu telemetrie ze zařízení, které nepoužívá komponenty. V tomto příkladu se zařízení volá thermostat-01 a volá temperaturese telemetrie:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pomocí následujícího požadavku načtěte poslední známou hodnotu telemetrie ze zařízení, které používá komponenty. V tomto příkladu se zařízení nazývá , komponenta je volána temperature-controller-01thermostat2a telemetrie se nazývá temperature:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pokud se jedná o zařízení IoT Edge, pomocí následujícího požadavku načtěte poslední známou hodnotu telemetrie z modulu. V tomto příkladu se používá zařízení volané environmental-sensor-01 s volaným SimulatedTemperatureSensor modulem a zavolána ambienttelemetrie . Typ ambient telemetrie má hodnoty teploty a vlhkosti:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Tip

Pokud chcete získat přístup k telemetrii ze komponenty v modulu, použijte /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Čtení vlastností

Pomocí následujícího požadavku načtěte hodnoty vlastností ze zařízení, které nepoužívá komponenty. V tomto příkladu se zařízení nazývá thermostat-01:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu. Zobrazuje, že zařízení hlásí jednu hodnotu vlastnosti:

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

Pomocí následujícího požadavku načtěte hodnoty vlastností ze všech komponent. V tomto příkladu se zařízení nazývá temperature-controller-01:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pomocí následujícího požadavku načtěte hodnotu vlastnosti z jednotlivé komponenty. V tomto příkladu se zařízení volá temperature-controller-01 a komponenta se nazývá thermostat2:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pokud se jedná o zařízení IoT Edge, pomocí následujícího požadavku načtěte hodnoty vlastností z modulu. V tomto příkladu se používá zařízení volané environmental-sensor-01 s názvem SimulatedTemperatureSensormodulu:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Tip

Chcete-li získat přístup k vlastnostem z komponenty v modulu, použijte /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Vlastnosti zápisu

Některé vlastnosti jsou zapisovatelné. V ukázkovém termostatovém modelu targetTemperature je vlastnost zapisovatelná vlastnost.

Následující požadavek použijte k zápisu hodnoty jednotlivých vlastností do zařízení, které nepoužívá součásti. V tomto příkladu se zařízení nazývá thermostat-01:

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

Text požadavku vypadá jako v následujícím příkladu:

{
  "targetTemperature": 65.5
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Tip

Chcete-li aktualizovat všechny vlastnosti na zařízení, použijte PUT místo PATCH.

Následující požadavek použijte k zápisu hodnoty jednotlivých vlastností do zařízení, které používá komponenty. V tomto příkladu se zařízení volá temperature-controller-01 a komponenta se nazývá thermostat2:

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

Text požadavku vypadá jako v následujícím příkladu:

{
  "targetTemperature": 65.5
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Tip

Chcete-li aktualizovat všechny vlastnosti komponenty, použijte PUT místo PATCH.

Pokud se jedná o zařízení IoT Edge, pomocí následujícího požadavku napište do modulu hodnotu jednotlivé vlastnosti. V tomto příkladu se používá zařízení s názvem environmental-sensor-01, modul volaný SimulatedTemperatureSensora vlastnost s názvem SendInterval:

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

Text požadavku vypadá jako v následujícím příkladu:

{
  "SendInterval": 20
}

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Tip

Chcete-li aktualizovat všechny vlastnosti modulu, použijte PUT místo PATCH.

Aktualizace vlastností modulu

Pokud používáte zařízení IoT Edge, pomocí následujícího požadavku načtěte hodnoty vlastností z modulu:

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

Pokud používáte zařízení IoT Edge, pomocí následujícího požadavku načtěte hodnoty vlastností z komponenty v modulu:

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

Volání příkazů

Rozhraní REST API můžete použít k volání příkazů zařízení a načtení historie příkazů.

Následující požadavek použijte k volání příkazu na zařízení, které nepoužívá komponenty. V tomto příkladu se zařízení volá thermostat-01 a příkaz se nazývá getMaxMinReport:

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

Text požadavku vypadá jako v následujícím příkladu:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pokud chcete zobrazit historii tohoto příkazu, použijte následující požadavek:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pomocí následujícího požadavku můžete volat příkaz na zařízení, které používá komponenty. V tomto příkladu se zařízení nazývá , komponenta je volána temperature-controller-01thermostat2a příkaz se nazývá getMaxMinReport:

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

Formáty datové části požadavku a odpovědi jsou stejné jako u zařízení, které nepoužívá komponenty.

Pokud chcete zobrazit historii tohoto příkazu, použijte následující požadavek:

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

Tip

Chcete-li volat příkazy v komponentě v modulu, použijte /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Další kroky

Teď, když jste se naučili řídit zařízení pomocí rozhraní REST API, je navrhovaným dalším krokem naučit se používat rozhraní IoT Central REST API k vytváření a správě úloh.