كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإدارة الأجهزة
تتيح لك واجهة برمجة تطبيقات REST في IoT Central تطوير تطبيقات العميل التي تتكامل مع تطبيقات IoT Central. يمكنك استخدام واجهة برمجة تطبيقات REST لإدارة الأجهزة في تطبيق IoT Central.
يتطلب كل استدعاء لواجهة برمجة تطبيقات REST ل IoT Central عنوان تخويل. لمعرفة المزيد، راجع كيفية مصادقة وتخويل استدعاءات واجهة برمجة تطبيقات REST ل IoT Central.
للحصول على الوثائق المرجعية لواجهة برمجة تطبيقات REST ل IoT Central، راجع مرجع واجهة برمجة تطبيقات REST ل Azure IoT Central.
لمعرفة كيفية إدارة الأجهزة باستخدام واجهة مستخدم 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 فقط الفرز على 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
كمعرف:
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="
}
]
}