مشاركة عبر

فهم نهج التخصيص المخصصة باستخدام Azure IoT Hub Device Provisioning Service

تمنحك نهج التخصيص المخصصة مزيدا من التحكم في كيفية تعيين الأجهزة إلى مراكز IoT الخاصة بك. باستخدام نهج التخصيص المخصصة، يمكنك تحديد نهج التخصيص الخاصة بك عندما لا تفي النهج المضمنة التي توفرها خدمة توفير الأجهزة (DPS) بمتطلبات السيناريو الخاص بك.

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

يمكنك تنفيذ نهج تخصيص مخصص في خطاف ويب مستضاف في Azure Functions. يمكنك بعد ذلك تكوين خطاف الويب في واحد أو أكثر من التسجيلات الفردية ومجموعات التسجيل. عندما يسجل جهاز من خلال إدخال تسجيل تم تكوينه، يستدعي DPS خطاف الويب، الذي يعيد مركز IoT لتسجيل الجهاز واختياريا، الإعدادات المزدوجة الأولية للجهاز وأي معلومات يتم إرجاعها مباشرة إلى الجهاز.

نظرة عامة

تصف الخطوات التالية كيفية عمل نهج التخصيص المخصصة:

  1. مطور تخصيص مخصص يطور خطاف ويب ينفذ نهج التخصيص المقصود وينشره كدالة مشغل HTTP إلى Azure Functions. يأخذ خطاف الويب معلومات حول إدخال تسجيل DPS والجهاز ويعيد مركز IoT الذي يجب تسجيل الجهاز فيه، واختياريا، معلومات حول الحالة الأولية للجهاز.

  2. يقوم عامل تشغيل IoT بتكوين واحد أو أكثر من التسجيلات الفردية و/أو مجموعات التسجيل للتخصيص المخصص ويوفر تفاصيل الاتصال لخطاف ويب التخصيص المخصص في Azure Functions.

  3. عندما يسجل جهاز من خلال إدخال تسجيل تم تكوينه لخطاف ويب التخصيص المخصص، ترسل DPS طلب POST إلى خطاف الويب مع تعيين نص الطلب إلى كائن طلب AllocationRequest. يحتوي كائن AllocationRequest على معلومات حول الجهاز الذي يحاول توفيره ومجموعة التسجيل أو التسجيل الفردية التي يقوم بتوفيرها. يمكن أن تتضمن معلومات الجهاز حمولة مخصصة اختيارية تم إرسالها من الجهاز في طلب التسجيل الخاص به. لمزيد من المعلومات، راجع طلب نهج التخصيص المخصص.

  4. تقوم وظيفة Azure بتنفيذ وإرجاع كائن AllocationResponse عند النجاح. يحتوي كائن AllocationResponse على مركز IoT الذي يجب توفير الجهاز إليه، وحالة التوأم الأولي، وحمولة مخصصة اختيارية للعودة إلى الجهاز. لمزيد من المعلومات، راجع استجابة نهج التخصيص المخصص.

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

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

توفر الأقسام التالية المزيد من التفاصيل حول طلب التخصيص المخصص والاستجابة والحمولات المخصصة وتنفيذ النهج. لمزيد من المعلومات حول مثال كامل شامل لنهج تخصيص مخصص، راجع البرنامج التعليمي: استخدام نهج التخصيص المخصصة مع خدمة توفير الأجهزة (DPS).

إدارة مفاتيح الوظائف

تستخدم نهج التخصيص المخصصة مفاتيح الوظائف لمصادقة الاستدعاءات إلى Azure Functions حيث يتم تعيين مستوى التخويل إلى Function. يختلف سلوك إدارة المفاتيح استنادا إلى ما إذا كنت تقوم بتكوين نهج التخصيص المخصص من خلال مدخل Microsoft Azure أو برمجيا.

المفاتيح الوظيفية في المدخل

عند إنشاء تسجيل في مدخل Microsoft Azure وتحديد نهج تخصيص مخصص، يعالج المدخل تلقائيا استرداد مفتاح الدالة وتضمينه.

بعد تحديد الدالة لنهج التخصيص المخصص، يسترد المدخل مفتاح الدالة. هذه الخطوة غير مرئية للمستخدمين من خلال واجهة المدخل. بعد ذلك، يتم تخزين مفتاح الدالة كجزء من عنوان URL للإخطار على الويب المشفر المستخدم من قبل DPS لاستدعاء الدالة. لا يتم عرض المفتاح في المدخل.

يمكنك التحقق من تضمين المفتاح في عنوان URL لخطاف الويب عن طريق تشغيل أمر GET لاسترداد تفاصيل التسجيل. في تكوين التسجيل، يتم تضمين مفتاح الدالة في حقل webhookUrl .

