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

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

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

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

الأنواع الخاصة بالرمز المميز

للوصول إلى تطبيق IoT Central باستخدام واجهة برمجة تطبيقات REST، يمكنك استخدام:

• الرمز المميز لحامل Microsoft Entra. يقترن الرمز المميز للحامل بحساب مستخدم Microsoft Entra أو كيان الخدمة. يمنح الرمز المميز المتصل نفس الأذونات التي يمتلكها المستخدم أو كيان الخدمة في تطبيق IoT Central.
• الرمز المميز لواجهة برمجة تطبيقات IoT Central. يرتبط الرمز المميز لواجهة برمجة التطبيقات بدور في تطبيق IoT Central الخاص بك.

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

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

الحصول على رمز مميز للحامل

للحصول على رمز حامل لحساب مستخدم Microsoft Entra، استخدم أوامر Azure CLI التالية:

az login
az account get-access-token --resource https://apps.azureiotcentral.com

يبدو إخراج JSON من الأمر السابق مثل المثال التالي:

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

الرمز المميز للحامل صالح لمدة ساعة واحدة تقريبا، وبعد ذلك تحتاج إلى إنشاء رمز جديد.

للحصول على رمز حامل لكيان الخدمة، راجع مصادقة كيان الخدمة.

الحصول على رمز مميز لواجهة برمجة التطبيقات

للحصول على رمز مميز لواجهة برمجة التطبيقات، يمكنك استخدام واجهة مستخدم IoT Central أو استدعاء واجهة برمجة تطبيقات REST. يمكن مسؤول istrators المقترنة بالمؤسسة الجذر والمستخدمين المعينين للدور الصحيح إنشاء رموز API المميزة.

في واجهة مستخدم IoT Central:

1. انتقل إلى الرموز المميزة لواجهة برمجة تطبيقات الأذونات>.

2. حدد + جديد أو إنشاء رمز مميز لواجهة برمجة التطبيقات.

3. أدخل اسما للرمز المميز وحدد دورا ومؤسسة.

4. حدد إنشاء.

5. يعرض IoT Central الرمز المميز الذي يبدو مثل المثال التالي:

   SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

   هذه الشاشة هي المرة الوحيدة التي يمكنك فيها رؤية الرمز المميز لواجهة برمجة التطبيقات، إذا فقدته، فأنت بحاجة إلى إنشاء رمز جديد.

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

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

استخدام واجهة برمجة تطبيقات REST:

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

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

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

   {
     "value": [
       {
         "displayName": "Administrator",
         "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
       },
       {
         "displayName": "Operator",
         "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
       },
       {
         "displayName": "Builder",
         "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
       }
     ]
   }
   

2. استخدم واجهة برمجة تطبيقات REST لإنشاء رمز مميز لواجهة برمجة التطبيقات لدور ما. على سبيل المثال، لإنشاء رمز مميز لواجهة برمجة التطبيقات يسمى operator-token لدور عامل التشغيل:

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

   نص طلب:

   {
     "roles": [
       {
         "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
       }
     ]
   }
   

   تبدو الاستجابة للأمر السابق مثل JSON التالي:

   {
     "expiry": "2022-03-22T12:01:27.889Z",
     "id": "operator-token",
     "roles": [
       {
         "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
       }
     ],
     "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
   }
   

   هذه الاستجابة هي المرة الوحيدة التي يكون لديك فيها حق الوصول إلى الرمز المميز لواجهة برمجة التطبيقات، إذا فقدت ذلك، فأنت بحاجة إلى إنشاء رمز جديد.

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

استخدام الرمز المميز للحامل

لاستخدام رمز حامل عند إجراء استدعاء REST API، يبدو عنوان التخويل الخاص بك مثل المثال التالي:

Authorization: Bearer eyJ0eX...fNQ

استخدام رمز مميز لواجهة برمجة التطبيقات

لاستخدام رمز API المميز عند إجراء استدعاء REST API، يبدو عنوان التخويل الخاص بك مثل المثال التالي:

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889