البرنامج التعليمي: استخدام نهج التخصيص المخصصة مع Device Provisioning Service (DPS)

  • مقالة

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

يوضح هذا البرنامج التعليمي نهج تخصيص مخصص باستخدام وظيفة Azure المكتوبة بلغة C#. يتم تعيين الأجهزة إلى أحد مركزي IoT اللذين يمثلان قسم محمصات Contoso وقسم مضخات الحرارة في Contoso. يجب أن يكون للأجهزة التي تطلب التزويد معرف تسجيل بإحدى اللاحقات التالية ليتم قبولها للتزويد:

  • -contoso-tstrsd-007 لقسم محمصات Contoso
  • -contoso-hpsd-088 لقسم مضخات الحرارة Contoso

تتم محاكاة الأجهزة باستخدام عينة توفير مضمنة في Azure IoT C SDK.

في هذا البرنامج التعليمي، ستقوم بما يلي:

  • استخدم Azure CLI لإنشاء مثيل DPS ولإنشاء وربط مركزي IoT لقسم Contoso (قسم محمصات Contoso وقسم مضخات الحرارة Contoso) به.
  • إنشاء دالة Azure التي تنفذ نهج التخصيص المخصص.
  • إنشاء مجموعة تسجيل جديدة تستخدم وظيفة Azure لنهج التخصيص المخصص.
  • إنشاء مفاتيح متماثلة للجهاز لجهازين محاكاة.
  • إعداد بيئة التطوير ل Azure IoT C SDK.
  • محاكاة الأجهزة والتحقق من توفيرها وفقا لمثال التعليمات البرمجية في نهج التخصيص المخصص.

إذا لم يكن لديك اشتراك في Azure، فأنشئ حساب Azure مجاني قبل أن تبدأ.

المتطلبات الأساسية

المتطلبات الأساسية التالية هي لبيئة تطوير Windows. بالنسبة إلى Linux أو macOS، راجع القسم المناسب في إعداد بيئة التطوير في وثائق SDK.

إنشاء خدمة التزويد ومركزي IoT

في هذا القسم، يمكنك استخدام Azure Cloud Shell لإنشاء خدمة توفير ومركزي IoT يمثلان قسم محمصات Contoso وقسم Contoso Heat Pumps.

  1. أولا، قم بتعيين متغيرات البيئة في مساحة العمل الخاصة بك لتبسيط الأوامر في هذا البرنامج التعليمي.

    يجب أن تكون أسماء DPS وIoT Hub فريدة عالميا. استبدل SUFFIX العنصر النائب بقيمتك الخاصة.

    أيضا، تبحث التعليمات البرمجية ل Azure Function التي تقوم بإنشائها لاحقا في هذا البرنامج التعليمي عن مراكز IoT التي تحتوي على أو -toasters--heatpumps- في أسمائها. إذا قمت بتغيير القيم المقترحة، فتأكد من استخدام الأسماء التي تحتوي على السلاسل الفرعية المطلوبة.

    #!/bin/bash
export RESOURCE_GROUP="contoso-us-resource-group"
export LOCATION="westus"
export DPS="contoso-provisioning-service-SUFFIX"
export TOASTER_HUB="contoso-toasters-hub-SUFFIX"
export HEATPUMP_HUB="contoso-heatpumps-hub-SUFFIX"

    # PowerShell
