使用 Azure Pipelines 整合 IoT Central 以進行持續整合與持續傳遞

持續整合與持續傳遞 (CI/CD) 是指使用自動化管線，以簡短、頻繁的週期開發及交付軟體的流程。 本文說明如何將 IoT Central 應用程式設定的建置、測試和部署自動化。 此自動化可讓開發小組更頻繁地產出可靠的版本。

持續整合的起始步驟是將程式碼認可到原始程式碼存放庫中的分支。 每個認可都會與其他開發人員的認可合併，以確保不會發生任何衝突。 建立組建並針對該組建執行自動化測試，以進一步驗證變更。 此流程最終會產出成品或部署套件組合，以部署到目標環境。 在此案例中，目標為 Azure IoT Central 應用程式。

如同 IoT Central 是較大 IoT 解決方案的一部分，IoT Central 是 CI/CD 管線的一部分。 CI/CD 管線應該將整個 IoT 解決方案和所有設定，部署到開發到實際執行流程的每個環境：

IoT Central 是「應用程式平台即服務」，其部署需求不同於「平台即服務」元件。 針對 IoT Central，您可以部署設定和裝置範本。 這些設定和裝置範本會使用 API 來管理，並整合到您的發行管線中。

雖然您可以將建立 IoT Central 應用程式的動作自動化，但您應該在開發 CI/CD 管線之前，先在每個環境中建立應用程式。

藉由使用 Azure IoT Central REST API，您可以將 IoT Central 應用程式設定整合到發行管線中。

本指南將逐步引導您建立新的管線，以根據 GitHub 中管理的設定檔來更新 IoT Central 應用程式。 本指南具有與 Azure Pipelines 整合的特定指示，但可調整為在任何使用 Tekton、Jenkins、GitLab 或 GitHub Actions 等工具建置的發行管線中包含 IoT Central。

在本指南中，您會建立只將 IoT Central 設定套用至 IoT Central 應用程式單一執行個體的管線。 您應該將步驟整合到較大的管線中，以部署整個解決方案，並將其從開發升級至 QA、生產階段前到生產，並一路執行所有必要的測試。

指令碼目前不會在 IoT Central 執行個體之間傳輸下列設定：儀表板、檢視、裝置範本中的自訂設定、定價方案、UX 自訂項目、應用程式映像、規則、排程工作、已儲存的工作和註冊群組。

指令碼目前不會從設定檔中不存在的目標 IoT Central 應用程式中，將設定移除。

必要條件

若要完成本指南中的步驟，您必須符合下列先決條件︰

• 兩個 IoT Central 應用程式 - 一個用於您的開發環境，另一個用於實際執行環境。 若要深入了解，請查看建立 IoT Central 應用程式。
• 兩個 Azure Key Vault - 一個用於您的開發環境，另一個用於實際執行環境。 最佳做法是為每個環境提供專用金鑰保存庫。 若要深入了解，請參閱使用 Azure 入口網站建立 Azure Key Vault。
• GitHub 帳戶GitHub。
• Azure DevOps 組織。 若要深入了解，請參閱建立 Azure DevOps 組織。
• 適用於 Windows、Mac 或 Linux 的 PowerShell 7。 取得 PowerShell。
• 安裝在 PowerShell 7 環境中的 Azure Az PowerShell 模組。 若要深入了解，請參閱安裝 Azure Az PowerShell 模組。
• Visual Studio Code 或其他工具來編輯 PowerShell 和 JSON 檔案。取得 Visual Studio Code。
• Git 用戶端。 從 Git - 下載 (git-scm.com)，下載最新版本。

• 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。

  

• 若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。

  • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱使用 Azure CLI 登入。

  • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。

  • 執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

下載範例程式碼

若要開始使用，請將 IoT Central CI/CD GitHub 存放庫建立分支，然後將分支複製到本機電腦：

1. 若要為 GitHub 存放庫建立分支，請開啟 IoT Central CI/CD GitHub 存放庫，然後選取 [分支]。

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. 請記下 [密碼]、[appId] 和 [租用戶]，因為您稍後需要這些值。

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 權杖

在本指南中，您的管線會使用 API 權杖來與您的 IoT Central 應用程式互動。 您也可以使用服務主體。

注意

IoT Central API 權杖會在一年後到期。

針對開發和實際執行環境的 IoT Central 應用程式完成下列步驟。

1. 在 IoT Central 應用程式中，選取 [權限]，然後選取 [API 權杖]。

2. 選取新增。

3. 為權杖命名、指定您應用程式中的最上層組織，並將角色設定為 [應用程式管理員]。

4. 記下來自開發 IoT Central 應用程式的 API 權杖。 您稍後會在執行 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}'
   

產生設定檔

這些步驟會根據現有的 IoT Central 應用程式，為您的開發環境產生 JSON 設定檔。 您也會從應用程式下載所有現有的裝置範本。

