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

مقالة
03/05/2024

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

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

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

تلميح

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

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

واجهة برمجة تطبيقات REST للأجهزة

تتيح لك واجهة برمجة التطبيقات الخاصة بـ IoT Central ما يلي:

إضافة جهاز إلى التطبيق الخاص بك
تحديث جهاز في التطبيق الخاص بك
الحصول على قائمة بالأجهزة الموجودة في التطبيق
الحصول على جهاز عن طريق المُعرِّف
الحصول على بيانات اعتماد الجهاز
حذف جهاز في التطبيق الخاص بك
تصفية قائمة الأجهزة في التطبيق

أضف جهاز

استخدم الطلب التالي لإنشاء جهاز جديد.

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

يوضح المثال التالي نص طلب يضيف جهازا لقالب جهاز. يمكنك الحصول على template التفاصيل من صفحة قوالب الجهاز في واجهة مستخدم تطبيق IoT Central.

{
  "displayName": "CheckoutThermostat",
  "template": "dtmi:contoso:Thermostat;1",
  "simulated": true,
  "enabled": true
}

يحتوي نص الطلب على بعض الحقول المطلوبة:

@displayName: اسم العرض للجهاز.
@enabled: يعلن أن هذا الكائن هو واجهة.
@etag: ETag يستخدم لمنع التعارض في تحديثات الجهاز.
simulated: هل تمت محاكاة الجهاز؟
template : تعريف قالب الجهاز للجهاز.

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

الحصول على جهاز

استخدم الطلب التالي لاسترداد تفاصيل جهاز من تطبيقك:

GET https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

إشعار

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

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

{
    "id": "5jcwskdwbm",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
    "displayName": "Thermostat - 5jcwskdwbm",
    "simulated": false,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

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

حالة جهاز واجهة المستخدم	ملاحظات	الحصول على واجهة برمجة تطبيقات REST
في انتظار الموافقة	تم تعطيل خيار الموافقة التلقائية في مجموعة اتصال الجهاز ولم تتم إضافة الجهاز من خلال واجهة المستخدم. يجب على المستخدم الموافقة يدويا على الجهاز من خلال واجهة المستخدم قبل أن يمكن استخدامه.	`Provisioned: false` `Enabled: false`
مسجلة	تمت الموافقة على جهاز إما تلقائيا أو يدويا.	`Provisioned: false` `Enabled: true`
توفير	تم توفير الجهاز ويمكنه الاتصال بتطبيق IoT Central الخاص بك.	`Provisioned: true` `Enabled: true`
محظور	لا يسمح للجهاز بالاتصال بتطبيق IoT Central. يمكنك حظر جهاز موجود في أي من الحالات الأخرى.	`Provisioned:` يعتمد على `Waiting for approval`/`Registered`/`Provisioned status` `Enabled: false`

الحصول على بيانات اعتماد الجهاز

استخدم الطلب التالي لاسترداد بيانات اعتماد جهاز من تطبيقك:

GET https://{your app subdomain}/api/devices/{deviceId}/credentials?api-version=2022-07-31

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

{
    "idScope": "0ne003E64EF",
    "symmetricKey": {
        "primaryKey": "XUQvxGl6+Q1R0NKN5kOTmLOWsSKiuqs5N9unrjYCH4k=",
        "secondaryKey": "Qp/MTGHjn5MUTw4NVGhRfG+P+L1zh1gtAhO/KH8kn5c="
    }
}

تحديث جهاز

PATCH https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

يغير نص طلب العينة enabled التالي الحقل إلى false:

{
  "enabled": false
}

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": false
}

حذف جهاز

استخدم الطلب التالي لحذف جهاز:

DELETE https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

سرد الأجهزة

استخدم الطلب التالي لاسترداد قائمة بالأجهزة من التطبيق الخاص بك:

GET https://{your app subdomain}/api/devices?api-version=2022-07-31

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

تعيين بيان توزيع

إذا كنت تضيف جهاز IoT Edge، يمكنك استخدام واجهة برمجة التطبيقات لتعيين بيان توزيع IoT Edge إلى الجهاز. لمعرفة المزيد، راجع تعيين بيان توزيع إلى جهاز.

استخدام عوامل تصفية ODATA

في إصدار المعاينة من واجهة برمجة التطبيقات (api-version=2022-10-31-preview)، يمكنك استخدام عوامل تصفية ODATA لتصفية وفرز النتائج التي تم إرجاعها بواسطة واجهة برمجة تطبيقات أجهزة القائمة.

الحد الأقصى لحجم الصفحات

استخدم maxpagesize لتعيين حجم النتيجة. الحد الأقصى لحجم النتيجة التي تم إرجاعها هو 100 والحجم الافتراضي هو 25.