المفاتيح الوظيفية مع واجهات برمجة التطبيقات

عند إنشاء تسجيل برمجيا باستخدام واجهة برمجة تطبيقات DPS، تحتاج إلى توفير المفتاح يدويا أثناء إنشاء التسجيل. إذا لم يتم توفير المفتاح، يفشل استدعاء Azure Functions في المصادقة.

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

لمزيد من المعلومات، راجع تخويل مفتاح الوصول.

طلب نهج التخصيص المخصص

يرسل DPS طلب POST إلى خطاف الويب الخاص بك على نقطة النهاية التالية: https://{your-function-app-name}.azurewebsites.net/api/{your-http-trigger}

نص الطلب هو كائن AllocationRequest :

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

يحتوي كائن DeviceRuntimeContext على الخصائص التالية:

الخاصية نوع ‏‏الوصف
registrationId سلسلة معرف التسجيل الذي يوفره الجهاز في وقت التشغيل. موجود دائما.
currentIotHubHostName سلسلة اسم مضيف مركز IoT الذي تم تعيين الجهاز له مسبقا (إن وجد). غير موجود إذا كان هذا تعيينا أوليا. يمكنك استخدام هذه الخاصية لتحديد ما إذا كان هذا تعيينا أوليا للجهاز أو ما إذا كان الجهاز قد تم تعيينه مسبقا.
معرف الجهاز الحالي سلسلة معرف الجهاز من التعيين السابق للجهاز (إن وجد). غير موجود إذا كان هذا تعيينا أوليا.
x509 X509DeviceAttestation للحصول على شهادة X.509، يحتوي على تفاصيل الشهادة.
مفتاح متماثل توصيل المفاتيح المتماثلة للحصول على إثبات المفتاح المتماثل، يحتوي على تفاصيل المفتاح الأساسي والثانوي.
TPM شهادة TPMشهادة للحصول على شهادة TPM، يحتوي على مفتاح المصادقة وتفاصيل مفتاح جذر التخزين.
حموله كائن يحتوي على خصائص محددة من قبل الجهاز في خاصية الحمولة أثناء التسجيل. تقديم إذا أرسل الجهاز حمولة مخصصة في طلب تسجيل DPS.

يظهر JSON التالي كائن AllocationRequest المرسل بواسطة DPS لجهاز مسجل من خلال مجموعة تسجيل مستندة إلى مفتاح متماثل.

{
   "enrollmentGroup":{
      "enrollmentGroupId":"contoso-custom-allocated-devices",
      "attestation":{
         "type":"symmetricKey"
      },
      "capabilities":{
         "iotEdge":false
      },
      "etag":"\"13003fea-0000-0300-0000-62d1d5e50000\"",
      "provisioningStatus":"enabled",
      "reprovisionPolicy":{
         "updateHubAssignment":true,
         "migrateDeviceData":true
      },
      "createdDateTimeUtc":"2022-07-05T21:27:16.8123235Z",
      "lastUpdatedDateTimeUtc":"2022-07-15T21:02:29.5922255Z",
      "allocationPolicy":"custom",
      "iotHubs":[
         "custom-allocation-toasters-hub.azure-devices.net",
         "custom-allocation-heatpumps-hub.azure-devices.net"
      ],
      "customAllocationDefinition":{
         "webhookUrl":"https://custom-allocation-function-app-3.azurewebsites.net/api/HttpTrigger1?****",
         "apiVersion":"2021-10-01"
      }
   },
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
   "linkedHubs":[
      "custom-allocation-toasters-hub.azure-devices.net",
      "custom-allocation-heatpumps-hub.azure-devices.net"
   ]
}

لأن هذا هو التسجيل الأولي للجهاز، تحتوي الخاصية deviceRuntimeContext فقط على معرف التسجيل وتفاصيل المصادقة للجهاز. يظهر JSON التالي deviceRuntimeContext لاستدعاء لاحق لتسجيل نفس الجهاز. لاحظ أنه يتم تضمين اسم مضيف مركز IoT الحالي ومعرف الجهاز في الطلب.

{
   "deviceRuntimeContext":{
      "registrationId":"breakroom499-contoso-tstrsd-007",
      "currentIotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
      "currentDeviceId":"breakroom499-contoso-tstrsd-007",
      "symmetricKey":{
         
      }
   },
}

استجابة نهج التخصيص المخصص

يقوم الطلب الناجح بإرجاع كائن AllocationResponse .