$env:RESOURCE_GROUP = "contoso-us-resource-group"
$env:LOCATION = "westus"
$env:DPS = "contoso-provisioning-service-SUFFIX"
$env:TOASTER_HUB = "contoso-toasters-hub-SUFFIX"
$env:HEATPUMP_HUB = "contoso-heatpumps-hub-SUFFIX"

    تلميح

    تنشئ الأوامر المستخدمة في هذا البرنامج التعليمي موارد في موقع غرب الولايات المتحدة بشكل افتراضي. نوصي بإنشاء مواردك في المنطقة الأقرب إليك التي تدعم خدمة توفير الأجهزة. يمكنك عرض قائمة بالمواقع المتوفرة بالانتقال إلى صفحة حالة Azure والبحث عن "خدمة تزويد الأجهزة". في الأوامر، يمكن تحديد المواقع إما بتنسيق كلمة واحدة أو تنسيق متعدد الكلمات؛ على سبيل المثال: westus، وWest US، وWEST US، وما إلى ذلك. القيمة ليست حساسة لحالة الأحرف.

  2. استخدم الأمر az group create لإنشاء مجموعة موارد Azure. مجموعة موارد Azure هي حاوية منطقية يتم بها نشر موارد Azure وإدارتها.

    ينشئ المثال التالي مجموعة موارد. نوصي باستخدام مجموعة واحدة لجميع الموارد التي تم إنشاؤها في هذا البرنامج التعليمي. سيجعل هذا النهج التنظيف أسهل بعد الانتهاء.

    az group create --name $RESOURCE_GROUP --location $LOCATION

  3. استخدم الأمر az iot dps create لإنشاء مثيل لخدمة توفير الأجهزة (DPS). تتم إضافة خدمة التوفير إلى contoso-us-resource-group.

    az iot dps create --name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION

    قد يستغرق هذا الأمر بضع دقائق لإكماله.

  4. استخدم الأمر az iot hub create لإنشاء مركز Contoso Toasters Division IoT. تتم إضافة مركز IoT إلى contoso-us-resource-group.

    az iot hub create --name $TOASTER_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    قد يستغرق هذا الأمر بضع دقائق لإكماله.

  5. استخدم الأمر az iot hub create لإنشاء مركز Contoso Heat Pumps Division IoT. تتم إضافة مركز IoT هذا أيضا إلى contoso-us-resource-group.

    az iot hub create --name $HEATPUMP_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    قد يستغرق هذا الأمر بضع دقائق لإكماله.

  6. قم بتشغيل الأمرين التاليين للحصول على سلسلة الاتصال للمراكز التي قمت بإنشائها.

    az iot hub connection-string show --hub-name $TOASTER_HUB --key primary --query connectionString -o tsv
az iot hub connection-string show --hub-name $HEATPUMP_HUB --key primary --query connectionString -o tsv

  7. قم بتشغيل الأوامر التالية لربط المراكز بمورد DPS. استبدل العناصر النائبة بالمركز سلسلة الاتصال من الخطوة السابقة.

    az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <toaster_hub_connection_string>
az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <heatpump_hub_connection_string>

إنشاء دالة التخصيص المخصصة

