Cihazları denetlemek için IoT Central REST API kullanma

  • Makale

IoT Central REST API,IoT Central uygulamalarıyla tümleşen istemci uygulamaları geliştirmenizi sağlar. IoT Central uygulamanızdaki cihazları denetlemek için REST API'yi kullanabilirsiniz. REST API şunları yapmanızı sağlar:

  • Bir cihazdan bilinen son telemetri değerini okuyun.
  • Bir cihazdan özellik değerlerini okuma.
  • Bir cihazda yazılabilir özellikleri ayarlayın.
  • Bir cihazdaki çağrı komutları.

Bu makalede, tek tek cihazları denetlemek için API'nin /devices/{device_id} nasıl kullanılacağı açıklanmaktadır. Cihazları toplu olarak denetlemek için işleri de kullanabilirsiniz.

Bir cihaz, desteklediği özellikleri, telemetriyi ve komutları bileşenler ve modüller halinde gruplandırabilir.

Her IoT Central REST API çağrısı bir yetkilendirme üst bilgisi gerektirir. Daha fazla bilgi edinmek için bkz . IoT Central REST API çağrılarının kimliğini doğrulama ve yetkilendirme.

IoT Central REST API'sinin başvuru belgeleri için bkz . Azure IoT Central REST API başvurusu.

İpucu

Postman'i kullanarak bu makalede açıklanan REST API çağrılarını deneyebilirsiniz. IoT Central Postman koleksiyonunu indirin ve Postman'a aktarın. Koleksiyonda, uygulamanızın alt etki alanı ve yönetici belirteci gibi değişkenleri ayarlamanız gerekir.

IoT Central kullanıcı arabirimini kullanarak cihazları denetlemeyi öğrenmek için bkz.

Bileşenler ve modüller

Bileşenler, cihaz özelliklerini gruplandırmanıza ve yeniden kullanmanıza olanak sağlar. Bileşenler ve cihaz modelleri hakkında daha fazla bilgi edinmek için IoT Tak Çalıştır modelleme kılavuzuna bakın.

Tüm cihaz şablonları bileşenleri kullanmaz. Aşağıdaki ekran görüntüsünde, tüm özelliklerin Kök bileşeni adlı tek bir arabirimde tanımlandığı basit bir termostat için cihaz şablonu gösterilmektedir:

Screenshot that shows a simple no component thermostat device.

Aşağıdaki ekran görüntüsünde bileşenleri kullanan bir sıcaklık denetleyicisi cihaz şablonu gösterilmektedir. Sıcaklık denetleyicisi iki termostat bileşenine ve bir cihaz bilgi bileşenine sahiptir:

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

IoT Central'da modül, bağlı bir IoT Edge cihazında çalışan bir IoT Edge modülüne başvurur. Modül, bileşenleri kullanmayan termostat gibi basit bir modele sahip olabilir. Modül, daha karmaşık bir özellik kümesi düzenlemek için bileşenleri de kullanabilir. Aşağıdaki ekran görüntüsünde modülleri kullanan bir cihaz şablonu örneği gösterilmektedir. Çevre algılayıcısı cihazı adlı SimulatedTemperatureSensor bir modüle ve adlı managementdevralınan bir arabirime sahiptir:

Screenshot that shows an environmental sensor device with a module.

Cihaz bileşeni alma

Adlı temperature-controller-01bir cihazdan bileşenleri almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer. Dizi, value her cihaz bileşeninin ayrıntılarını içerir:

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

Cihaz modülü alma

adlı environmental-sensor-01bağlı bir IoT Edge cihazında çalışan modüllerin listesini almak için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer. Modül dizisi yalnızca IoT Edge cihazında çalışan özel modülleri içerir, yerleşik $edgeAgent ve $edgeHub modülleri içermez:

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

adlı SimulatedTemperatureSensormodüldeki bileşenlerin listesini almak için aşağıdaki isteği kullanın:

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

Telemetriyi okuma

Bileşenleri kullanmayan bir cihazdan bilinen son telemetri değerini almak için aşağıdaki isteği kullanın. Bu örnekte cihaz çağrılır thermostat-01 ve telemetri olarak adlandırılır temperature:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Bileşenleri kullanan bir cihazdan bilinen son telemetri değerini almak için aşağıdaki isteği kullanın. Bu örnekte, cihaz olarak adlandırılır temperature-controller-01, bileşen olarak adlandırılır thermostat2ve telemetri olarak adlandırılır temperature:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Cihaz bir IoT Edge cihazıysa, bir modülden bilinen son telemetri değerini almak için aşağıdaki isteği kullanın. Bu örnekte adlı environmental-sensor-01 bir cihaz ve adlı SimulatedTemperatureSensor bir modül ve adlı ambienttelemetri kullanılır. ambient Telemetri türü sıcaklık ve nem değerlerine sahiptir:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

