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

  • مقالة
  • قراءة خلال 7 دقائق

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

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

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

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

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

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

تلميح

تتضمن واجهة برمجة تطبيقات المعاينة دعما لميزة المؤسسات الجديدة.

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

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

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

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=1.0

تبدو الاستجابة لهذا الطلب مثل المثال التالي. يحتوي 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=1.0

تبدو الاستجابة لهذا الطلب مثل المثال التالي. تتضمن مجموعة الوحدات النمطية فقط وحدات مخصصة تعمل على جهاز 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=1.0

قراءة القياس عن بعد

استخدم الطلب التالي لاسترداد آخر قيمة معروفة للقياس عن بعد من جهاز لا يستخدم المكونات. في هذا المثال ، يتم استدعاء thermostat-01 الجهاز ويسمى temperatureالقياس عن بعد:

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

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

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

استخدم الطلب التالي لاسترداد آخر قيمة معروفة للقياس عن بعد من جهاز يستخدم المكونات. في هذا المثال ، يسمى temperature-controller-01الجهاز ، ويسمى المكون ، ويسمى thermostat2temperatureالقياس عن بعد:

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

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

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

إذا كان الجهاز عبارة عن جهاز IoT Edge، فاستخدم الطلب التالي لاسترداد آخر قيمة معروفة للقياس عن بعد من وحدة نمطية. يستخدم هذا المثال جهازا يسمى مع وحدة نمطية تسمى SimulatedTemperatureSensor والقياس عن بعد يسمى ambientenvironmental-sensor-01 . يحتوي نوع القياس ambient عن بعد على قيم درجة الحرارة والرطوبة:

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

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "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=1.0

تبدو الاستجابة لهذا الطلب مثل المثال التالي. يظهر أن الجهاز يبلغ عن قيمة موقع واحد:

{
  "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=1.0

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "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=1.0

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "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=1.0

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "$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=1.0

يبدو نص الطلب مثل المثال التالي:

{
  "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=1.0

يبدو نص الطلب مثل المثال التالي:

{
  "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=1.0

يبدو نص الطلب مثل المثال التالي:

{
  "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=1.0

إذا كنت تستخدم جهاز IoT Edge، فاستخدم الطلب التالي لاسترداد قيم الخصائص من مكون في وحدة نمطية:

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

أوامر الاتصال

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

استخدم الطلب التالي للاتصال بأمر على جهاز لا يستخدم المكونات. في هذا المثال ، يتم استدعاء thermostat-01 الجهاز ويسمى getMaxMinReportالأمر :

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

يبدو نص الطلب مثل المثال التالي:

{
  "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=1.0

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "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الجهاز ، ويسمى المكون ، ويسمى thermostat2getMaxMinReportالأمر:

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

تنسيقات حمولة الطلب والاستجابة هي نفسها بالنسبة للجهاز الذي لا يستخدم المكونات.

لعرض محفوظات هذا الأمر، استخدم الطلب التالي:

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

تلميح

لاستدعاء الأوامر في مكون في وحدة نمطية، استخدم /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

الخطوات التالية

الآن بعد أن تعلمت كيفية التحكم في الأجهزة باستخدام واجهة برمجة تطبيقات REST ، فإن الخطوة التالية المقترحة هي معرفة كيفية استخدام واجهة برمجة تطبيقات IoT Central REST لإنشاء الوظائف وإدارتها.