共用方式為


教學課程:使用 GitHub Actions 將 Azure 裝置佈建服務自動化

使用 GitHub Actions 之類的自動化工具來管理 IoT 裝置生命週期。 本教學課程示範使用 Azure 裝置佈建服務將裝置連線到 IoT 中樞的 GitHub Actions 工作流程。

在本教學課程中,您會了解如何:

  • 將驗證認證儲存為存放庫秘密。
  • 建立工作流程以布建 IoT 中樞和裝置布建服務資源。
  • 執行工作流程,並在模擬裝置連線到 IoT 中樞 時加以監視。

必要條件

  • Azure 訂閱

    如尚未擁有 Azure 訂用帳戶,請在開始之前先建立免費帳戶

  • Azure CLI

    • Azure Cloud Shell 中使用 Bash 環境。

    • 或者,如果您想要在本機執行 CLI 參考命令,請 安裝 Azure CLI。 如果您正在 Windows 或 macOS 上執行,請考慮 在 Docker 容器中執行 Azure CLI。

      • 如果您使用的是本機安裝,請使用 az login 命令,透過 Azure CLI 來登入。

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

  • GitHub 帳戶,其中包含您擁有的存放庫,或具有系統管理員存取權的存放庫。 如需詳細資訊,請參閱 開始使用 GitHub

1 - 建立存放庫秘密

您在下一節中定義的工作流程需要存取您的 Azure 訂用帳戶,才能建立和管理資源。 您不想將該資訊放在可以探索到的未受保護的檔案中,因此我們會使用存放庫密碼來儲存此資訊,但仍可將其當做工作流程中的環境變數存取。 如需詳細資訊,請參閱 加密的秘密。

只有存放庫擁有者和系統管理員可以管理存放庫秘密。

建立服務主體

我們不會提供您的個人存取認證,而是會建立服務主體,然後將這些認證新增為存放庫秘密。 使用 Azure CLI 建立新的服務主體。 如需詳細資訊,請參閱 建立 Azure 服務主體

  1. 使用 az ad sp create-for-rbac 命令來建立具有特定資源群組參與者存取權的服務主體。 將 <SUBSCRIPTION_ID><RESOURCE_GROUP_NAME> 取代為您的個人資訊。

    此命令需要訂用帳戶中的擁有者或使用者存取系統管理員角色。

    az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
    
  2. 從服務主體建立命令的輸出複製下列專案,以在下一節中使用:

    • clientId
    • clientSecret。 這是服務主體產生的密碼,您無法再次存取。
    • tenantId
  3. 使用 az role assignment create 命令,將另外兩個存取角色指派給服務主體:裝置布建服務數據參與者IoT 中樞 數據參與者。 將取代 <SP_CLIENT_ID> 為您 從上一個命令輸出複製的 clientId 值。

    az role assignment create --assignee "<SP_CLIENT_ID>" --role "Device Provisioning Service Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
    
    az role assignment create --assignee "<SP_CLIENT_ID>" --role "IoT Hub Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
    

將服務主體認證儲存為秘密

  1. GitHub.com 上,流覽至存放庫的 設定

  2. 從導覽功能表中選取 [秘密 ],然後選取 [ 動作]。

  3. 選取 [新增存放庫祕密]。

  4. 為您的服務主體標識碼建立秘密。

    • 名稱APP_ID
    • 秘密:貼上 您從服務主體建立命令輸出複製的 clientId
  5. 選取 [新增秘密],然後選取 [新增存放庫密碼 ] 以新增第二個秘密。

  6. 為您的服務主體密碼建立秘密。

    • 名稱SECRET
    • 秘密:貼上 您從服務主體建立命令輸出複製的 clientSecret
  7. 選取 [新增秘密],然後選取 [新增存放庫密碼 ] 以新增最終秘密。

  8. 為您的 Azure 租使用者建立秘密。

    • 名稱TENANT
    • 秘密:貼上 您從服務主體建立命令輸出複製的tenantId
  9. 選取 [新增祕密]。

2 - 建立工作流程

GitHub Actions 工作流程會定義一旦事件觸發後執行的工作。 工作流程包含一或多個 可平行或循序執行的作業 。 如需詳細資訊,請參閱 瞭解 GitHub Actions

在本教學課程中,我們將建立一個工作流程,其中包含下列每個工作的作業:

  • 布建 IoT 中樞 實例和 DPS 實例。
  • 將 IoT 中樞和 DPS 實例連結至彼此。
  • 在 DPS 實例上建立個別註冊,並透過 DPS 註冊,使用對稱密鑰驗證向 IoT 中樞註冊裝置。
  • 模擬裝置五分鐘並監視IoT中樞事件。

