كيفية مصادقة وتخويل استدعاءات IoT Central REST API

مقالة
05/10/2022
قراءة خلال 3 دقائق

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

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

توضح هذه المقالة أنواع الرمز المميز الذي يمكنك استخدامه في عنوان التخويل وكيفية الحصول عليها.

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

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

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

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

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

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

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

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

هام

az login الأمر ضروري حتى إذا كنت تستخدم Cloud Shell.

يبدو إخراج 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. يمكن للمسؤولين المقترنين بالمؤسسة الجذر والمستخدمين المعينين للدور الصحيح إنشاء رموز API المميزة.

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

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

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

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

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

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

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

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

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

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

{
  "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"
    }
  ]
}

استخدم واجهة برمجة تطبيقات REST لإنشاء رمز مميز لواجهة برمجة التطبيقات لدور ما. على سبيل المثال، لإنشاء رمز مميز لواجهة برمجة التطبيقات يسمى operator-token لدور عامل التشغيل:
```
PUT https://{your app subdomain}.azureiotcentral.com/api/apiToken/operator-token?api-version=1.0
```
نص الطلب:
```
{
  "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، يبدو عنوان التخويل الخاص بك مثل المثال التالي:

Authorization: Bearer eyJ0eX...fNQ

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

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

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

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

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