استخدم الطلب التالي لاسترداد أفضل 10 أجهزة من التطبيق الخاص بك:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdgdwbm",
            "etag": "eyJoZWdhhZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "RS40 Occupancy Sensor - 5jcwskdgdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "urn:modelDefinition:aqlyr1ulfku:tz5rut2pvx",
            "enabled": true
        },
        ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
}

تتضمن الاستجابة قيمة nextLink التي يمكنك استخدامها لاسترداد الصفحة التالية من النتائج.

filter

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

عامل المقارنة	الرمز	مثال
يساوي	eq	`id eq 'device1' and scopes eq 'redmond'`
لا يساوي	ne	`Enabled ne true`
أصغر من أو يساوي	le	`id le '26whl7mure6'`
أقل من	الليتوانية	`id lt '26whl7mure6'`
أكبر من أو يساوي	جنرال الكتريك	`id ge '26whl7mure6'`
أكبر من	gt	`id gt '26whl7mure6'`

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

عامل تشغيل المنطق	الرمز	مثال
و	و	`id eq 'device1' and enabled eq true`
OR	أو	`id eq 'device1' or simulated eq false`

حاليا، يعمل عامل التصفية مع حقول الجهاز التالية:

Fieldname	النوع	الوصف
`id`	سلسلة	معرف الجهاز
`displayName`	سلسلة	اسم عرض الجهاز
`enabled`	boolean	حالة تمكين الجهاز
`provisioned`	boolean	حالة توفير الجهاز
`simulated`	boolean	حالة محاكاة الجهاز
`template`	سلسلة	معرف قالب الجهاز
`scopes`	سلسلة	معرف المؤسسة

تصفية الوظائف المدعومة:

حاليا، وظيفة التصفية المدعومة الوحيدة لقوائم الأجهزة هي الدالة contains :

filter=contains(displayName, 'device1')

يوضح المثال التالي كيفية استرداد جميع الأجهزة حيث يحتوي اسم العرض على السلسلة thermostat:

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "thermostat1",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "thermostat2",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Orderby

استخدم orderby لفرز النتائج. حاليا، يتيح لك orderby فقط الفرز على displayName. بشكل افتراضي، يتم فرز orderby بترتيب تصاعدي. استخدم desc للفرز بترتيب تنازلي، على سبيل المثال:

orderby=displayName
orderby=displayName desc

يوضح المثال التالي كيفية استرداد جميع قوالب الجهاز حيث يتم فرز النتيجة حسب displayName :

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName

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