İpucu

Modüldeki bir bileşenden telemetriye erişmek için kullanın /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Okuma özellikleri

Bileşenleri kullanmayan bir cihazdan özellik değerlerini almak için aşağıdaki isteği kullanın. Bu örnekte, cihaz olarak adlandırılır thermostat-01:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer. Cihazın tek bir özellik değeri bildirmiş olduğunu gösterir:

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

Tüm bileşenlerden özellik değerlerini almak için aşağıdaki isteği kullanın. Bu örnekte, cihaz olarak adlandırılır temperature-controller-01:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Tek bir bileşenden özellik değeri almak için aşağıdaki isteği kullanın. Bu örnekte, cihaz çağrılır temperature-controller-01 ve bileşen olarak adlandırılır thermostat2:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Cihaz bir IoT Edge cihazıysa, modülden özellik değerlerini almak için aşağıdaki isteği kullanın. Bu örnekte adlı environmental-sensor-01 bir cihaz ve adlı SimulatedTemperatureSensorbir modül kullanılır:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

İpucu

Modüldeki bir bileşenden özelliklere erişmek için kullanın /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Yazma özellikleri

Bazı özellikler yazılabilir. Örnek termostat modelinde targetTemperature özelliği yazılabilir bir özelliktir.

Bileşenleri kullanmayan bir cihaza tek bir özellik değeri yazmak için aşağıdaki isteği kullanın. Bu örnekte, cihaz olarak adlandırılır thermostat-01:

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

İstek gövdesi aşağıdaki örneğe benzer:

{
  "targetTemperature": 65.5
}

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

İpucu

Bir cihazdaki tüm özellikleri güncelleştirmek için yerine PATCHkullanınPUT.

Bileşenleri kullanan bir cihaza tek bir özellik değeri yazmak için aşağıdaki isteği kullanın. Bu örnekte, cihaz çağrılır temperature-controller-01 ve bileşen olarak adlandırılır thermostat2:

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

İstek gövdesi aşağıdaki örneğe benzer:

{
  "targetTemperature": 65.5
}

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

İpucu

Bir bileşendeki tüm özellikleri güncelleştirmek için yerine PATCHkullanınPUT.

Cihaz bir IoT Edge cihazıysa, modüle tek bir özellik değeri yazmak için aşağıdaki isteği kullanın. Bu örnekte adlı environmental-sensor-01bir cihaz, adlı SimulatedTemperatureSensorbir modül ve adlı SendIntervalbir özellik kullanılır:

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

İstek gövdesi aşağıdaki örneğe benzer:

{
  "SendInterval": 20
}

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

İpucu

Modüldeki tüm özellikleri güncelleştirmek için yerine PATCHkullanınPUT.

Modül özelliklerini güncelleştirme

IoT Edge cihazı kullanıyorsanız bir modülden özellik değerlerini almak için aşağıdaki isteği kullanın:

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

IoT Edge cihazı kullanıyorsanız modüldeki bir bileşenden özellik değerlerini almak için aşağıdaki isteği kullanın:

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

Arama komutları

Cihaz komutlarını çağırmak ve komut geçmişini almak için REST API'yi kullanabilirsiniz.

Bileşen kullanmayan bir cihazda komut çağırmak için aşağıdaki isteği kullanın. Bu örnekte, cihaz çağrılır thermostat-01 ve komutu olarak adlandırılır getMaxMinReport:

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

İstek gövdesi aşağıdaki örneğe benzer:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Bu komutun geçmişini görüntülemek için aşağıdaki isteği kullanın:

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

Bu isteğin yanıtı aşağıdaki örneğe benzer:

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

Bileşenleri kullanan cihazda bir komut çağırmak için aşağıdaki isteği kullanın. Bu örnekte, cihaz olarak adlandırılır temperature-controller-01, bileşen olarak adlandırılır thermostat2ve komutu olarak adlandırılır getMaxMinReport:

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

İstek yükü ve yanıt biçimleri, bileşenleri kullanmayan bir cihazla aynıdır.

Bu komutun geçmişini görüntülemek için aşağıdaki isteği kullanın:

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

İpucu

Modüldeki bir bileşendeki komutları çağırmak için kullanın /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Sonraki adımlar

Rest API ile cihazları denetlemeyi öğrendiğinize göre, önerilen bir sonraki adım ioT Central REST API'sini kullanarak iş oluşturma ve yönetme hakkında bilgi edinmektir.