في هذا القسم، يمكنك إنشاء دالة Azure التي تنفذ نهج التخصيص المخصص. تحدد هذه الدالة مركز IoT القسمي الذي يجب تسجيل الجهاز فيه بناء على ما إذا كان معرف التسجيل الخاص به يحتوي على السلسلة -contoso-tstrsd-007 أو -contoso-hpsd-088. كما أنه يحدد الحالة الأولية للجهاز المزدوج بناء على ما إذا كان الجهاز محمصة أو مضخة حرارية.

  1. قم بتسجيل الدخول إلى بوابة Azure.

  2. في مربع البحث، ابحث عن Function App وحدده.

  3. حدد Create or Create Function App.

  4. في صفحة إنشاء تطبيق الوظائف، ضمن علامة التبويب أساسيات ، أدخل الإعدادات التالية لتطبيق الوظائف الجديد وحدد مراجعة + إنشاء:

    المعلمة القيمة
    الاشتراك تأكد من تحديد الاشتراك الذي أنشأت فيه الموارد لهذا البرنامج التعليمي.
    مجموعة الموارد حدد مجموعة الموارد التي قمت بإنشائها في القسم السابق. الإعداد الافتراضي المتوفر في القسم السابق هو contoso-us-resource-group.
    اسم تطبيق الوظائف أدخل اسما لتطبيق الوظائف.
    هل تريد نشر التعليمات البرمجية أو صورة الحاوية؟ الرمز
    مكدس وقت التشغيل NET.
    ‏‏الإصدار حدد أي إصدار نموذج قيد المعالجة.
    المنطقة حدد أقرب منطقة إليك.

    إشعار

    بشكل افتراضي، يتم تمكين Application Insights. Application Insights ليس ضروريا لهذا البرنامج التعليمي، ولكنه قد يساعدك على فهم أي مشكلات تواجهها مع التخصيص المخصص والتحقيق فيها. إذا كنت تفضل ذلك، يمكنك تعطيل Application Insights عن طريق تحديد علامة التبويب Monitoring ثم تحديد No للخيار Enable Application Insights.

    لقطة شاشة تعرض نموذج Create Function App في مدخل Microsoft Azure.

  5. في علامة التبويب Review + create ، حدد Create لإنشاء تطبيق الوظائف.

  6. قد يستغرق النشر عدة دقائق. عند الانتهاء، حدد Go to resource.

  7. في الجزء الأيمن من صفحة نظرة عامة على تطبيق الوظائف، حدد Create function.

    لقطة شاشة توضح تحديد خيار إنشاء وظيفة في مدخل Microsoft Azure.

  8. في صفحة Create function ، حدد قالب HTTP Trigger ثم حدد Next.

  9. في علامة التبويب تفاصيل القالب، حدد مجهول كمستوى التخويل ثم حدد إنشاء.

    لقطة شاشة توضح تعيين مستوى التخويل على أنه مجهول.

    تلميح

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

  10. عند فتح الدالة HttpTrigger1 ، حدد Code + Test في الجزء الأيمن. يسمح لك هذا بتحرير التعليمات البرمجية للدالة. يجب فتح ملف التعليمات البرمجية run.csx للتحرير.

  11. الرجوع إلى حزم NuGet المطلوبة. لإنشاء توأم الجهاز الأولي، تستخدم دالة التخصيص المخصصة الفئات التي تم تعريفها في حزمتي NuGet التي يجب تحميلها في بيئة الاستضافة. باستخدام Azure Functions، تتم الإشارة إلى حزم NuGet باستخدام ملف function.proj . في هذه الخطوة، يمكنك حفظ وتحميل ملف function.proj للتجميعات المطلوبة. لمزيد من المعلومات، راجع استخدام حزم NuGet مع Azure Functions.

    1. انسخ الأسطر التالية في المحرر المفضل لديك واحفظ الملف على الكمبيوتر الخاص بك ك function.proj.

      <Project Sdk="Microsoft.NET.Sdk">  
    <PropertyGroup>  
        <TargetFramework>netstandard2.0</TargetFramework>  
    </PropertyGroup>  
    <ItemGroup>  
        <PackageReference Include="Microsoft.Azure.Devices.Provisioning.Service" Version="1.18.1" />
        <PackageReference Include="Microsoft.Azure.Devices.Shared" Version="1.30.1" />
    </ItemGroup>  
</Project>

    2. حدد الزر Upload الموجود أعلى محرر التعليمات البرمجية لتحميل ملف function.proj. بعد التحميل، حدد الملف في محرر التعليمات البرمجية باستخدام مربع القائمة المنسدلة للتحقق من المحتويات.

    3. حدد الملف function.proj في محرر التعليمات البرمجية وتحقق من محتوياته. إذا كان الملف function.proj فارغا، فانسخ الأسطر أعلاه في الملف واحفظه. (في بعض الأحيان يقوم التحميل بإنشاء الملف دون تحميل المحتويات.)

  12. تأكد من تحديد run.csx ل HttpTrigger1 في محرر التعليمات البرمجية. استبدل التعليمات البرمجية لدالة HttpTrigger1 بالتعليمات البرمجية التالية وحدد حفظ:

    #r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

