مشاركة عبر

دمج IoT Central مع Azure Pipelines للتكامل المستمر والتسليم المستمر

  • مقالة

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

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

كما أن IoT Central هو جزء من حل IoT الأكبر، فإن IoT Central هو جزء من البنية الأساسية لبرنامج ربط العمليات التجارية CI/CD. يجب أن تنشر البنية الأساسية لبرنامج ربط العمليات التجارية CI/CD حل IoT بأكمله وجميع التكوينات لكل بيئة من التطوير إلى الإنتاج:

رسم تخطيطي يوضح مراحل مسار CI/CD نموذجي.

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

في حين أنه من الممكن أتمتة إنشاء تطبيق IoT Central، يجب عليك إنشاء تطبيق في كل بيئة قبل تطوير البنية الأساسية لبرنامج ربط العمليات التجارية CI/CD.

باستخدام Azure IoT Central REST API، يمكنك دمج تكوينات تطبيق IoT Central في البنية الأساسية لبرنامج ربط العمليات التجارية للإصدار.

يرشدك هذا الدليل خلال إنشاء مسار جديد يقوم بتحديث تطبيق IoT Central استنادا إلى ملفات التكوين المدارة في GitHub. يحتوي هذا الدليل على إرشادات محددة للتكامل مع Azure Pipelines، ولكن يمكن تكييفه لتضمين IoT Central في أي مسار إصدار تم إنشاؤه باستخدام أدوات مثل Tekton أو Jenkins أو GitLab أو GitHub Actions.

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

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

لا تزيل البرامج النصية حاليا الإعدادات من تطبيق IoT Central الهدف غير الموجودة في ملف التكوين.

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

تحتاج إلى المتطلبات الأساسية التالية لإكمال الخطوات الواردة في هذا الدليل:

تنزيل نموذج التعليمات البرمجية

للبدء، قم بنسخ مستودع IoT Central CI/CD GitHub ثم نسخ نسخة المستودع إلى جهازك المحلي:

  1. لتشعب مستودع GitHub، افتح مستودع IoT Central CI/CD GitHub وحدد Fork.

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

    git clone https://github.com/{your GitHub username}/iot-central-CICD-sample

إنشاء كيان خدمة

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

لإنشاء كيان خدمة محدد النطاق لاشتراكك:

  1. قم بتشغيل الأمر التالي لإنشاء كيان خدمة جديد:

    az ad sp create-for-rbac -n DevOpsAccess --scopes /subscriptions/{your Azure subscription Id} --role Contributor

  2. دون كلمة المرور ومعرف التطبيق والمستأجر حيث تحتاج إلى هذه القيم لاحقا.

  3. أضف كلمة مرور كيان الخدمة كبيانات سرية تسمى SP-Password إلى مخزن مفاتيح الإنتاج الخاص بك:

    az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}

  4. امنح كيان الخدمة الإذن لقراءة البيانات السرية من مخزن المفاتيح:

    az keyvault set-policy --name {your production key vault name} --secret-permissions get list --spn {the appId of the service principal}

إنشاء رموز واجهة برمجة تطبيقات IoT Central

في هذا الدليل، يستخدم المسار الخاص بك رموز API المميزة للتفاعل مع تطبيقات IoT Central. من الممكن أيضا استخدام كيان الخدمة.

إشعار

تنتهي صلاحية الرموز المميزة لواجهة برمجة تطبيقات IoT Central بعد عام واحد.

أكمل الخطوات التالية لكل من تطوير تطبيقات IoT Central وإنتاجها.

  1. في تطبيق IoT Central، حدد Permissions ثم API tokens.

  2. حدد جديد.

  3. امنح الرمز المميز اسما، وحدد المؤسسة ذات المستوى الأعلى في تطبيقك، وقم بتعيين الدور إلى App مسؤول istrator.

  4. دون ملاحظة عن الرمز المميز لواجهة برمجة التطبيقات من تطبيق IoT Central الخاص بالتطوير. يمكنك استخدامه لاحقا عند تشغيل البرنامج النصي IoTC-Config.ps1 .

  5. احفظ الرمز المميز الذي تم إنشاؤه من تطبيق IoT Central للإنتاج كبيانات سرية تسمى API-Token إلى مخزن مفتاح الإنتاج:

    az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'

إنشاء ملف تكوين

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

  1. قم بتشغيل البرنامج النصي PowerShell 7 التالي في النسخة المحلية من مستودع IoT Central CI/CD:

    cd .\iot-central-CICD-sample\PowerShell\
