كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإدارة بيانات التوزيع
يتيح لك بيان التوزيع تحديد الوحدات النمطية التي يجب أن يقوم وقت تشغيل IoT Edge بتنزيلها وتكوينها. يمكن لجهاز IoT Edge تنزيل بيان توزيع عند الاتصال أولا بتطبيق IoT Central الخاص بك. توضح هذه المقالة كيفية إدارة بيانات التوزيع المخزنة في تطبيق IoT Central باستخدام واجهة برمجة تطبيقات REST.
لمعرفة المزيد حول IoT Edge وIoT Central، راجع الاتصال أجهزة Azure IoT Edge إلى تطبيق Azure IoT Central.
يتطلب كل استدعاء لواجهة برمجة تطبيقات REST ل IoT Central عنوان تخويل. لمعرفة المزيد، راجع كيفية مصادقة وتخويل استدعاءات واجهة برمجة تطبيقات REST ل IoT Central.
للحصول على الوثائق المرجعية لواجهة برمجة تطبيقات REST ل IoT Central، راجع مرجع واجهة برمجة تطبيقات REST ل Azure IoT Central.
تلميح
يمكنك استخدام Postman لتجربة استدعاءات واجهة برمجة تطبيقات REST الموضحة في هذه المقالة. قم بتنزيل مجموعة IoT Central Postman واستوردها إلى Postman. في المجموعة، ستحتاج إلى تعيين متغيرات مثل المجال الفرعي للتطبيق والرمز المميز للمسؤول.
لمعرفة كيفية إدارة بيانات التوزيع باستخدام واجهة مستخدم IoT Central، راجع إدارة بيانات توزيع IoT Edge في تطبيق IoT Central.
بيان النشر REST API
تتيح لك واجهة برمجة التطبيقات الخاصة بـ IoT Central ما يلي:
- إضافة بيان توزيع إلى التطبيق الخاص بك
- تحديث بيان توزيع في التطبيق الخاص بك
- الحصول على قائمة ببيانات التوزيع في التطبيق
- الحصول على بيان توزيع حسب المعرف
- حذف بيان توزيع في التطبيق الخاص بك
إشعار
بيانات النشر REST API قيد المعاينة حاليا.
إضافة بيان توزيع
استخدم الطلب التالي لإنشاء بيان نشر جديد.
PUT https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
يوضح المثال التالي نص طلب يضيف بيان نشر يعرف ثلاث وحدات نمطية:
{
"id": "envsensorv1",
"displayName": "Environmental sensor deployment manifest",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.0",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.0",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
}
}
يحتوي نص الطلب على بعض الحقول المطلوبة:
id: معرف فريد لبيان النشر في تطبيق IoT Central.displayName: اسم لبيان النشر المعروض في واجهة المستخدم.data: بيان نشر IoT Edge.
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"id": "envsensorv1",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"0500f164-0000-1100-0000-637cf09c0000\""
}
الحصول على بيان توزيع
استخدم الطلب التالي لاسترداد تفاصيل بيان توزيع من التطبيق الخاص بك:
GET https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
يمكنك الحصول على deploymentManifestId القيم باستخدام واجهة برمجة تطبيقات بيانات نشر القائمة.
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"id": "envsensor",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"0500f663-0000-1100-0000-637cec590000\""
}
تحديث بيان توزيع
PATCH https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
يقوم نموذج نص الطلب التالي بتحديث إعداد الخاصية SendInterval المطلوبة للوحدة النمطية SimuatedTemperatureSetting :
{
"data": {
"modulesContent": {
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendInterval": 30
}
}
}
}
}
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"id": "envsensorv1",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.2",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 30
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"05003065-0000-1100-0000-637cf1b00000\""
}
حذف بيان نشر
استخدم الطلب التالي لحذف بيان توزيع:
DELETE https://{your app subdomain}/api/deploymentManifests/{deploymentManifestId}?api-version=2022-10-31-preview
سرد بيانات التوزيع
استخدم الطلب التالي لاسترداد قائمة بيانات التوزيع من التطبيق الخاص بك:
GET https://{your app subdomain}/api/deploymentManifests?api-version=2022-10-31-preview
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"value": [
{
"id": "envsensor",
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.1",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.1",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
},
"displayName": "Environmental sensor deployment manifest",
"etag": "\"0500f663-0000-1100-0000-637cec590000\""
},
{
// More deployment manifests
}
]
}
تعيين بيان نشر إلى جهاز
لاستخدام بيان توزيع مخزن بالفعل في تطبيق IoT Central الخاص بك، استخدم أولا Get a deployment manifest API لجلبه. استخدم الطلب التالي لتعيين بيان توزيع إلى جهاز IoT Edge في تطبيق IoT Central الخاص بك:
POST https://{your app subdomain}.azureiotcentral.com/api/devices/{your IoT Edge device ID}/applyDeploymentManifest?api-version=2022-10-31-preview
يعين نموذج نص الطلب التالي بيان النشر إلى جهاز IoT Edge:
{
"data": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.0",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25",
"loggingOptions": "",
"registryCredentials": {}
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-agent:1.4",
"createOptions": "{}"
}
},
"edgeHub": {
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-hub:1.4",
"createOptions": "{}"
}
}
},
"modules": {
"SimulatedTemperatureSensor": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
"createOptions": "{}"
}
}
}
}
},
"$edgeHub": {
"properties.desired": {
"schemaVersion": "1.0",
"routes": {
"route": "FROM /* INTO $upstream"
},
"storeAndForwardConfiguration": {
"timeToLiveSecs": 7200
}
}
},
"SimulatedTemperatureSensor": {
"properties.desired": {
"SendData": true,
"SendInterval": 10
}
}
}
}
}
الخطوات التالية
الآن بعد أن تعلمت كيفية إدارة بيانات النشر باستخدام واجهة برمجة تطبيقات REST، فإن الخطوة التالية المقترحة هي معرفة كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإدارة الأجهزة.