استخدام واجهة برمجة تطبيقات REST لإنشاء تطبيقات IoT Central وإدارتها
يمكنك استخدام واجهة برمجة تطبيقات REST لمستوى التحكم لإنشاء تطبيقات IoT Central وإدارتها. يمكنك أيضا استخدام واجهة برمجة تطبيقات REST من أجل:
- إضافة هوية مدارة إلى التطبيق الخاص بك.
- إدارة لوحات المعلومات في التطبيق الخاص بك
لاستخدام واجهة برمجة التطبيقات هذه، تحتاج إلى رمز حامل للمورد management.azure.com . للحصول على رمز مميز للحامل، يمكنك استخدام Azure CLI:
az account get-access-token --resource https://management.azure.com
لمعرفة كيفية إدارة تطبيق IoT Central باستخدام واجهة مستخدم IoT Central، راجع إنشاء تطبيق IoT Central.
سرد التطبيقات الخاصة بك
للحصول على قائمة بتطبيقات IoT Central في اشتراك:
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
للحصول على قائمة بتطبيقات IoT Central في مجموعة موارد:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
يمكنك استرداد تفاصيل تطبيق فردي:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
إنشاء تطبيق IoT Central
لإنشاء تطبيق IoT Central مع هوية مدارة معينة من قبل النظام:
PUT https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
تظهر الحمولة التالية تكوين التطبيق الجديد، بما في ذلك الهوية المدارة:
{
"location": "eastus",
"sku": {
"name": "ST2"
},
"properties": {
"displayName": "Contoso IoT Central App",
"subdomain": "my-iot-central-app",
"template": "iotc-pnp-preview@1.0.0"
},
"identity": {
"type": "SystemAssigned"
}
}
تعديل تطبيق IoT Central
يمكنك تعديل تطبيق IoT Central موجود. يوضح المثال التالي كيفية تغيير اسم العرض وتمكين الهوية المدارة المعينة من قبل النظام:
PATCH https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
استخدم الحمولة التالية لتغيير اسم العرض وتمكين الهوية المدارة المعينة من قبل النظام:
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
إشعار
يمكنك فقط إضافة هوية مدارة إلى تطبيق IoT Central الذي تم إنشاؤه في منطقة. يتم إنشاء جميع التطبيقات الجديدة في منطقة.
حذف تطبيق IoT Central
لحذف تطبيق IoT Central، استخدم:
DELETE https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
لوحات المعلومات
يمكنك إنشاء لوحات معلومات مقترنة بمؤسسة معينة. تكون لوحة معلومات المؤسسة مرئية فقط للمستخدمين الذين لديهم حق الوصول إلى المؤسسة التي ترتبط بها لوحة المعلومات. يمكن فقط للمستخدمين في دور لديه أذونات لوحة معلومات المؤسسة إنشاء لوحات معلومات المؤسسة وتحريرها وحذفها.
يمكن لجميع المستخدمين إنشاء لوحات معلومات شخصية، مرئية لأنفسهم فقط. يمكن للمستخدمين التبديل بين لوحات معلومات المؤسسة ولوحات المعلومات الشخصية.
إشعار
إنشاء لوحات معلومات شخصية باستخدام واجهة برمجة التطبيقات غير مدعوم حاليا.
لمعرفة كيفية إدارة لوحات المعلومات باستخدام واجهة مستخدم IoT Central، راجع كيفية إدارة لوحات المعلومات.
واجهة برمجة تطبيقات REST للوحات المعلومات
تتيح لك واجهة برمجة التطبيقات الخاصة بـ IoT Central ما يلي:
- إضافة لوحة معلومات إلى التطبيق الخاص بك
- تحديث لوحة معلومات في التطبيق الخاص بك
- الحصول على قائمة بلوحة المعلومات في التطبيق
- الحصول على لوحة معلومات حسب المعرف
- حذف لوحة معلومات في تطبيقك
إضافة لوحة معلومات
استخدم الطلب التالي لإنشاء لوحة معلومات.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId- معرف DTMI فريد للوحة المعلومات.
يحتوي نص الطلب على بعض الحقول المطلوبة:
@displayName: اسم العرض للوحة المعلومات.@favorite: هل لوحة المعلومات في قائمة المفضلة؟group: معرف مجموعة الأجهزة.Tile: تكوين يحدد كائن تجانب، بما في ذلك التخطيط واسم العرض والتكوين.
يحتوي التجانب على بعض الحقول المطلوبة:
| Name | الوصف |
|---|---|
displayName |
اسم العرض لللوحة |
height |
ارتفاع اللوحة |
width |
عرض الإطار المتجانب |
x |
الموضع الأفقي لللوحة |
y |
الموضع العمودي لللوحة |
تستخدم أبعاد وموقع الإطار المتجانب وحدات عدد صحيح. أصغر تجانب ممكن له ارتفاع وعرض واحد.
يمكنك تكوين كائن تجانب لعرض أنواع متعددة من البيانات. تتضمن هذه المقالة أمثلة على الإطارات المتجانبة التي تعرض المخططات الخطية وعلامة العلامات والقيمة الأخيرة المعروفة. لمعرفة المزيد حول أنواع التجانب المختلفة التي يمكنك إضافتها إلى لوحة المعلومات، راجع أنواع اللوحات.
مربع الرسم البياني الخطي
رسم قيمة واحدة أو أكثر من قيم بيانات تتبع الاستخدام المجمعة لجهاز واحد أو أكثر على مدى فترة زمنية. على سبيل المثال، يمكنك عرض مخطط خطي لرسم متوسط درجة الحرارة والضغط لجهاز واحد أو أكثر خلال الساعة الماضية.
يحتوي تجانب المخطط الخطي على التكوين التالي:
| Name | الوصف |
|---|---|
capabilities |
تحديد القيمة الإجمالية لبيانات تتبع الاستخدام المراد عرضها. |
devices |
قائمة الأجهزة المراد عرضها. |
format |
تكوين تنسيق المخطط مثل المحاور التي يجب استخدامها. |
group |
معرف مجموعة الأجهزة المراد عرضها. |
queryRange |
النطاق الزمني والدقة المراد عرضهما. |
type |
lineChart |
لوحة Markdown
تجانبات قابلة للنقر تعرض عنوانا ونص وصف منسقا في Markdown. يمكن أن يكون عنوان موقع ويب رابطا نسبيا إلى صفحة أخرى في التطبيق أو رابطا مطلقا إلى موقع خارجي. يحتوي تجانب markdown على التكوين التالي:
| Name | الوصف |
|---|---|
description |
سلسلة markdown لعرضها داخل الإطار المتجانب. |
href |
الارتباط الذي يجب زيارته عند تحديد الإطار المتجانب. |
image |
صورة مشفرة base64 لعرضها. |
type |
markdown |
تجانب القيمة الأخيرة المعروفة
عرض أحدث قيم بيانات تتبع الاستخدام لجهاز واحد أو أكثر. على سبيل المثال، يمكنك استخدام هذا التجانب لعرض أحدث قيم درجة الحرارة والضغط والرطوبة لأجهزة واحدة أو أكثر.
يحتوي تجانب آخر قيمة معروفة (LKV) على التكوين التالي:
| Name | الوصف |
|---|---|
capabilities |
تحديد بيانات تتبع الاستخدام المراد عرضها. |
devices |
قائمة الأجهزة المراد عرضها. |
format |
تكوين تنسيق لوحة LKV مثل حجم نص التفاف الكلمات. |
group |
معرف مجموعة الأجهزة المراد عرضها. |
showTrend |
إظهار الفرق بين آخر قيمة معروفة والقيمة السابقة. |
type |
lkv |
يوضح المثال التالي نص طلب يضيف لوحة معلومات جديدة مع مخطط خطي وعلامة تجانب وآخر قيم معروفة. الإطارات المتجانبة ل LKV والمخطط الخطي هي 2x2 تجانبات. لوحة markdown هي 1x1 لوحة. يتم ترتيب الإطارات المتجانبة في الصف العلوي من لوحة المعلومات:
{
"displayName": "My Dashboard ",
"tiles": [
{
"displayName": "LKV Temperature",
"configuration": {
"type": "lkv",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"format": {
"abbreviateValue": false,
"wordWrap": false,
"textSize": 14
}
},
"x": 0,
"y": 0,
"width": 2,
"height": 2
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Average temperature",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 3,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
إضافة تكوين حساب تخزين تحميل ملف
استخدم الطلب التالي لإنشاء تكوين حساب تخزين كائن ثنائي كبير الحجم لتحميل ملف في تطبيق IoT Central الخاص بك:
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
يحتوي نص الطلب على الحقول التالية:
account: اسم حساب التخزين حيث يتم تحميل الملف إليه.connectionString: سلسلة الاتصال للاتصال بحساب التخزين.container: اسم الحاوية داخل حساب التخزين. يستخدم المثال التالي الاسمfileuploads.etag: ETag لمنع التعارض مع التحميلات المتعددةsasTtl: معيار مدة ISO 8601، مقدار الوقت الذي يكون فيه طلب الجهاز لتحميل ملف صالحا قبل انتهاء صلاحيته.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H",
"state": "pending",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
الحصول على تكوين حساب تخزين تحميل الملف
استخدم الطلب التالي لاسترداد تفاصيل تكوين حساب تخزين كائن ثنائي كبير الحجم لتحميل ملف في تطبيق IoT Central الخاص بك:
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
تحديث تكوين حساب تخزين تحميل الملف
استخدم الطلب التالي لتحديث حساب تخزين blob تحميل ملف سلسلة الاتصال في تطبيق IoT Central الخاص بك:
PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
{
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"sasTtl": "PT1H",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
إزالة تكوين حساب تخزين تحميل الملف
استخدم الطلب التالي لحذف تكوين حساب تخزين:
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
الحصول على لوحة معلومات
استخدم الطلب التالي لاسترداد تفاصيل لوحة المعلومات باستخدام معرف لوحة المعلومات.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
تحديث لوحة معلومات
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
يوضح المثال التالي نص طلب يقوم بتحديث اسم العرض للوحة المعلومات ويضيف لوحة المعلومات إلى قائمة المفضلة:
{
"displayName": "New Dashboard Name",
"favorite": true
}
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "New Dashboard Name",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 5,
"height": 5
}
],
"favorite": true
}
القيام بحذف لوحة المعلومات
استخدم الطلب التالي لحذف لوحة معلومات باستخدام معرف لوحة المعلومات:
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
سرد لوحات المعلومات
استخدم الطلب التالي لاسترداد قائمة لوحات المعلومات من التطبيق الخاص بك:
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"value": [
{
"id": "dtmi:kkfvwa2xi:p7pyt5x3o",
"displayName": "Dashboard",
"personal": false,
"tiles": [
{
"displayName": "Device templates",
"configuration": {
"type": "markdown",
"description": "Get started by adding your first device.",
"href": "/device-templates/new/devicetemplates",
"image": "f5ba1b00-1d24-4781-869b-6f954df48736"
},
"x": 1,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Quick start demo",
"configuration": {
"type": "markdown",
"description": "Learn how to use Azure IoT Central in minutes.",
"href": "https://aka.ms/iotcentral-pnp-video",
"image": "9eb01d71-491a-44e5-8fac-7af3bc9f9acd"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Tutorials",
"configuration": {
"type": "markdown",
"description": "Step-by-step articles teach you how to create apps and devices.",
"href": "https://aka.ms/iotcentral-pnp-tutorials",
"image": "7d9fc12c-d46e-41c6-885f-0a67c619366e"
},
"x": 3,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 4,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "IoT Central Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": ""
},
"x": 0,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Contoso Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": "c9ac5af4-f38e-4cd3-886a-e0cb107f391c"
},
"x": 0,
"y": 1,
"width": 5,
"height": 3
},
{
"displayName": "Available Memory",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
]
}
الملاحظات
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجع https://aka.ms/ContentUserFeedback.
إرسال الملاحظات وعرضها المتعلقة بـ