الخاصية ‏‏الوصف
نافذة أولية اختياري. كائن يحتوي على الخصائص والعلامات المطلوبة لتعيينها في التوأم الأولي على مركز IoT المعين. يستخدم DPS الخاصية initialTwin لتعيين التوأم الأولي على مركز IoT المعين عند التعيين الأولي أو عند إعادة التوفير إذا تم تعيين نهج ترحيل إدخال التسجيل إلى إعادة التوفير وإعادة التعيين إلى التكوين الأولي. في كلتا الحالتين، إذا لم يتم إرجاع initialTwin أو تم تعيينه على null، يقوم DPS بتعيين التوأم على مركز IoT المعين إلى الإعدادات المزدوجة الأولية في إدخال التسجيل. تتجاهل DPS الميزة initialTwin لكافة إعدادات إعادة التزويد الأخرى في إدخال التسجيل. لمعرفة المزيد، راجع تفاصيل التنفيذ.
iotHubHostName مطلوب. اسم مضيف مركز IoT لتعيين الجهاز إليه. يجب أن يكون هذا أحد مراكز IoT التي تم تمريرها في الخاصية linkedHubs في الطلب.
حموله اختياري. كائن يحتوي على بيانات ليتم تمريرها مرة أخرى إلى الجهاز في استجابة التسجيل. تعتمد البيانات الدقيقة على العقد الضمني الذي حدده المطور بين الجهاز ووظيفة التخصيص المخصصة.

يعرض JSON التالي كائن AllocationResponse الذي تم إرجاعه بواسطة دالة تخصيص مخصصة إلى DPS للتسجيل في المثال السابق.

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   }
}

استخدام حمولات الجهاز في التخصيص المخصص

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

على سبيل المثال، قد ترغب في تخصيص الأجهزة استنادا إلى طراز الجهاز. في هذه الحالة، يمكنك تكوين الجهاز للإبلاغ عن معلومات النموذج الخاص به في حمولة الطلب عند تسجيله مع DPS. يمرر DPS هذه الحمولة إلى خطاف الويب للتخصيص المخصص، والذي يحدد مركز IoT الذي يتم توفير الجهاز إليه استنادا إلى معلومات طراز الجهاز. إذا لزم الأمر، يمكن أن يقوم خطاف الويب بإرجاع البيانات مرة أخرى إلى DPS ككائن JSON في استجابة الإخطار على الويب، ويعيد DPS هذه البيانات إلى جهازك في استجابة التسجيل.

يرسل الجهاز حمولة البيانات إلى DPS

يستدعي الجهاز واجهة برمجة تطبيقات تسجيل DPS للتسجيل في DPS. يمكن تحسين الطلب باستخدام خاصية الحمولة الاختيارية. يمكن أن تحتوي هذه الخاصية على أي كائن JSON صالح. تعتمد المحتويات الدقيقة على متطلبات الحل الخاص بك.

للتصديق باستخدام TPM، يبدو نص الطلب مثل المثال التالي:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

يرسل DPS حمولة البيانات إلى خطاف الويب المخصص للتخصيص

إذا كان الجهاز يتضمن حمولة طلب التسجيل الخاص به، فإن DPS تمرر الحمولة في خاصية AllocationRequest.deviceRuntimeContext.payload عند استدعاء إخطار على الويب المخصص للتخصيص.

بالنسبة لطلب تسجيل TPM في القسم السابق، يبدو سياق وقت تشغيل الجهاز مثل المثال التالي:

{ 
    "registrationId": "mydevice", 
    "tpm": { 
        "endorsementKey": "xxxx-device-endorsement-key-xxxxx", 
        "storageRootKey": "xxxx-device-storage-root-key-xxxxx" 
    }, 
    "payload": { "property1": "value1", "property2": {"propertyA":"valueA", "property2-2":1234}, .. } 
}

إذا لم يكن هذا هو التسجيل الأولي للجهاز، فإن سياق وقت التشغيل يتضمن أيضا خصائص currentIoTHubHostnameوcurrentDeviceId .

يقوم خطاف ويب التخصيص المخصص بإرجاع البيانات إلى DPS

يمكن لخطاف ويب نهج التخصيص المخصص إرجاع البيانات المخصصة لجهاز إلى DPS في كائن JSON باستخدام خاصية AllocationResponse.payload في استجابة خطاف الويب.

يظهر JSON التالي استجابة إخطار على الويب تتضمن حمولة:

{
   "iotHubHostName":"custom-allocation-toasters-hub.azure-devices.net",
   "initialTwin":{
      "properties":{
         "desired":{
            "state":"ready",
            "darknessSetting":"medium"
         }
      },
      "tags":{
         "deviceType":"toaster"
      }
   },
   "payload": { "property1": "value1" } 
}

يرسل DPS حمولة البيانات إلى الجهاز

إذا تلقت DPS حمولة في استجابة خطاف الويب، فإنها تمرر هذه البيانات مرة أخرى إلى الجهاز في خاصية RegistrationOperationStatus.registrationState.payload في الاستجابة لتسجيل ناجح. الخاصية registrationState من نوع DeviceRegistrationResult.