{
    "value": [
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

يمكنك أيضا دمج اثنين أو أكثر من عوامل التصفية.

يوضح المثال التالي كيفية استرداد الأجهزة الثلاثة الأولى حيث يحتوي اسم العرض على السلسلة Thermostat.

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3

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

{
  "value": [
    {
      "id": "1fpwlahp0zp",
      "displayName": "Thermostat - 1fpwlahp0zp",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "1yg0zvpz9un",
      "displayName": "Thermostat - 1yg0zvpz9un",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "20cp9l96znn",
      "displayName": "Thermostat - 20cp9l96znn",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    }
  ],
  "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
}

مجموعات الأجهزة

يمكنك إنشاء مجموعات الأجهزة في تطبيق IoT Central لمراقبة البيانات المجمعة واستخدامها مع المهام وإدارة الوصول. يتم تعريف مجموعات الأجهزة بواسطة عامل تصفية يحدد الأجهزة لإضافتها إلى المجموعة. يمكنك إنشاء مجموعات الأجهزة في مدخل IoT Central أو باستخدام واجهة برمجة التطبيقات.

إضافة مجموعة أجهزة

استخدم الطلب التالي لإنشاء مجموعة أجهزة جديدة.

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

عند إنشاء مجموعة أجهزة، يمكنك تحديد filter الذي يحدد الأجهزة لإضافتها إلى المجموعة. 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",
  "organizations": [
    "seattle"
  ]
}

يحتوي نص الطلب على بعض الحقول المطلوبة:

@displayName: اسم العرض لمجموعة الأجهزة.
@filter: الاستعلام الذي يحدد الأجهزة التي يجب أن تكون في هذه المجموعة.
@etag: ETag يستخدم لمنع التعارض في تحديثات الجهاز.
description: ملخص قصير لمجموعة الأجهزة.

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

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

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

الحصول على مجموعة أجهزة

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

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

deviceGroupId - معرف فريد لمجموعة الأجهزة.

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

{
  "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
  "displayName": "DeviceGroupEntry1",
  "description": "This is a default device group containing all the devices for this particular Device Template.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

تحديث مجموعة أجهزة

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

يبدو نموذج نص الطلب مثل المثال التالي الذي يحدث displayName مجموعة الأجهزة:

{
  "displayName": "New group name"
}

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

{
  "id": "group1",
  "displayName": "New group name",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

حذف مجموعة أجهزة

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

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

سرد مجموعات الأجهزة

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

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

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

{
  "value": [
    {
      "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
      "displayName": "DeviceGroupEntry1",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
      "organizations": [
        "seattle"
      ]
    },
    {
      "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
      "displayName": "DeviceGroupEntry2",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
      "organizations": [
        "redmond"
      ]
    },
    {
      "id": "241ad72b-32aa-4216-aabe-91b240582c8d",
      "displayName": "DeviceGroupEntry3",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
    },
    {
      "id": "group4",
      "displayName": "DeviceGroupEntry4",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
    }
  ]
}

مجموعات التسجيل

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

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

عند إنشاء مجموعة تسجيل للأجهزة التي تستخدم شهادات X.509، تحتاج أولا إلى تحميل الشهادة الجذر أو الشهادة المتوسطة إلى تطبيق IoT Central.

إنشاء شهادات الجذر والجهاز

في هذا القسم، يمكنك إنشاء شهادات X.509 التي تحتاجها لتوصيل جهاز ب IoT Central.

تحذير

هذه الطريقة لإنشاء شهادات X.509 هي للاختبار فقط. بالنسبة لبيئة الإنتاج، يجب عليك استخدام آلية رسمية وآمنة لإنشاء الشهادات.

انتقل إلى البرنامج النصي لمنشئ الشهادة في Microsoft Azure IoT SDK Node.js قمت بتنزيله. قم بتثبيت الحزم المطلوبة:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
إنشاء شهادة جذر ثم اشتقاق شهادة جهاز عن طريق تشغيل البرنامج النصي:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
تلميح

يمكن أن يحتوي معرف الجهاز على أحرف وأرقام وحرف - .

تنتج هذه الأوامر الجذر التالي وشهادات الجهاز:

filename	المحتويات
mytestrootcert_cert.pem	الجزء العام من شهادة X.509 الجذر
mytestrootcert_key.pem	المفتاح الخاص لشهادة X.509 الجذر
mytestrootcert_fullchain.pem	سلسلة المفاتيح بأكملها لشهادة الجذر X.509.
mytestrootcert.pfx	ملف PFX لشهادة X.509 الجذر.
sampleDevice01_cert.pem	الجزء العام من شهادة X.509 للجهاز
sampleDevice01_key.pem	المفتاح الخاص لشهادة الجهاز X.509
sampleDevice01_fullchain.pem	سلسلة المفاتيح بأكملها لشهادة الجهاز X.509.
sampleDevice01.pfx	ملف PFX لشهادة X.509 للجهاز.

دون ملاحظة عن موقع هذه الملفات. ستحتاجها لاحقًا.

إنشاء الإصدار المشفرة base-64 من الشهادة الجذر

في المجلد الموجود على جهازك المحلي الذي يحتوي على الشهادات التي قمت بإنشائها، أنشئ ملفا يسمى convert.js وأضف محتوى JavaScript التالي:

const fs = require('fs')
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
console.log(fileContents);

قم بتشغيل الأمر التالي لإنشاء إصدار ترميز base-64 من الشهادة:

node convert.js mytestrootcert_cert.pem

دون ملاحظة عن الإصدار المشفرة base-64 من الشهادة. ستحتاجها لاحقًا.

إضافة مجموعة تسجيل X.509

استخدم الطلب التالي لإنشاء مجموعة تسجيل جديدة باستخدام myx509eg كمعرف:

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

يوضح المثال التالي نص طلب يضيف مجموعة تسجيل X.509 جديدة:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "x509"
  }
}

يحتوي نص الطلب على بعض الحقول المطلوبة:

@displayName: اسم العرض لمجموعة التسجيل.
@enabled: ما إذا كان يسمح للأجهزة التي تستخدم المجموعة بالاتصال ب IoT Central.
@type: نوع الأجهزة التي تتصل من خلال المجموعة، إما iot أو iotEdge.
attestation: آلية التصديق لمجموعة التسجيل، إما symmetricKey أو x509.

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

{
    "id": "myEnrollmentGroupId",
    "displayName": "My group",
    "enabled": true,
    "type": "iot",
    "attestation": {
        "type": "x509",
        "x509": {
            "signingCertificates": {}
        }
    },
    "etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
}

إضافة شهادة X.509 إلى مجموعة تسجيل

استخدم الطلب التالي لتعيين شهادة X.509 الأساسية لمجموعة التسجيل myx509eg:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

استخدم هذا الطلب لإضافة شهادة X.509 أساسية أو ثانوية إلى مجموعة التسجيل.

يوضح المثال التالي نص طلب يضيف شهادة X.509 إلى مجموعة تسجيل:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}

certificate - الإصدار base-64 من الشهادة التي قمت بتدوينها مسبقا.
verified - true إذا كنت تشهد بأن الشهادة صالحة، false إذا كنت بحاجة إلى إثبات صحة الشهادة.

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

