كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central للتحكم في الأجهزة

  • مقالة

تتيح لك واجهة برمجة تطبيقات REST في IoT Central تطوير تطبيقات العميل التي تتكامل مع تطبيقات IoT Central. يمكنك استخدام واجهة برمجة تطبيقات REST للتحكم في الأجهزة في تطبيق IoT Central. تتيح لك واجهة برمجة تطبيقات REST ما يلي:

  • اقرأ آخر قيمة معروفة لبيانات تتبع الاستخدام من جهاز.
  • قراءة قيم الخصائص من جهاز.
  • تعيين خصائص قابلة للكتابة على جهاز.
  • أوامر الاتصال على جهاز.

توضح هذه المقالة كيفية استخدام واجهة برمجة التطبيقات للتحكم في /devices/{device_id} الأجهزة الفردية. يمكنك أيضا استخدام المهام للتحكم في الأجهزة بشكل مجمع.

يمكن للجهاز تجميع الخصائص وبيانات تتبع الاستخدام والأوامر التي يدعمها في المكونات والوحدات النمطية.

يتطلب كل استدعاء لواجهة برمجة تطبيقات REST ل IoT Central عنوان تخويل. لمعرفة المزيد، راجع كيفية مصادقة وتخويل استدعاءات واجهة برمجة تطبيقات REST ل IoT Central.

للحصول على الوثائق المرجعية لواجهة برمجة تطبيقات REST ل IoT Central، راجع مرجع واجهة برمجة تطبيقات REST ل Azure IoT Central.

تلميح

يمكنك استخدام Postman لتجربة استدعاءات واجهة برمجة تطبيقات REST الموضحة في هذه المقالة. قم بتنزيل مجموعة IoT Central Postman واستوردها إلى Postman. في المجموعة، ستحتاج إلى تعيين متغيرات مثل المجال الفرعي للتطبيق والرمز المميز للمسؤول.

لمعرفة كيفية التحكم في الأجهزة باستخدام واجهة مستخدم IoT Central، راجع

المكونات والوحدات النمطية

تتيح لك المكونات تجميع قدرات الجهاز وإعادة استخدامها. لمعرفة المزيد حول المكونات ونماذج الأجهزة، راجع دليل نمذجة أجهزة التوصيل و التشغيل IoT.

لا تستخدم جميع قوالب الأجهزة المكونات. تظهر لقطة الشاشة التالية قالب الجهاز لثرموستات بسيط حيث يتم تعريف جميع الإمكانات في واجهة واحدة تسمى المكون الجذر:

Screenshot that shows a simple no component thermostat device.

تظهر لقطة الشاشة التالية قالب جهاز وحدة تحكم درجة الحرارة الذي يستخدم المكونات. تحتوي وحدة التحكم في درجة الحرارة على مكونين للترموستات ومكون معلومات الجهاز:

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

في IoT Central، تشير الوحدة النمطية إلى وحدة IoT Edge تعمل على جهاز IoT Edge متصل. يمكن أن تحتوي الوحدة النمطية على نموذج بسيط مثل منظم الحرارة الذي لا يستخدم المكونات. يمكن للوحدة النمطية أيضا استخدام المكونات لتنظيم مجموعة أكثر تعقيدا من القدرات. تظهر لقطة الشاشة التالية مثالا لقالب جهاز يستخدم الوحدات النمطية. يحتوي جهاز الاستشعار البيئي على وحدة نمطية تسمى SimulatedTemperatureSensor وواجهة موروثة تسمى management:

Screenshot that shows an environmental sensor device with a module.

الحصول على مكون جهاز

استخدم الطلب التالي لاسترداد المكونات من جهاز يسمى 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 لاستدعاء أوامر الجهاز واسترداد محفوظات الأوامر.

استخدم الطلب التالي لاستدعاء أمر على الجهاز الذي لا يستخدم المكونات. في هذا المثال، يتم استدعاء 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، فإن الخطوة التالية المقترحة هي معرفة كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإنشاء الوظائف وإدارتها.