使用 fabric-cicd 部署 Power BI 專案（PBIP）

fabric-cicd 是一個官方支援，由 Microsoft 支持的開源 Python 函式庫，提供一種以程式碼為優先的方式，讓 Fabric 開發者能使用其程式碼定義格式（如語意模型與 PBIP 檔案格式的報告）從原始碼控制部署到工作區。 此工具可整合 Fabric Git 整合、Fabric REST API 及 Fabric CLI，實現工作區間一致的部署流程。

在本文中，您將學會如何：

  • 請手動從本地機器部署 PBIP 檔案
  • 參數化 PBIP 檔案以符合環境特定配置
  • 利用 Azure DevOps 或 GitHub Actions 自動化基於分支的工作區目標部署

在 Power BI桌面專案（PBIP） 以及 Fabric Git 整合概覽 中了解更多關於 PBIP 格式的資訊。

為什麼選擇 Fabric-CICD 用於 PBIP 部署？

fabric-cicd 專為部署源代碼控制的 Fabric 構件設計，並具備多項優勢：

  • 使用 Fabric 原生 REST API - 基於官方 Microsoft Fabric API，確保相容性與長期支援
  • 自動化相依性處理 - 決定正確的部署順序，並解決項目間的相依性（例如在報告前發布語意模型），減少手動排序並減少部署錯誤
  • Python-native - 與現代基於Python的 DevOps 工作流程無縫整合
  • 參數化 - 內建對環境特定配置（工作區 ID、資料來源、連接字串）的支援
  • Developer-Friendly - 簡單Python腳本，可在本地或 CI/CD 管線中執行
  • 彈性部署控制 - 僅部署特定項目類型（例如無報告的語意模型，或有無資料快取的語意模型），並確保設定一致，如預設頁面或參數，無需人工介入
  • 孤立項目清理 - 自動從工作區移除來源控制中已不存在的項目
  • Reliable Authentication - 使用 Azure Identity SDK 並具備多種認證選項

備註

完整文件請參閱 fabric-cicd 文件。

先決條件

在開始之前，請確保您擁有：

  • Python（版本 3.9 至 3.12）
  • 一個以 PBIP 格式儲存的 Power BI 桌面專案
  • 以貢獻者角色存取 Microsoft Fabric 工作空間

自動化部署還需要：

  • 一位至少在目標 Fabric 工作區擔任貢獻者角色的服務主體
  • 存取 Azure DevOps 或 GitHub Actions
  • 你在原始碼控制（Git、Azure DevOps 或 GitHub）中的 PBIP 檔案

快速入門

這個快速入門指南會教你如何從本地機器部署 PBIP 專案到 Fabric 工作區。

1. 安裝布製CICD

打開終端並安裝 fabric-cicd：

pip install fabric-cicd

2. 準備你的 PBIP 專案

確保您的 PBIP 專案包含所需的檔案。 典型的 PBIP 專案結構：

my-powerbi-project/
├── SalesAnalytics.Report/
│   ├── definition.pbir
│   └── definition/
│       └── pages/
├── SalesAnalytics.SemanticModel/
│   ├── definition.pbism
│   └── definition/
│       ├── model.tmdl
│       ├── tables/
│       └── ...
└── SalesAnalytics.pbip

如需詳細了解所需檔案與格式，請參閱 Power BI Desktop 專案報告資料夾 以及 Power BI Desktop 專案語意模型資料夾。

小提示

要建立 PBIP 專案，請在桌面Power BI開啟你的 PBIX 檔案，並使用 File > 另存為 > Power BI 專案（.pbip） 儲存。 詳情請參見 Power BI桌面專案。

3. 建立部署腳本

在項目目錄中建立 deploy.py 檔案：

import argparse
from azure.identity import InteractiveBrowserCredential, AzureCliCredential
from fabric_cicd import FabricWorkspace, publish_all_items

parser = argparse.ArgumentParser(description="Deploy PBIP to Fabric")
parser.add_argument("--workspace_name", type=str, required=False, help="Target workspace name", default="PBIP Fabric CICD Dev")
parser.add_argument("--environment", type=str, default="dev", help="Environment name")
parser.add_argument("--spn-auth", action="store_true", help="Use SPN authentication via Azure CLI")
args = parser.parse_args()

# Use InteractiveBrowserCredential for local development, AzureCliCredential for CI/CD pipelines
if not args.spn_auth:
    credential = InteractiveBrowserCredential()
else:
    credential = AzureCliCredential()