{
  "verified": false,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

إنشاء رمز التحقق لشهادة X.509

استخدم الطلب التالي لإنشاء رمز تحقق لشهادة X.509 الأساسية أو الثانوية لمجموعة تسجيل.

إذا قمت بتعيين verified إلى false في الطلب السابق، فاستخدم الطلب التالي لإنشاء رمز تحقق لشهادة X.509 الأساسية في myx509eg مجموعة التسجيل:

POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31

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

{
  "verificationCode": "<certificate-verification-code>"
}

دون رمز التحقق، فأنت بحاجة إليه في الخطوة التالية.

إنشاء شهادة التحقق

استخدم الأمر التالي لإنشاء شهادة تحقق من رمز التحقق في الخطوة السابقة:

node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

قم بتشغيل الأمر التالي لإنشاء إصدار مشفر base-64 من الشهادة:

node convert.js verification_cert.pem

دون ملاحظة عن الإصدار المشفرة base-64 من الشهادة. ستحتاجها لاحقًا.

التحقق من شهادة X.509 لمجموعة تسجيل

استخدم الطلب التالي للتحقق من شهادة myx509eg X.509 الأساسية لمجموعة التسجيل عن طريق تزويد الشهادة برمز التحقق الموقع:

POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31

يوضح المثال التالي نص طلب يتحقق من شهادة X.509:

{
  "certificate": "base64-verification-certificate"
}

الحصول على شهادة X.509 لمجموعة تسجيل

استخدم الطلب التالي لاسترداد تفاصيل شهادة X.509 لمجموعة تسجيل من التطبيق الخاص بك:

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

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

{
  "verified": true,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

حذف شهادة X.509 من مجموعة تسجيل

استخدم الطلب التالي لحذف شهادة X.509 الأساسية من مجموعة تسجيل ذات المعرف myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

إضافة مجموعة تسجيل مفاتيح متماثلة

استخدم الطلب التالي لإنشاء مجموعة تسجيل جديدة باستخدام mysymmetric كمعرف:

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

يوضح المثال التالي نص طلب يضيف مجموعة تسجيل جديدة:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey"
  }
}

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

ينشئ IoT Central المفاتيح المتماثلة الأساسية والثانوية عند إجراء استدعاء واجهة برمجة التطبيقات هذا.

الحصول على مجموعة تسجيل

استخدم الطلب التالي لاسترداد تفاصيل مجموعة تسجيل باستخدام mysymmetric كمعرف:

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

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

تحديث مجموعة تسجيل

استخدم الطلب التالي لتحديث مجموعة تسجيل.

PATCH https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

يوضح المثال التالي نص طلب يقوم بتحديث اسم العرض لمجموعة تسجيل:

{
  "displayName": "My new group name",
}

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

{
  "id": "myEnrollmentGroupId",
  "displayName": "My new group name",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

حذف مجموعة تسجيل

استخدم الطلب التالي لحذف مجموعة تسجيل بالمعرف myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

سرد مجموعات التسجيل

استخدم الطلب التالي لاسترداد قائمة بمجموعات التسجيل من التطبيق الخاص بك:

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

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

{
    "value": [
        {
            "id": "myEnrollmentGroupId",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "symmetricKey",
                "symmetricKey": {
                    "primaryKey": "primaryKey",
                    "secondaryKey": "secondarykey"
                }
            },
            "etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
        },
        {
            "id": "enrollmentGroupId2",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "x509",
                "x509": {
                    "signingCertificates": {}
                }
            },
            "etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
        }
    ]
}

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

واجهة برمجة تطبيقات REST للأجهزة

أضف جهاز

الحصول على جهاز

الحصول على بيانات اعتماد الجهاز

تحديث جهاز

حذف جهاز

سرد الأجهزة

تعيين بيان توزيع

استخدام عوامل تصفية ODATA

الحد الأقصى لحجم الصفحات

filter

Orderby

مجموعات الأجهزة

إضافة مجموعة أجهزة

الحصول على مجموعة أجهزة

تحديث مجموعة أجهزة

حذف مجموعة أجهزة

سرد مجموعات الأجهزة

مجموعات التسجيل

أنشئ مجموعة تسجيل

إنشاء شهادات الجذر والجهاز

إنشاء الإصدار المشفرة base-64 من الشهادة الجذر

إضافة مجموعة تسجيل X.509

إضافة شهادة X.509 إلى مجموعة تسجيل

إنشاء رمز التحقق لشهادة X.509

إنشاء شهادة التحقق

التحقق من شهادة X.509 لمجموعة تسجيل

الحصول على شهادة X.509 لمجموعة تسجيل

حذف شهادة X.509 من مجموعة تسجيل

الحصول على مجموعة تسجيل

تحديث مجموعة تسجيل

حذف مجموعة تسجيل

سرد مجموعات التسجيل

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