.\IoTC-Config.ps1

  2. اتبع الإرشادات لتسجيل الدخول إلى حساب Azure الخاص بك.

  3. بعد تسجيل الدخول، يعرض البرنامج النصي قائمة خيارات تكوين IoTC. يمكن للبرنامج النصي إنشاء ملف تكوين من تطبيق IoT Central موجود وتطبيق تكوين على تطبيق IoT Central آخر.

  4. حدد الخيار 1 لإنشاء ملف تكوين.

  5. أدخل المعلمات الضرورية واضغط على Enter:

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

  6. ينشئ البرنامج النصي مجلدا يسمى IoTC Configuration في المجلد Config\Dev في نسختك المحلية من المستودع. يحتوي هذا المجلد على ملف تكوين ومجلد يسمى نماذج الجهاز لجميع قوالب الجهاز في التطبيق الخاص بك.

تعديل ملف التكوين

الآن بعد أن أصبح لديك ملف تكوين يمثل إعدادات مثيل تطبيق IoT Central الخاص بالتطوير، قم بإجراء أي تغييرات ضرورية قبل تطبيق هذا التكوين على مثيل تطبيق IoT Central للإنتاج.

  1. قم بإنشاء نسخة من مجلد Dev الذي تم إنشاؤه مسبقا واسمه Production.

  2. افتح IoTC-Config.json في مجلد الإنتاج باستخدام محرر نص.

  3. يحتوي الملف على مقاطع متعددة. ومع ذلك، إذا لم يستخدم تطبيقك إعدادا معينا، يتم حذف هذا المقطع من الملف:

    {
  "APITokens": {
    "value": [
      {
        "id": "dev-admin",
        "roles": [
          {
            "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
          }
        ],
        "expiry": "2023-05-31T10:47:08.53Z"
      }
    ]
  },
  "data exports": {
    "value": [
      {
        "id": "5ad278d6-e22b-4749-803d-db1a8a2b8529",
        "displayName": "All telemetry to blob storage",
        "enabled": false,
        "source": "telemetry",
        "destinations": [
          {
            "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63"
          }
        ],
        "status": "notStarted"
      }
    ]
  },
  "device groups": {
    "value": [
      {
        "id": "66f41d29-832d-4a12-9e9d-18932bee3141",
        "displayName": "MXCHIP Getting Started Guide - All devices"
      },
      {
        "id": "494dc749-0963-4ec1-89ff-e1de2228e750",
        "displayName": "RS40 Occupancy Sensor - All devices"
      },
      {
        "id": "dd87877d-9465-410b-947e-64167a7a1c39",
        "displayName": "Cascade 500 - All devices"
      },
      {
        "id": "91ceac5b-f98d-4df0-9ed6-5465854e7d9e",
        "displayName": "Simulated devices"
      }
    ]
  },
  "organizations": {
    "value": []
  },
  "roles": {
    "value": [
      {
        "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
        "displayName": "Builder"
      },
      {
        "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
        "displayName": "Administrator"
      },
      {
        "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
        "displayName": "Operator"
      }
    ]
  },
  "destinations": {
    "value": [
      {
        "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
        "displayName": "Blob destination",
        "type": "blobstorage@v1",
        "authorization": {
          "type": "connectionString",
          "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourexportaccount;AccountKey=*****;EndpointSuffix=core.windows.net",
          "containerName": "dataexport"
        },
        "status": "waiting"
      }
    ]
  },
  "file uploads": {
    "connectionString": "FileUpload",
    "container": "fileupload",
    "sasTtl": "PT1H"
  },
  "jobs": {
    "value": []
  }
}

  4. إذا كان التطبيق الخاص بك يستخدم تحميلات الملفات، فإن البرنامج النصي ينشئ سرا في مخزن مفاتيح التطوير الخاص بك بالقيمة الموضحة في الخاصية connectionString . إنشاء سر بنفس الاسم في مخزن مفتاح الإنتاج الذي يحتوي على سلسلة الاتصال لحساب تخزين الإنتاج الخاص بك. على سبيل المثال:

    az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'

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

  6. قم بتحديث الأسرار في ملف التكوين باسم السر في مخزن المفاتيح الخاص بك.

    نوع الوجهة الخاصية المراد تغييرها
    قائمة انتظار حافلة الخدمة سلسلة الاتصال
    موضوع ناقل الخدمة سلسلة الاتصال
    Azure Data Explorer ‏(Kusto) clientSecret
    Azure Blob Storage سلسلة الاتصال
    مراكز الأحداث سلسلة الاتصال
    Webhook No Auth ‏‫غير متوفر‬

    على سبيل المثال:

    "destinations": {
  "value": [
    {
      "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
      "displayName": "Blob destination",
      "type": "blobstorage@v1",
      "authorization": {
        "type": "connectionString",
        "connectionString": "Storage-CS",
        "containerName": "dataexport"
      },
      "status": "waiting"
    }
  ]
}

  7. لتحميل مجلد التكوين إلى مستودع GitHub الخاص بك، قم بتشغيل الأوامر التالية من المجلد IoTC-CICD-howto .

     git add Config
 git commit -m "Adding config directories and files"
 git push

