كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإنشاء الوظائف وإدارتها

مقالة
06/14/2023

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

سرد المهام وعرض تفاصيل المهمة في التطبيق الخاص بك.
إنشاء وظائف في التطبيق الخاص بك.
إيقاف المهام واستئنافها وإعادة تشغيلها في التطبيق الخاص بك.
جدولة المهام وعرض تفاصيل المهمة المجدولة في التطبيق الخاص بك.

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

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

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

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

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

تلميح

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

حمولات الوظائف

تتضمن العديد من واجهات برمجة التطبيقات الموضحة في هذه المقالة تعريفا يشبه مقتطف JSON التالي:

{
  "id": "job-014",
  "displayName": "Set target temperature",
  "description": "Set target temperature for all thermostat devices",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "56"
    }
  ],
  "status": "complete"
}

يصف الجدول التالي الحقول في مقتطف JSON السابق:

الحقل	‏‏الوصف
`id`	معرف فريد للوظيفة في التطبيق الخاص بك.
`displayName`	اسم العرض للوظيفة في التطبيق الخاص بك.
`description`	وصف الوظيفة.
`group`	معرف مجموعة الأجهزة التي تنطبق عليها المهمة. استخدم واجهة `deviceGroups` برمجة تطبيقات REST للمعاينة للحصول على قائمة بمجموعات الأجهزة في التطبيق الخاص بك.
`status`	حالة الوظيفة. واحد من `complete`، `cancelled`، `failed`، `pending`، `running`، `stopped`.
`batch`	إذا كان موجودا، يحدد هذا القسم كيفية تجميع الأجهزة في الوظيفة.
`batch/type`	حجم كل دفعة هو إما من `percentage` إجمالي الأجهزة في المجموعة أو من `number` الأجهزة.
`batch/value`	إما النسبة المئوية للأجهزة أو عدد الأجهزة في كل دفعة.
`cancellationThreshold`	إذا كان موجودا، يحدد هذا القسم حد الإلغاء للوظيفة.
`cancellationThreshold/batch`	`true` أو `false`. إذا كان صحيحا، يتم تعيين حد الإلغاء لكل دفعة. إذا ، `false`فإن حد الإلغاء ينطبق على الوظيفة بأكملها.
`cancellationThreshold/type`	حد الإلغاء للوظيفة هو إما `percentage` أو من `number` الأجهزة.
`cancellationThreshold/value`	إما النسبة المئوية للأجهزة أو عدد الأجهزة التي تحدد حد الإلغاء.
`data`	صفيف من العمليات التي تقوم بها الوظيفة.
`data/type`	واحد من `PropertyJobData`أو `CommandJobDataCloudPropertyJobData`أو أو `DeviceTemplateMigrationJobData`. يتضمن `DeviceManifestMigrationJobData`إصدار المعاينة لواجهة برمجة التطبيقات .
`data/target`	معرف النموذج للأجهزة المستهدفة.
`data/path`	اسم الخاصية أو الأمر أو خاصية السحابة.
`data/value`	قيمة الخاصية المراد تعيينها أو معلمة الأمر لإرسالها.

الحصول على معلومات الوظيفة

استخدم الطلب التالي لاسترداد قائمة المهام في التطبيق الخاص بك:

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

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

{
  "value": [
    {
      "id": "job-006",
      "displayName": "Set customer name",
      "description": "Set the customer name cloud property",
      "group": "4fcbec3b-5ee8-4324-855d-0f03b56bcf7f",
      "data": [
        {
          "type": "CloudPropertyJobData",
          "target": "dtmi:modelDefinition:bojo9tfju:yfvu5gv2vl",
          "path": "CustomerName",
          "value": "Contoso"
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-005",
      "displayName": "Set target temperature",
      "description": "Set target temperature device property",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "data": [
        {
          "type": "PropertyJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "targetTemperature",
          "value": 56
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-004",
      "displayName": "Run device report",
      "description": "Call command to run the device reports",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "batch": {
        "type": "percentage",
        "value": 25
      },
      "cancellationThreshold": {
        "type": "percentage",
        "value": 10,
        "batch": false
      },
      "data": [
        {
          "type": "CommandJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "getMaxMinReport",
          "value": "2021-06-15T05:00:00.000Z"
        }
      ],
      "status": "complete"
    }
  ]
}

استخدم الطلب التالي لاسترداد مهمة فردية حسب المعرف:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004?api-version=2022-07-31

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

{
  "id": "job-004",
  "displayName": "Run device report",
  "description": "Call command to run the device reports",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "CommandJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "getMaxMinReport",
      "value": "2021-06-15T05:00:00.000Z"
    }
  ],
  "status": "complete"
}

استخدم الطلب التالي لاسترداد تفاصيل الأجهزة في وظيفة:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004/devices?api-version=2022-07-31

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

{
  "value": [
    {
      "id": "therm-01",
      "status": "completed"
    },
    {
      "id": "therm-02",
      "status": "completed"
    },
    {
      "id": "therm-03",
      "status": "completed"
    },
    {
      "id": "therm-04",
      "status": "completed"
    }
  ]
}

قم بإنشاء وظيفة

استخدم الطلب التالي لإنشاء وظيفة:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006?api-version=2022-07-31

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

إذا لم يكن لديك بالفعل مجموعة أجهزة مناسبة، يمكنك إنشاء واحدة باستخدام استدعاء REST API. ينشئ المثال التالي مجموعة أجهزة مع group1 كمعرف المجموعة:

PUT https://{your app subdomain}/api/deviceGroups/group1?api-version=2022-07-31

عند إنشاء مجموعة أجهزة، يمكنك تحديد filter الذي يحدد الأجهزة المراد تضمينها في المجموعة. يحدد عامل التصفية قالب الجهاز وأي خصائص لمطابقتها. ينشئ المثال التالي مجموعة أجهزة تحتوي على جميع الأجهزة المقترنة بقالب الجهاز "dtmi:modelDefinition:dtdlv2" حيث تكون trueالخاصية provisioned .

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

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

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

يمكنك الآن استخدام id القيمة من الاستجابة لإنشاء مهمة جديدة.

{
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ]
}

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

{
  "id": "job-006",
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ],
  "status": "pending"
}

