مشاركة عبر

فهم نهج التخصيص المخصصة باستخدام 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 طلب 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 TpmAttestation للحصول على شهادة TPM، يحتوي على مفتاح المصادقة وتفاصيل مفتاح جذر التخزين.
payload كائن يحتوي على خصائص محددة من قبل الجهاز في خاصية الحمولة أثناء التسجيل. تقديم إذا أرسل الجهاز حمولة مخصصة في طلب تسجيل 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 Hub الحالي ومعرف الجهاز مضمنان في الطلب.

{
   "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 المعين في التعيين الأولي أو عند إعادة التوفير إذا تم تعيين نهج ترحيل إدخال التسجيل إلى Reprovision وإعادة التعيين إلى التكوين الأولي. في كلتا الحالتين، إذا لم يتم إرجاع initialTwin أو تم تعيينه إلى خال، يقوم DPS بتعيين التوأم على مركز IoT المعين إلى إعدادات التوأم الأولي في إدخال التسجيل. تتجاهل DPS الميزة initialTwin لكافة إعدادات إعادة التزويد الأخرى في إدخال التسجيل. لمعرفة المزيد، راجع تفاصيل التنفيذ.
iotHubHostName مطلوب. اسم مضيف مركز IoT لتعيين الجهاز إليه. يجب أن يكون هذا أحد مراكز IoT التي تم تمريرها في الخاصية linkedHubs في الطلب.
payload اختياري. كائن يحتوي على بيانات ليتم تمريرها مرة أخرى إلى الجهاز في استجابة التسجيل. ستعتمد البيانات الدقيقة على العقد الضمني المحدد من قبل المطور بين الجهاز ووظيفة التخصيص المخصصة.

يظهر 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. يمكن تحسين الطلب باستخدام خاصية الحمولة الاختيارية. يمكن أن تحتوي هذه الخاصية على أي كائن 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 في خاصية 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، راجع Azure IoT Hub SDKs وAzure DPS SDKs.

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