إنشاء البنية الأساسية لبرنامج ربط العمليات التجارية

  1. افتح مؤسسة Azure DevOps في مستعرض ويب بالانتقال إلى https://dev.azure.com/{your DevOps organization}
  2. حدد مشروع جديد لإنشاء مشروع جديد.
  3. امنح مشروعك اسما ووصفا اختياريا ثم حدد إنشاء.
  4. في صفحة Welcome to the project ، حدد Pipelines ثم Create Pipeline.
  5. حدد GitHub كموقع للتعليمات البرمجية الخاصة بك.
  6. حدد Authorize AzurePipelines لتخويل Azure Pipelines للوصول إلى حساب GitHub الخاص بك.
  7. في صفحة تحديد مستودع ، حدد نسخة المستودع الخاصة بك من مستودع IoT Central CI/CD GitHub.
  8. عند مطالبتك بتسجيل الدخول إلى GitHub وتوفير إذن ل Azure Pipelines للوصول إلى المستودع، حدد Approve & install.
  9. في صفحة Configure your pipeline ، حدد Starter pipeline للبدء. يتم عرض azure-pipelines.yml للتحرير.

إنشاء مجموعة متغيرة

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

  1. حدد Library في قسم Pipelines من القائمة على اليسار.

  2. حدد + مجموعة متغيرة.

  3. أدخل keyvault كاسم لمجموعة المتغيرات الخاصة بك.

  4. قم بتمكين التبديل لربط الأسرار من مخزن مفاتيح Azure.

  5. حدد اشتراك Azure الخاص بك وقم بتخويله. ثم حدد اسم مخزن مفتاح الإنتاج الخاص بك.

  6. حدد إضافة لبدء إضافة متغيرات إلى المجموعة.

  7. أضف الأسرار التالية:

    • مفتاح واجهة برمجة تطبيقات IoT Central لتطبيق الإنتاج الخاص بك. لقد قمت باستدعاء هذا السر API-Token عندما قمت بإنشائه.
    • كلمة المرور الخاصة بكيان الخدمة الذي قمت بإنشائه مسبقا. لقد قمت باستدعاء هذا السر SP-Password عندما قمت بإنشائه.

  8. حدد موافق.

  9. حدد حفظ لحفظ مجموعة المتغيرات.

تكوين البنية الأساسية لبرنامج ربط العمليات التجارية

الآن قم بتكوين البنية الأساسية لبرنامج ربط العمليات التجارية لدفع تغييرات التكوين إلى تطبيق IoT Central الخاص بك:

  1. حدد Pipelines في قسم Pipelines من القائمة على اليسار.

  2. استبدل محتويات البنية الأساسية لبرنامج ربط العمليات التجارية YAML ب YAML التالي. يفترض التكوين أن مخزن مفاتيح الإنتاج الخاص بك يحتوي على:

    • رمز API المميز لتطبيق IoT Central للإنتاج الخاص بك في سر يسمى API-Token.
    • كلمة مرور كيان الخدمة في سر يسمى SP-Password.

    استبدل قيم -AppName و -KeyVault بالقيم المناسبة لمثيلات الإنتاج الخاصة بك.

    لقد قمت بتدوين -AppId و -TenantId عند إنشاء كيان الخدمة الخاص بك.

    trigger:
- master
variables:
- group: keyvault
- name: buildConfiguration
  value: 'Release'
steps:
- task: PowerShell@2
  displayName: 'IoT Central'
  inputs:
    filePath: 'PowerShell/IoTC-Task.ps1'
    arguments: '-ApiToken "$(API-Token)" -ConfigPath "Config/Production/IoTC Configuration" -AppName "{your production IoT Central app name}" -ServicePrincipalPassword (ConvertTo-SecureString "$(SP-Password)" -AsPlainText -Force) -AppId "{your service principal app id}" -KeyVault "{your production key vault name}" -TenantId "{your tenant id}"'
    pwsh: true
    failOnStderr:  true

  3. حدد حفظ وتشغيل.

  4. يتم حفظ ملف YAML في مستودع GitHub الخاص بك، لذلك تحتاج إلى توفير رسالة تثبيت ثم حدد حفظ وتشغيل مرة أخرى.

تم وضع البنية الأساسية لبرنامج ربط العمليات التجارية الخاصة بك في قائمة الانتظار. قد يستغرق الأمر بضع دقائق قبل تشغيله.

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

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

تعزيز التغييرات من التطوير إلى الإنتاج

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

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

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