1. 在 IoT Central CI/CD 存放庫的本機複本中執行下列 PowerShell 7 指令碼：

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

2. 依照指示登入 Azure 帳戶。

3. 登入之後，指令碼會顯示 [IoTC 設定] 選項功能表。 指令碼可以從現有的 IoT Central 應用程式產生設定檔，並將設定套用至另一個 IoT Central 應用程式。

4. 選取選項 1 以產生設定檔。

5. 輸入必要的參數，然後按 Enter：

   • 您為開發 IoT Central 應用程式產生的 API 權杖。
   • 開發 IoT Central 應用程式的子網域。
   • 輸入 ..\Config\Dev 作為資料夾，來儲存設定檔和裝置範本。
   • 開發金鑰保存庫的名稱。

6. 指令碼會在存放庫本機複本的 Config\Dev 資料夾中，建立名為 [IoTC 設定] 的資料夾。 此資料夾包含應用程式中所有裝置範本的設定檔，以及稱為「裝置模型」的資料夾。

修改設定檔

現在您有一個設定檔，代表您開發 IoT Central 應用程式執行個體的設定，請先進行任何必要的變更，再將此設定套用至實際執行環境 IoT Central 應用程式的執行個體。

1. 針對先前建立的 Dev 資料夾建立副本，並將其命名為 [實際執行環境]。

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": "systemAssignedManagedIdentity",
             "endpointUri": "https://yourstorageaccount.blob.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. 如果您的應用程式針對資料匯出目的地使用受控識別，則沒有任何秘密可供您管理。 不過，您必須為生產 IoT Central 應用程式啟用系統指派的受控識別，並授與寫入目的地所需的權限。

6. 如果您的應用程式針對資料匯出目的地使用連線字串，請將目的地的秘密新增至生產金鑰保存庫。 設定檔不包含目的地的任何實際密碼，密碼會儲存在金鑰保存庫中。

7. 使用金鑰保存庫中的密碼名稱來更新設定檔中的密碼。

   目的地類型	要變更的屬性
   服務匯流排佇列	connectionString
   服務匯流排主題	connectionString
   Azure 資料總管	clientSecret
   Azure Blob 儲存體	connectionString
   事件中樞	connectionString
   Webhook 無授權	N/A

   例如：

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

8. 若要將 [設定] 資料夾上傳至 GitHub 存放庫，請從 [IoTC-CICD-howto] 資料夾執行下列命令。

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

建立新管線

1. 前往 https://dev.azure.com/{your DevOps organization}，以網頁瀏覽器開啟您的 Azure DevOps 組織
2. 選取 [新增專案] 以建立新的專案。
3. 為您的專案命名，並且可提供描述，然後選取 [建立]。
4. 在 [歡迎使用專案] 頁面上，選取 [管線]，然後選取 [建立管線]。
5. 選取 [GitHub] 作為程式碼的位置。
6. 選取 [授權 AzurePipelines] 以授權 Azure Pipelines 存取您的 GitHub 帳戶。
7. 在 [選取存放庫] 頁面上，選取 IoT Central CI/CD GitHub 存放庫的分支。
8. 當系統提示您登入 GitHub 並提供 Azure Pipelines 存取存放庫的權限時，請選取 [核准] 與 [安裝]。
9. 在 [設定管線] 頁面上，選取 [入門管線] 以開始使用。 azure-pipelines.yml 隨即顯示供您編輯。

建立變數群組

您可以透過變數群組，輕鬆將金鑰保存庫密碼整合到管線中。 使用變數群組來確保部署指令碼可以使用正確的密碼。 若要建立變數群組：

1. 在左側功能表的 [管線] 區段中選取 [程式庫]。

2. 選取 [+ 變數群組]。

3. 輸入 keyvault 作為變數群組的名稱。

4. 啟用切換，以從 Azure 金鑰保存庫連結密碼。

5. 選取您的 Azure 訂用帳戶並授權。 然後選取實際執行環境金鑰保存庫的名稱。

6. 選取 [新增] 以開始將變數新增至群組。

7. 新增下列密碼：

   • 實際執行環境應用程式的 IoT Central API 金鑰。 您在建立密碼時，已呼叫此密碼 API-Token。
   • 您先前建立的服務主體密碼。 您在建立密碼時，已呼叫此密碼 SP-Password。

8. 選取 [確定]。

9. 選取 [儲存] 以儲存變數群組。

設定您的管線

現在設定管線，將將設定變更推送至 IoT Central 應用程式：

1. 在左側功能表的 [管線] 區段中選取 [管線]。

2. 以下列 YAML 取代管線 YAML 的內容。 設定會假設您的實際執行環境金鑰保存庫具有下列項目：

   • 在稱為 API-Token 的密碼中，具有實際執行環境 IoT Central 應用程式的 API 權杖。
   • 在稱為 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 應用程式。