using Microsoft.Azure.Devices.Shared;               // For TwinCollection
using Microsoft.Azure.Devices.Provisioning.Service; // For TwinState

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    // Get request body
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    log.LogInformation("Request.Body:...");
    log.LogInformation(requestBody);

    // Get registration ID of the device
    string regId = data?.deviceRuntimeContext?.registrationId;

    string message = "Uncaught error";
    bool fail = false;
    ResponseObj obj = new ResponseObj();

    if (regId == null)
    {
        message = "Registration ID not provided for the device.";
        log.LogInformation("Registration ID : NULL");
        fail = true;
    }
    else
    {
        string[] hubs = data?.linkedHubs?.ToObject<string[]>();

        // Must have hubs selected on the enrollment
        if (hubs == null)
        {
            message = "No hub group defined for the enrollment.";
            log.LogInformation("linkedHubs : NULL");
            fail = true;
        }
        else
        {
            // This is a Contoso Toaster Model 007
            if (regId.Contains("-contoso-tstrsd-007"))
            {
                //Find the "-toasters-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-toasters-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No toasters hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "toaster";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "ready";
                    properties["darknessSetting"] = "medium";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // This is a Contoso Heat pump Model 008
            else if (regId.Contains("-contoso-hpsd-088"))
            {
                //Find the "-heatpumps-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-heatpumps-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No heat pumps hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "heatpump";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "on";
                    properties["temperatureSetting"] = "65";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // Unrecognized device.
            else
            {
                fail = true;
                message = "Unrecognized device registration.";
                log.LogInformation("Unknown device registration");
            }
        }
    }

    log.LogInformation("\nResponse");
    log.LogInformation((obj.iotHubHostName != null) ? JsonConvert.SerializeObject(obj) : message);

    return (fail)
        ? new BadRequestObjectResult(message) 
        : (ActionResult)new OkObjectResult(obj);
}

public class ResponseObj
{
    public string iotHubHostName {get; set;}
    public TwinState initialTwin {get; set;}
}

إنشاء التسجيل

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

  1. سجل الدخول إلى مدخل Microsoft Azure وانتقل إلى مثيل خدمة تزويد الأجهزة.

  2. حدد إدارة التسجيلات من قسم الإعدادات من قائمة التنقل.

  3. حدد Add enrollment group.

  4. في علامة التبويب Registration + provisioning في صفحة Add enrollment group ، قم بتوفير المعلومات التالية لتكوين تفاصيل مجموعة التسجيل:

    الحقل ‏‏الوصف
    شهاده حدد مفتاح متماثل كآلية التصديق.
    إعدادات المفتاح المتماثل حدد المربع إنشاء مفاتيح متماثلة تلقائيا.
    اسم المجموعة أدخل contoso-custom-custom-allocated-devices كاسم المجموعة.
    حالة التوفير حدد المربع تمكين هذا التسجيل.

  5. حدد Next: IoT hubs.

  6. في علامة التبويب IoT hubs في صفحة Add enrollment group ، قم بتوفير المعلومات التالية لتحديد مراكز IoT التي يمكن لمجموعة التسجيل توفير الأجهزة لها:

    الحقل ‏‏الوصف
    مراكز IoT المستهدفة حدد واحدا أو أكثر من مراكز IoT المرتبطة، أو أضف ارتباطا جديدا إلى مركز IoT.
    نهج التخصيص حدد Custom (use Azure Function). حدد Select Azure function، ثم اتبع المطالبات لتحديد الدالة التي قمت بإنشائها لهذا البرنامج التعليمي.

  7. حدد "Review + create".

  8. في علامة التبويب Review + create ، تحقق من جميع القيم الخاصة بك ثم حدد Create.

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

اشتقاق مفاتيح جهاز فريدة

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

لاشتقاق مفتاح الجهاز، يمكنك استخدام مجموعة التسجيل Primary Key التي لاحظتها سابقا لحساب HMAC-SHA256 لمعرف تسجيل الجهاز لكل جهاز وتحويل النتيجة إلى تنسيق Base 64. لمزيد من المعلومات حول إنشاء مفاتيح الأجهزة المشتقة مع مجموعات التسجيل، راجع قسم التسجيلات الجماعية في Symmetric key attestation.

على سبيل المثال في هذا البرنامج التعليمي، استخدم معرفي تسجيل الجهاز التاليين واحسب مفتاح جهاز لكلا الجهازين. يحتوي معرفا التسجيل على لاحقة صالحة للعمل مع مثال التعليمات البرمجية لنهج التخصيص المخصص:

  • breakroom499-contoso-tstrsd-007
  • mainbuilding167-contoso-hpsd-088

يوفر ملحق IoT لـ Azure CLI الأمر iot dps enrollment-group compute-device-key لإنشاء مفاتيح الأجهزة المشتقة. يمكن استخدام هذا الأمر على الأنظمة المستندة إلى Windows أو Linux، من PowerShell أو Bash shell.

استبدل قيمة الوسيطة --key بـ Primary Key من مجموعة التسجيل.

az iot dps enrollment-group compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id breakroom499-contoso-tstrsd-007

az iot dps compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id mainbuilding167-contoso-hpsd-088

إشعار

يمكنك أيضا توفير معرف مجموعة التسجيل بدلا من المفتاح المتماثل للأمر iot dps enrollment-group compute-device-key . على سبيل المثال:

az iot dps enrollment-group compute-device-key -g contoso-us-resource-group --dps-name contoso-provisioning-service-1098 --enrollment-id contoso-custom-allocated-devices --registration-id breakroom499-contoso-tstrsd-007

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

إعداد بيئة تطوير SDK IoT C من Azure

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

يتم توجيه هذا المقال نحو محطة عمل تستند إلى Windows. للحصول على مثال Linux، راجع إعداد الأجهزة الظاهرية في البرنامج التعليمي: توفير لزمن الانتقال الجغرافي.

  1. قم بتنزيل نظام CMake build.

    من المهم تثبيت المتطلبات الأساسية ل Visual Studio (Visual Studio و "تطوير سطح المكتب مع حمل العمل C++" على جهازك، قبل بدء CMake التثبيت. بمجرد أن يتم وضع المتطلبات الأساسية، ويتم التحقق من التنزيل، قم بتثبيت نظام بنية CMake.

  2. ابحث عن اسم العلامة لأحدث إصدار من SDK.

  3. افتح موجه الأوامر أو Git Bash shell. قم بتشغيل الأوامر التالية لاستنساخ أحدث إصدار من Azure IoT Device SDK لمستودع C GitHub. استخدم العلامة التي وجدتها في الخطوة السابقة كقيمة للمعلمة -b ، على سبيل المثال: lts_01_2023.

    git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

    يجب أن تتوقع أن تستغرق هذه العملية عدة دقائق حتى تكتمل.

  4. إنشاء cmake دليل فرعي في الدليل الجذر لمستودع git ثم انتقل إلى ذلك المجلد. تشغيل الأوامر التالية من الدليل azure-iot-sdk-c:

    mkdir cmake
cd cmake

  5. تشغيل الأمر التالي الذي ينشئ إصدار SDK خاصة إلى النظام الأساسي لعميل التطوير الخاص بك. يتم إنشاء حل Visual Studio للجهاز المحاكى في الدليل cmake.

    cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..

    إذا cmake لم يعثر على المحول البرمجي C++، فقد ترى أخطاء في الإنشاء أثناء تشغيل الأمر. إذا حدث ذلك، فحاول تشغيل الأمر في موجه الأوامر Visual Studio.

    بمجرد نجاح البناء، تبدو أسطر الإخراج القليلة الأخيرة مشابهة للإخراج التالي:

    $ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
-- Building for: Visual Studio 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake

محاكاة الجهاز

في هذا القسم، يمكنك تحديث نموذج توفير يسمى prov_dev_client_sample موجود في Azure IoT C SDK الذي قمت بإعداده مسبقا.

تحاكي هذه التعليمة البرمجية نموذج تسلسل تمهيد جهاز يرسل طلب التوفير إلى مثيل "Device Provisioning Service". يؤدي تسلسل التمهيد إلى التعرف على جهاز المحمصة وتعيينه إلى مركز IoT باستخدام نهج التخصيص المخصص.

  1. في مدخل Microsoft Azure، حدد علامة التبويب Overview لخدمة إدارة الأجهزة الخاصة بك وقم بتدوين قيمة ID Scope.

    استخراج معلومات نقطة نهاية خدمة توفير الأجهزة من وحدة المدخل

  2. في Visual Studio، افتح ملف الحل azure_iot_sdks.sln الذي تم إنشاؤه بواسطة تشغيل CMake مسبقًا. يجب أن يكون ملف الحل في الموقع التالي: azure-iot-sdk-c\cmake\azure_iot_sdks.sln.

  3. في نافذة مستكشف الحلول Visual Studio، انتقل إلى مجلد Provision_Samples. قم بتوسيع نموذج المشروع المسمى prov_dev_client_sample. قم بتوسيع ملفات المصدر، وافتح prov_dev_client_sample.c.

  4. ابحث عن id_scope الثابت، واستبدل القيمة بقيمة نطاق معرفك التي قمت بنسخها سابقاً.

    static const char* id_scope = "0ne00002193";

  5. ابحث عن تعريف الدالة main() في نفس الملف. تأكد من تعيين المتغير hsm_type كما هو موضح SECURE_DEVICE_TYPE_SYMMETRIC_KEY أدناه:

    SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
//hsm_type = SECURE_DEVICE_TYPE_X509;
hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;

  6. في الدالة main()، ابحث عن الاستدعاء إلى Prov_Device_Register_Device(). قبل ذلك الاستدعاء، قم بإضافة الأسطر التالية من التعليمات البرمجية التي تستخدم Prov_Device_Set_Provisioning_Payload() لتمرير حمولة JSON مخصصة أثناء التوفير. يمكن استخدام هذا لتوفير مزيد من المعلومات إلى وظائف التخصيص المخصصة. ويمكن أيضاً استخدام هذا لتمرير نوع الجهاز بدلاً من فحص معرف التسجيل. لمزيد من المعلومات حول إرسال حمولات البيانات المخصصة وتلقيها باستخدام DPS، راجع كيفية نقل الحمولات بين الأجهزة وDPS.

    // An example custom payload
const char* custom_json_payload = "{\"MyDeviceFirmwareVersion\":\"12.0.2.5\",\"MyDeviceProvisioningVersion\":\"1.0.0.0\"}";

prov_device_result = Prov_Device_Set_Provisioning_Payload(prov_device_handle, custom_json_payload);
if (prov_device_result != PROV_DEVICE_RESULT_OK)
{
    (void)printf("\r\nFailure setting provisioning payload: %s\r\n", MU_ENUM_TO_STRING(PROV_DEVICE_RESULT, prov_device_result));
}

  7. انقر بزر الماوس الأيمن فوق مشروع prov_dev_client_sample وحدد تعيين كمشروع بدء التشغيل.

محاكاة جهاز محمصة Contoso

  1. لمحاكاة جهاز المحمصة، ابحث عن الاستدعاء في prov_dev_set_symmetric_key_info()prov_dev_client_sample.c الذي تم التعليق عليه.

    // Set the symmetric key if using they auth type
//prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");

    قم بإلغاء تعليق استدعاء الوظيفة، واستبدل قيم العناصر النائبة (بما في ذلك أقواس الزاوية) بمعرف تسجيل المحمصة ومفتاح الجهاز المشتق الذي أنشأته مسبقًا. القيمة الرئيسية JC8F96eayuQwz+PkE7IzjH2lIAjCUnAa61tDigBnSs= الموضحة أدناه مقدمة فقط كمثال.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("breakroom499-contoso-tstrsd-007", "JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs=");

    حفظ الملف.

  2. في القائمة Visual Studio حدد Debug> البدء من دون تصحيح الأخطاء لتشغيل الحل. في المطالبة بإعادة إنشاء المشروع، حدد Yes لإعادة إنشاء المشروع قبل تشغيله.

    الإخراج التالي هو مثال على جهاز محمصة محاكاة التشغيل بنجاح والاتصال بمثيل خدمة التوفير ليتم تعيينه إلى مركز IoT المحمصة بواسطة نهج التخصيص المخصص:

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-toasters-hub-1098.azure-devices.net, deviceId: breakroom499-contoso-tstrsd-007

Press enter key to exit:

    الإخراج التالي هو مثال على إخراج التسجيل من التعليمة البرمجية لدالة التخصيص المخصصة التي تعمل لجهاز المحمصة. لاحظ أنه تم تحديد مركز بنجاح لجهاز محمصة. لاحظ أيضا الخاصية payload التي تحتوي على محتوى JSON المخصص الذي أضفته إلى التعليمات البرمجية. يتوفر هذا للتعليمة البرمجية لاستخدامه داخل deviceRuntimeContext.

    يتوفر هذا التسجيل بالنقر فوق Logs ضمن التعليمة البرمجية للوظيفة في المدخل:

    2022-08-03T20:34:41.178 [Information] Executing 'Functions.HttpTrigger1' (Reason='This function was programmatically called via the host APIs.', Id=12950752-6d75-4f41-844b-c253a6653d4f)
2022-08-03T20:34:41.340 [Information] C# HTTP trigger function processed a request.
2022-08-03T20:34:41.341 [Information] Request.Body:...
2022-08-03T20:34:41.341 [Information] {"enrollmentGroup":{"enrollmentGroupId":"contoso-custom-allocated-devices","attestation":{"type":"symmetricKey"},"capabilities":{"iotEdge":false},"etag":"\"0000f176-0000-0700-0000-62eaad1e0000\"","provisioningStatus":"enabled","reprovisionPolicy":{"updateHubAssignment":true,"migrateDeviceData":true},"createdDateTimeUtc":"2022-08-03T17:15:10.8464255Z","lastUpdatedDateTimeUtc":"2022-08-03T17:15:10.8464255Z","allocationPolicy":"custom","iotHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"],"customAllocationDefinition":{"webhookUrl":"https://contoso-function-app-1098.azurewebsites.net/api/HttpTrigger1?****","apiVersion":"2021-10-01"}},"deviceRuntimeContext":{"registrationId":"breakroom499-contoso-tstrsd-007","currentIotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","currentDeviceId":"breakroom499-contoso-tstrsd-007","symmetricKey":{},"payload":{"MyDeviceFirmwareVersion":"12.0.2.5","MyDeviceProvisioningVersion":"1.0.0.0"}},"linkedHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"]}
2022-08-03T20:34:41.382 [Information] Response
2022-08-03T20:34:41.398 [Information] {"iotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","initialTwin":{"properties":{"desired":{"state":"ready","darknessSetting":"medium"}},"tags":{"deviceType":"toaster"}}}
2022-08-03T20:34:41.399 [Information] Executed 'Functions.HttpTrigger1' (Succeeded, Id=12950752-6d75-4f41-844b-c253a6653d4f, Duration=227ms)