يظهر JSON التالي استجابة تسجيل ناجحة لجهاز TPM يتضمن خاصية الحمولة:

{
   "operationId":"5.316aac5bdc130deb.b1e02da8-xxxx-xxxx-xxxx-7ea7a6b7f550",
   "status":"assigned",
   "registrationState":{
      "assignedHub":"myIotHub",
      "createdDateTimeUtc" : "2022-08-01T22:57:47Z",
      "deviceId" : "myDeviceId",
      "etag" : "xxxx-etag-value-xxxxx",
      "lastUpdatedDateTimeUtc" : "2022-08-01T22:57:47Z",
      "payload": { "property1": "value1" },
      "registrationId": "mydevice", 
      "status": assigned,
      "substatus": initialAssignment,
      "tpm": {"authenticationKey": "xxxx-encrypted-authentication-key-xxxxx"}
   }
}

تفاصيل التنفيذ

يمكن استدعاء خطاف الويب للتخصيص المخصص لجهاز لم يتم تسجيله مسبقا من خلال DPS (التعيين الأولي) أو لجهاز تم تسجيله مسبقا من خلال DPS (إعادة التوفير). يدعم DPS نهج إعادة التزويد التالية: إعادة توفير البيانات وترحيلها، وإعادة التوفير وإعادة التعيين إلى التكوين الأولي، وإعادة التوفير أبدا. يتم تطبيق هذه النهج كلما تم تعيين جهاز تم توفيره مسبقا إلى مركز IoT جديد. لمزيد من المعلومات، راجع مفاهيم إعادة توفير جهاز IoT Hub.

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

  • يجب تعيين الجهاز إلى أحد مراكز IoT في خاصية AllocationRequest.linkedHubs . تحتوي هذه الخاصية على قائمة بمراكز IoT حسب اسم المضيف الذي يمكن تعيين الجهاز إليه. يتكون هذا عادة من مراكز IoT المحددة لإدخال التسجيل. إذا لم يتم تحديد مراكز IoT في إدخال التسجيل، فإنه يحتوي على جميع مراكز IoT المرتبطة بمثيل DPS. وأخيرا، إذا كان الجهاز يقوم بإعادة التوفير وتم تعيين نهج عدم إعادة التوفير مطلقا في إدخال التسجيل، فإنه يحتوي فقط على مركز IoT الذي تم تعيين الجهاز له حاليا.

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

  • عند إعادة التزويد، يتبع DPS نهج إعادة التزويد الذي تم تعيينه في إدخال التسجيل. يستخدم DPS خاصية initialTwin فقط في الاستجابة إذا تم تغيير مركز IoT الحالي وكان نهج إعادة التزويد المعين على إدخال التسجيل هو Reprovision وإعادة التعيين إلى التكوين الأولي. في هذه الحالة، يعين DPS التوأم الأولي للجهاز على مركز IoT الجديد تماما كما هو الحال أثناء التعيين الأولي في التعداد النقطي السابق. في جميع الحالات الأخرى، تتجاهل DPS خاصية initialTwin .

  • إذا تم تعيين خاصية الحمولة في الاستجابة، فإن DPS يعيدها دائما إلى الجهاز بغض النظر عما إذا كان الطلب مخصصا أوليا أو إعادة توفير.

  • إذا تم توفير جهاز مسبقا إلى مركز IoT، فإن AllocationRequest.deviceRuntimeContext يحتوي على خاصية currentIotHubHostName ، والتي تم تعيينها على اسم المضيف لمركز IoT حيث تم تعيين الجهاز حاليا.

  • يمكنك تحديد أي من نهج إعادة التزويد التي تم تعيينها حاليا على إدخال التسجيل، عن طريق فحص خاصية reprovisionPolicy إما AllocationRequest.individualEnrollment أو الخاصية AllocationRequest.enrollmentGroup في الطلب. يعرض JSON التالي إعدادات نهج إعادة توفير البيانات وترحيلها:

           "reprovisionPolicy":{
          "updateHubAssignment":true,
          "migrateDeviceData":true
       }

دعم عدة تطوير البرامج

توفر حزم SDK لجهاز DPS واجهات برمجة التطبيقات في C وC# وJava Node.js لمساعدتك في تسجيل الأجهزة باستخدام DPS. توفر كل من IoT Hub SDKs وDPS SDKs فئات تمثل أدوات الجهاز والخدمة مثل توائم الجهاز وإدخالات التسجيل التي قد تكون مفيدة عند تطوير خطافات ويب مخصصة للتخصيص. لمعرفة المزيد حول Azure IoT SDKs المتوفرة لخدمة IoT Hub وIoT Hub Device Provisioning، راجع Azure IoT Hub SDKsوMicrosoft SDKs لخدمة توفير جهاز IoT Hub.

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

  • Last updated on