إيقاف المهام واستئنافها وإعادة تشغيلها

استخدم الطلب التالي لإيقاف مهمة قيد التشغيل:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/stop?api-version=2022-07-31

إذا نجح الطلب، فإنه يرجع استجابة 204 - No Content .

استخدم الطلب التالي لاستئناف مهمة متوقفة:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/resume?api-version=2022-07-31

إذا نجح الطلب، فإنه يرجع استجابة 204 - No Content .

استخدم الأمر التالي لإعادة تشغيل مهمة موجودة على أي أجهزة فاشلة:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/rerun/rerun-001?api-version=2022-07-31

إنشاء مهمة مجدولة

حمولة مهمة مجدولة مشابهة لوظيفة قياسية ولكنها تتضمن الحقول الإضافية التالية:

الحقل	‏‏الوصف
الجدول/البدء	تاريخ ووقت بدء المهمة بتنسيق ISO 8601
الجدول/التكرار	واحد من `daily`، ، `monthlyyearly \|`
الجدول/الانتهاء	حقل اختياري يحدد إما عدد مرات حدوث المهمة أو تاريخ انتهاء بتنسيق ISO 8601

PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

يوضح المثال التالي نص طلب يقوم بإنشاء مهمة مجدولة.

{
    "displayName": "New Scheduled Job",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    }
}

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

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

الحصول على وظيفة مجدولة

استخدم الطلب التالي للحصول على مهمة مجدولة:

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

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

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

سرد المهام المجدولة

استخدم الطلب التالي للحصول على قائمة بالمهام المجدولة:

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

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

{
    "value": [
        {
            "id": "scheduled-Job-001",
            "displayName": "New Scheduled Job",
            "description": "",
            "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
                    "path": "Company",
                    "value": "Contoso"
                }
            ],
            "schedule": {
                "start": "2022-10-24T22:29:01Z",
                "recurrence": "daily"
            },
            "enabled": false,
            "completed": false,
            "etag": "\"88003877-0000-0700-0000-631020670000\""
        },
        {
            "id": "46480dff-dc22-4542-924e-a5d45bf347aa",
            "displayName": "test",
            "description": "",
            "group": "cdd04344-bb55-425b-a55a-954d68383289",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:rigado:evxfmi0xim",
                    "path": "test",
                    "value": 2
                }
            ],
            "schedule": {
                "start": "2022-09-01T03:00:00.000Z"
            },
            "enabled": true,
            "completed": true,
            "etag": "\"88000f76-0000-0700-0000-631020310000\""
        }
    ]
}

تحديث مهمة مجدولة

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

PATCH https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

يوضح المثال التالي نص طلب يقوم بتحديث مهمة مجدولة.

{
  "schedule": {
    "start": "2022-10-24T22:29:01Z",
    "recurrence": "weekly"
  }
}

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

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "weekly"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

حذف مهمة مجدولة

استخدم الطلب التالي لحذف مهمة مجدولة

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

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

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

كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإنشاء الوظائف وإدارتها

حمولات الوظائف

الحصول على معلومات الوظيفة

قم بإنشاء وظيفة

إيقاف المهام واستئنافها وإعادة تشغيلها

إنشاء مهمة مجدولة

الحصول على وظيفة مجدولة

سرد المهام المجدولة

تحديث مهمة مجدولة

حذف مهمة مجدولة

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

الموارد الإضافية