محاكاة جهاز مضخة الحرارة Contoso

  1. لمحاكاة جهاز مضخة الحرارة، قم بتحديث الاستدعاء إلى prov_dev_set_symmetric_key_info() في prov_dev_client_sample.c مرة أخرى باستخدام معرف تسجيل مضخة الحرارة ومفتاح الجهاز المشتق الذي أنشأته سابقا. القيمة الرئيسية 6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg= الموضحة أدناه هي أيضاً فقط كمثال.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("mainbuilding167-contoso-hpsd-088", "6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg=");

    حفظ الملف.

  2. في القائمة Visual Studio حدد Debug> البدء من دون تصحيح الأخطاء لتشغيل الحل. في المطالبة بإعادة إنشاء المشروع، حدد Yes لإعادة إنشاء المشروع قبل تشغيله.

    الإخراج التالي هو مثال على جهاز مضخة الحرارة المحاكاة بنجاح التمهيد والاتصال بمثيل خدمة التزويد ليتم تعيينه إلى مركز مضخات الحرارة Contoso IoT بواسطة نهج التخصيص المخصص:

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-heatpumps-hub-1098.azure-devices.net, deviceId: mainbuilding167-contoso-hpsd-088

Press enter key to exit:

استكشاف أخطاء نهج التخصيص المخصصة وإصلاحها

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