workspace_params = {
    "workspace_name": args.workspace_name,
    "environment": args.environment,
    "repository_directory": ".",
    "item_type_in_scope": ["SemanticModel", "Report"],
    "token_credential": credential,
}

target_workspace = FabricWorkspace(**workspace_params)
publish_all_items(target_workspace)

4. 部署

執行部署腳本，並使用你的工作區名稱：

python deploy.py --workspace_name "PBIP Fabric CICD Dev"

備註

你也可以在指令碼的 workspace_id 字典和命令列引數中，將 workspace_params 替換為 workspace_name，來使用工作區 ID（GUID）。

你的瀏覽器開啟以進行認證。 登入後，fabric-cicd 會將你的 PBIP 檔案部署到目標工作區。 你會看到像這樣的進度訊息：

[info] Publishing SemanticModel 'SalesAnalytics'
       Operation in progress. Checking again in 1 second (Attempt 1)...
       Published

[info] Publishing Report 'SalesAnalytics'
       Published

部署通常需要 20-30 秒，視語意模型大小而定。

備註

第一次部署帶有資料來源的語意模型時，你需要在 Fabric 入口網站手動設定資料來源憑證。 請前往工作空間 > 語意模型 > 設定 > 資料來源憑證。 後續部署會重複使用儲存的憑證。

環境特定參數化

fabric-cicd 最強大的功能之一是能夠針對不同環境參數化你的 PBIP 檔案。 當你的語意模型引用環境特定資源（如工作區 ID、湖屋 ID 或連線字串）時，這點尤為重要。

範例：參數化工作區與湖屋 ID

在專案根目錄建立 parameter.yml 一個檔案，定義環境特定的值：

find_replace:
  # Replace workspace ID for DirectLake connection
  - find_value: "11111111-1111-1111-1111-111111111111"
    replace_value:
      dev: "11111111-1111-1111-1111-111111111111"  # Dev workspace
      prod: "22222222-2222-2222-2222-222222222222"  # Prod workspace

  # Replace lakehouse ID for DirectLake semantic model
  - find_value: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
    replace_value:
      dev: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"  # Dev lakehouse
      prod: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"  # Prod lakehouse

當您執行 python deploy.py --workspace_name "PBIP Fabric CICD Dev" --environment dev 時，fabric-cicd 會自動進行以下操作：

  1. 讀取parameter.yml檔案
  2. 在你的 PBIP 定義檔案中找到所有 的 find_value 實例
  3. 以對應的環境專用 replace_value 替換它們
  4. 將修改後的定義部署至目標工作區

自動化部署

你可以自動化 PBIP 部署，以便在程式碼合併到儲存庫中特定分支時自動執行。 自動化的邏輯如下：

  1. 當程式碼推送到已設定的分支（例如，dev 或 main）時，管道或工作流程會被觸發。
  2. 分支名稱決定目標環境與工作區 ID
  3. 部署腳本會自動執行，並依照設定好的適當參數進行運行。
  4. 你的 PBIP 產物會部署到該環境的正確工作區

本節涵蓋 Azure DevOps 與 GitHub Actions 常見的設定步驟，接著是平台專屬的設定說明。

設定

在配置您的 CI/CD 平台前，請完成以下常見的設定步驟：

1. 建立服務主體

在 Azure AD 建立一個服務主體，並在你的 Fabric 工作空間中扮演貢獻者或管理員角色。

2. 將服務主體加入 Fabric 工作空間

  1. 打開 Fabric 入口網站，並導覽到每個目標工作區（開發、生產）
  2. 前往工作區設定 > 管理存取權限
  3. 新增服務主體並賦予「貢獻者」或「管理員」角色。

備註

服務主體必須在租戶層級啟用才能使用 Fabric API。 欲了解更多資訊，請參閱 服務主體可呼叫 Fabric 公開 API。

3. 在你的儲存庫中設定分支

建立你將用於自動化的分支。 本文的例子如下：

  1. 建立用於開發環境部署的 dev 分支
  2. 建立用於生產環境部署的 main 分支

你可以透過修改 YAML 檔案中的工作區映射來自訂分支名稱並新增更多環境。

Azure DevOps

用 Azure Pipelines 自動化 PBIP 部署。 當程式碼被推送到已設定的分支時，管線會自動部署到對應的工作區。

在你的儲存庫根目錄建立 azure-pipelines.yml ：

trigger:
  branches:
    include:
      - dev
      - main