工作流程是位於 .github/workflows/ 存放庫目錄中的 YAML 檔案。

  1. 在您的 GitHub 存放庫中,流覽至 [ 動作] 索引標籤。

  2. 在 [ 動作] 窗格中,選取 [ 新增工作流程]。

  3. 在 [ 選擇工作流程] 頁面上,您可以選擇要使用的預先建置範本。 我們將為此教學課程建立自己的工作流程,因此請選取 [自行設定工作流程]。

  4. GitHub 會為您建立新的工作流程檔案。 請注意,它位於 .github/workflows/ 目錄中。 為新檔案提供有意義的名稱,例如 dps-tutorial.yml

  5. 新增 name 參數,為您的工作流程指定名稱。

    name: DPS Tutorial
    
  6. 新增 on.workflow_dispatch 參數。 參數 on 會定義工作流程何時執行。 參數 workflow_dispatch 表示我們想要手動觸發工作流程。 透過此參數,我們可以定義 inputs 會在每次執行時傳遞至工作流程,但我們不會針對本教學課程使用這些參數。

    on: workflow_dispatch
    
  7. 定義您在工作流程中建立之資源的環境變數。 這些變數將可供工作流程中的所有作業使用。 您也可以定義個別作業的環境變數,或針對作業內的個別步驟。

    將佔位元值取代為您自己的值。 請確定您指定服務主體可存取的相同資源群組。

    env:
      HUB_NAME: <Globally unique IoT hub name>
      DPS_NAME: <Desired Device Provisioning Service name>
      DEVICE_NAME: <Desired device name>
      RESOURCE_GROUP: <Solution resource group where resources will be created>
    
  8. 定義您在上一節中建立之秘密的環境變數。

      SP_USER: ${{ secrets.APP_ID }}
      SP_SECRET: ${{ secrets.SECRET }}
      SP_TENANT: ${{ secrets.TENANT }}
    
  9. jobs 參數新增至工作流程檔案。

    jobs:
    
  10. 定義工作流程的第一個作業,我們將呼叫 provision 該作業。 此作業會布建 IoT 中樞 和 DPS 實例:

      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
    

    如需此作業中執行之命令的詳細資訊,請參閱:

  11. 定義 DPS 和 IoT 中樞 實例的作業configure。 請注意,此作業會使用 needs 參數,這表示 configure 在列出的作業順利完成自己的執行之前,作業將不會執行。

      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"   
    

    如需此作業中執行之命令的詳細資訊,請參閱:

  12. 定義名為 register 的作業,以建立個別註冊,然後使用該註冊來註冊裝置以 IoT 中樞。

      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login   
    

    注意

    此作業和其他人會在某些命令中使用 參數 --auth-type login ,以指出作業應該使用來自目前 Microsoft Entra 會話的服務主體。 或者, --auth-type key 不需要服務主體設定,但較不安全。

    如需此作業中執行之命令的詳細資訊,請參閱:

  13. 將作業定義至 simulate IoT裝置,以連線到IoT中樞並傳送範例遙測訊息。

      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
    

    如需此作業中執行之命令的詳細資訊,請參閱:

  14. 針對事件定義IoT中樞端點的作業 monitor ,並監看來自模擬裝置的訊息。 請注意,模擬監視作業都會在其 參數中needs定義註冊作業。 此設定表示一旦 註冊 作業順利完成,這兩個作業都會以平行方式執行。

      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y   
    

    如需此作業中執行之命令的詳細資訊,請參閱:

  15. 完整的工作流程檔案看起來應該像這個範例,而您的資訊會取代環境變數中的佔位元值:

    name: DPS Tutorial
    
    on: workflow_dispatch
    
    env:
      HUB_NAME: <Globally unique IoT hub name>
      DPS_NAME: <Desired Device Provisioning Service name>
      DEVICE_NAME: <Desired device name>
      RESOURCE_GROUP: <Solution resource group where resources will be created>
      SP_USER: ${{ secrets.APP_ID }}
      SP_SECRET: ${{ secrets.SECRET }}
      SP_TENANT: ${{ secrets.TENANT }}
    
    jobs:
      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"
      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login
      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y
    
  16. 儲存、認可並推送此新檔案至您的 GitHub 存放庫。

3 - 執行工作流程

  1. 流覽至 GitHub 存放庫的 [動作] 索引標籤。

  2. 在 [ 動作] 窗格中,選取 [DPS 教學課程],這是我們在工作流程檔案中定義的名稱,然後選取 [ 執行工作流程 ] 下拉式方塊。

    Screenshot of the action tab where you can select a workflow and run it.

  3. 如果您在 main 以外的分支中建立工作流程,請變更分支,然後選取 [ 執行工作流程]。

  4. 新的工作流程執行隨即出現。 選取名稱以檢視執行的詳細數據。

  5. 在工作流程摘要中,您可以監看每項作業的開始和完成。 選取任何作業名稱以檢視其詳細數據。 模擬裝置作業會執行五分鐘,並將遙測數據傳送至 IoT 中樞。 在此期間,選取模擬作業來監看從裝置傳送的訊息,以及監視工作來監看 IoT 中樞 所接收的訊息。

  6. 當所有作業都順利完成時,您應該會看到每個作業的綠色複選標記。

    Screenshot of a successfully completed workflow.

清除資源

如果您不打算繼續使用本教學課程中建立的這些資源,請使用下列步驟加以刪除。

使用 Azure CLI:

  1. 列出資源群組中的資源。

    az resource list --resource-group <RESOURCE_GROUP_NAME>
    
  2. 若要刪除個別資源,請使用資源識別碼。

    az resource delete --resource-group <RESOURCE_GROUP_NAME> --ids <RESOURCE_ID>
    
  3. 如果您要刪除整個資源群組及其內的所有資源,請執行下列命令:

    az group delete --resource-group <RESOURCE_GROUP_NAME>
    

使用 Azure 入口網站:

  1. Azure 入口網站 中,流覽至您建立新資源的資源群組。
  2. 您可以刪除整個資源群組,或選取您想要移除的個別資源,然後選取 [ 刪除]。

下一步

瞭解如何使用其他自動化工具布建 DPS 實例。