السيناريو نتيجة التسجيل من خدمة التزويد توفير نتائج SDK
يقوم الإخطار على الويب بإرجاع 200 موافق مع تعيين "iotHubHostName" إلى اسم مضيف مركز IoT صالح حالة النتيجة: تم التعيين ترجع SDK PROV_DEVICE_RESULT_OK مع معلومات المركز
يقوم خطاف الويب بإرجاع 200 موافق مع وجود "iotHubHostName" في الاستجابة، ولكن يتم تعيينه إلى سلسلة فارغة أو فارغة حالة النتيجة: فشل

رمز الخطأ: CustomAllocationIotHubNotSpecified (400208)		 ترجع SDK PROV_DEVICE_RESULT_HUB_NOT_SPECIFIED
يقوم خطاف الويب بإرجاع 401 غير مصرح به حالة النتيجة: فشل

رمز الخطأ: CustomAllocationUnauthorizedAccess (400209)		 ترجع SDK PROV_DEVICE_RESULT_UNAUTHORIZED
تم إنشاء تسجيل فردي لتعطيل الجهاز حالة النتيجة: معطل ترجع SDK PROV_DEVICE_RESULT_DISABLED
يقوم الإخطار على الويب بإرجاع رمز >الخطأ = 429 سيعيد تنسيق DPS المحاولة عدة مرات. نهج إعادة المحاولة حاليا:

  - عدد مرات إعادة المحاولة: 10
  - الفاصل الزمني الأولي: 1 ثانية
  - الزيادة: 9 ثانية		 سيتجاهل SDK الخطأ ويرسل رسالة حالة الحصول على أخرى في الوقت المحدد
