如何使用 IoT Central REST API 來控制裝置

發行項
05/11/2024

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。您可以使用 REST API 來控制 IoT Central 應用程式中的裝置。 REST API 可讓您：

從裝置讀取上一個已知的遙測值。
從裝置讀取屬性值。
在裝置上設定可寫入的屬性。
在裝置上呼叫命令。

本文說明如何使用 /devices/{device_id} API 來控制個別裝置。您也可以使用作業來控制大量裝置。

裝置可以將其所支援的屬性、遙測和命令分組至「元件」和「模組」中。

每個 IoT Central REST API 呼叫都需要授權標頭。若要深入了解，請參閱如何驗證和授權 IoT Central REST API 呼叫。

如需 IoT Central REST API 的參考文件，請參閱 Azure IoT Central REST API 參考。

若要了解如何使用 IoT Central UI 控制裝置，請參閱

元件和模組

元件可讓您分組並重複使用裝置功能。如要深入了解元件和裝置型號，請參閱 IoT 隨插即用模型化指南。

並非所有裝置範本都使用元件。下列螢幕擷取畫面顯示簡單控溫器的裝置範本，其中所有功能皆於稱為根元件的單一介面中定義：

下列螢幕擷取畫面顯示使用元件的溫度控制器裝置範本。溫度控制器有兩個控溫器元件和一個裝置資訊元件：

在 IoT Central 中，模組是指在連線的 IoT Edge 裝置上執行的 IoT Edge 模組。模組可以有簡單的模型，例如不使用元件的控溫器。模組也可以使用元件來組織更複雜的一組功能。以下螢幕擷取畫面顯示使用模組的裝置範本範例。環境感應器裝置有稱為 SimulatedTemperatureSensor 的模組，以及稱為 management 的繼承介面：

取得裝置元件

使用下列要求，從名為 temperature-controller-01 的裝置擷取元件：

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

此要求的回應看起來會如同下列範例。 value 陣列包含每個裝置元件的詳細資料：

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

取得裝置模組

使用下列要求來擷取在連線的 IoT Edge 裝置上執行的模組清單，稱為 environmental-sensor-01：

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

此要求的回應看起來會如同下列範例。模組陣列只包含 IoT Edge 裝置上執行的自訂模組，而不是內建 $edgeAgent 和 $edgeHub 模組：

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

使用下列要求來擷取名為 SimulatedTemperatureSensor 的模組中的元件清單：

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

讀取遙測資料

使用下列要求，從不使用元件的裝置擷取最後一個已知的遙測值。在此範例中，裝置稱為 thermostat-01，而遙測稱為 temperature：

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

此要求的回應如下列範例所示：

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

使用下列要求，從使用元件的裝置擷取最後一個已知的遙測值。在此範例中，裝置稱為 temperature-controller-01，元件稱為 thermostat2，而遙測稱為 temperature：

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

此要求的回應如下列範例所示：

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

如果裝置是 IoT Edge 裝置，請使用下列要求從模組擷取最後一個已知的遙測值。此範例會使用名為 environmental-sensor-01 的裝置，並搭配名為 SimulatedTemperatureSensor 的模組和名為 ambient 的遙測。 ambient 遙測類型具有溫度和濕度值：

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

此要求的回應如下列範例所示：

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

提示

若要從模組中的元件存取遙測，請使用 /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}。

讀取屬性

使用下列要求，從不使用元件的裝置擷取最後屬性值。在此範例中，裝置稱為 thermostat-01：

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

此要求的回應看起來會如同下列範例。它會顯示裝置正在報告單一屬性值：

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

使用下列要求從所有元件擷取屬性值。在此範例中，裝置稱為 temperature-controller-01：

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

此要求的回應如下列範例所示：

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

使用下列要求從個別元件擷取屬性值。在此範例中，裝置稱為 temperature-controller-01，元件稱為 thermostat2：

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

此要求的回應如下列範例所示：

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

如果裝置是 IoT Edge 裝置，請使用下列要求從模組擷取屬性值。此範例使用名為 environmental-sensor-01 的裝置搭配名為 SimulatedTemperatureSensor 的模組：

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

此要求的回應如下列範例所示：

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

提示

若要從模組中的元件存取屬性，請使用 /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties。

寫入內容

有些屬性是可寫入的。在範例控溫器模型中，targetTemperature 屬性是可寫入的屬性。

使用下列要求，將個別屬性值寫入未使用元件的裝置。在此範例中，裝置稱為 thermostat-01：

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

要求本文看起來會像下列範例：

{
  "targetTemperature": 65.5
}

此要求的回應如下列範例所示：

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

提示

若要更新裝置上的所有屬性，請使用 PUT 而非 PATCH。

使用下列要求，將個別屬性值寫入使用元件的裝置。在此範例中，裝置稱為 temperature-controller-01，元件稱為 thermostat2：

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

要求本文看起來會像下列範例：

{
  "targetTemperature": 65.5
}

此要求的回應如下列範例所示：

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

提示

若要更新元件上的所有屬性，請使用 PUT 而非 PATCH。

如果裝置是 IoT Edge 裝置，請使用下列要求將個別屬性值寫入模組。此範例使用名為 environmental-sensor-01 的裝置、名為 SimulatedTemperatureSensor 的模組，以及名為 SendInterval 的屬性：

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

要求本文看起來會像下列範例：

{
  "SendInterval": 20
}

此要求的回應如下列範例所示：

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

提示

若要更新模組上的所有屬性，請使用 PUT 而非 PATCH。

更新模組屬性

如果您使用 IoT Edge 裝置，請使用下列要求從模組擷取屬性值：

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

如果您使用 IoT Edge 裝置，請使用下列要求從模組中的元件擷取屬性值：

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

呼叫命令

您可以使用 REST API 來呼叫裝置命令，並擷取裝置歷程記錄。

使用下列要求，在不使用元件的裝置上呼叫命令。在此範例中，裝置稱為 thermostat-01，命令稱為 getMaxMinReport：

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

要求本文看起來會像下列範例：

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

此要求的回應如下列範例所示：

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

若要檢視此命令的歷程記錄，請使用下列要求：

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

此要求的回應如下列範例所示：

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

使用下列要求，在使用元件的裝置上呼叫命令。在此範例中，裝置稱為 temperature-controller-01，元件稱為 thermostat2，而命令稱為 getMaxMinReport：

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

要求承載和回應的格式與不使用元件的裝置的格式相同。

若要檢視此命令的歷程記錄，請使用下列要求：

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

提示

若要在模組的元件中呼叫命令，請使用 /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}。

下一步

現在您已了解如何使用 REST API 控制裝置，建議的下一個步驟是了解如何使用 IoT Central REST API 來建立和管理作業。

共用方式為

如何使用 IoT Central REST API 來控制裝置

元件和模組

取得裝置元件

取得裝置模組

讀取遙測資料

讀取屬性

寫入內容

更新模組屬性

呼叫命令

下一步

意見反應

其他資源