variables:
  - name: workspace_names
    value: |
      {
        "dev": "PBIP Fabric CICD Dev",
        "main": "PBIP Fabric CICD Prod"
      }
  - name: environments
    value: |
      {
        "dev": "dev",
        "main": "prod"
      }

stages:
  - stage: Deploy
    jobs:
      - job: DeployPBIP
        pool:
          vmImage: 'windows-latest'
        steps:
          - checkout: self
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.12'
              addToPath: true
          - task: AzureCLI@2
            displayName: 'Deploy PBIP to Fabric'
            inputs:
              azureSubscription: 'your-azure-service-connection'
              scriptType: 'ps'
              scriptLocation: 'inlineScript'
              inlineScript: |
                cd "$(Build.SourcesDirectory)"
                
                pip install fabric-cicd
                
                $branch_ref = $env:BUILD_SOURCEBRANCH
                $branch_name = $branch_ref -replace '^refs/heads/', ''
                
                $workspace_names = '$(workspace_names)' | ConvertFrom-Json
                $environments = '$(environments)' | ConvertFrom-Json
                
                $workspace_name = $workspace_names.$branch_name
                $environment = $environments.$branch_name
                
                python -u deploy.py --spn-auth --workspace_name "$workspace_name" --environment "$environment"
                
                if ($LASTEXITCODE -ne 0) {
                    Write-Error "Deployment failed with exit code: $LASTEXITCODE"
                    exit $LASTEXITCODE
                }

Azure DevOps 組態設定

  1. 在Azure DevOps專案設定中建立Azure服務連線：
    • 前往專案設定 > 服務連結
    • 使用你的服務主體憑證建立一個新的 Azure Resource Manager 服務連線
    • 詳細說明請參見 Connect to Microsoft Azure
    • 更新 azureSubscription YAML 中的值以符合你的服務連線名稱
  2. 更新 YAML 中的工作區名稱：
    • 在azure-pipelines.yml中編輯 workspace_names 變數
    • 設定你的開發與生產工作區名稱
    • 提交並推送變更到你的儲存庫
  3. 建立流程：
    • 前往 Pipelines > 新 Pipeline
    • 選擇你的儲存庫並選擇「現有 Azure Pipelines YAML 檔案」
    • 選擇 azure-pipelines.yml
    • 詳細說明請參見「建立你的第一個管線」
    • 儲存並執行管線，將你的 PBIP 部署到 Fabric

GitHub Actions

使用 GitHub Actions 自動化 PBIP 部署。 當程式碼被推送到已設定的分支時，工作流程會自動部署到對應的工作區。

在您的資料庫中建立 .github/workflows/deploy.yml ：

name: Deploy PBIP to Fabric

on:
  push:
    branches: [dev, main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      
      - name: Set workspace variables
        id: workspace
        shell: pwsh
        run: |
          $branch_name = "${{ github.ref_name }}"
          
          $workspace_names = @{
            "dev" = "PBIP Fabric CICD Dev"
            "main" = "PBIP Fabric CICD Prod"
          }
          
          $environments = @{
            "dev" = "dev"
            "main" = "prod"
          }
          
          $workspace_name = $workspace_names[$branch_name]
          $environment = $environments[$branch_name]
          
          echo "workspace_name=$workspace_name" >> $env:GITHUB_OUTPUT
          echo "environment=$environment" >> $env:GITHUB_OUTPUT
      
      - name: Azure Login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
          allow-no-subscriptions: true
      
      - name: Deploy PBIP to Fabric
        shell: pwsh
        run: |
          pip install fabric-cicd
          
          python -u deploy.py --spn-auth --workspace_name "${{ steps.workspace.outputs.workspace_name }}" --environment "${{ steps.workspace.outputs.environment }}"
          
          if ($LASTEXITCODE -ne 0) {
              Write-Error "Deployment failed with exit code: $LASTEXITCODE"
              exit $LASTEXITCODE
          }

設定 GitHub Actions

  1. 建立Azure憑證秘密：

    • 取得您的服務主體憑證，格式為 JSON： 
      {
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "tenantId": "<azure-tenant-id>"
}
    • 前往GitHub儲存庫設定 > 秘密與變數 > 動作
    • 將上面的 JSON 新增至 AZURE_CREDENTIALS

  2. 更新工作流程中的工作區名稱：

    • 在「設定工作區變數」步驟中，編輯雜湊表 workspace_names.github/workflows/deploy.yml
    • 設定你的開發與生產工作區名稱
    • 提交並推送工作流程 YAML 到你的資料庫

相關內容

  • 上次更新時間：