يقوم خطاف الويب بإرجاع أي رمز حالة آخر حالة النتيجة: فشل

رمز الخطأ: CustomAllocationFailed (400207)		 ترجع SDK PROV_DEVICE_RESULT_DEV_AUTH_ERROR

تنظيف الموارد

إذا كنت تخطط لمواصلة العمل مع الموارد التي تم إنشاؤها في هذا البرنامج التعليمي، يمكنك تركها. إذا كنت لا تخطط لمتابعة استخدام الموارد، فاستخدم الخطوات التالية لحذف جميع الموارد التي تم إنشاؤها في هذا البرنامج التعليمي لتجنب الرسوم غير الضرورية.

تفترض الخطوات هنا أنك أنشأت جميع الموارد في هذا البرنامج التعليمي كما هو موضح في نفس مجموعة الموارد المسماة contoso-us-resource-group.

هام

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

لحذف مجموعة الموارد حسب الاسم:

  1. سجل الدخول إلىمدخل Azureوحددمجموعات الموارد.

  2. في مربع النص Filter by name...، اكتب اسم مجموعة الموارد التي تحتوي على الموارد الخاصة بك، contoso-us-resource-group.

  3. إلى يمين مجموعة الموارد في قائمة النتائج، حدد ... ثم Delete resource group.

  4. سيطلب منك تأكيد حذف مجموعة الموارد. اكتب اسم مجموعة الموارد مرة أخرى لتأكيده، واختر Delete. بعد لحظات قليلة، يتم حذف مجموعة الموارد وكافة الموارد المضمنة.

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

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

فهم نهج التخصيص المخصصة