Nasadit projekty Power BI (PBIP) pomocí fabric-cicd

Důležité

Projekty Power BI Desktopu jsou aktuálně ve verzi Preview.

fabric-cicd je knihovna Pythonu vyvinutá společností Microsoft, která vývojářům Fabric poskytuje kódově orientovanou metodu pro nasazení položek Fabric ze správy zdrojového kódu do pracovních prostorů pomocí jejich formátu definice kódu, jako jsou sémantické modely a sestavy používající formát souboru PBIP.

V tomto článku se naučíte:

• Ruční nasazení souborů PBIP z místního počítače
• Parametrizace souborů PBIP pro konfigurace specifické pro prostředí
• Automatizujte nasazení cílením na pracovní prostory založené na větvích s využitím Azure DevOps nebo GitHub Actions

Zjistěte více o formátu PBIP v projektech Power BI Desktop (PBIP) a přehledu integrace Fabric Git.

Proč používat fabric-cicd pro nasazení PBIP?

Fabric-cicd je speciálně navržený pro nasazení artefaktů ve verzi řízených systémem Fabric a nabízí několik výhod:

• Používá nativní rozhraní REST API Fabric – postavené na oficiálních rozhraních API Microsoft Fabric a zajišťující kompatibilitu a dlouhodobou podporu.
• Nativní pro Python – Bezproblémová integrace s moderními pracovními postupy DevOps založenými na Pythonu
• Parametrizace: Integrovaná podpora konfigurací specifických pro prostředí (ID pracovních prostorů, zdroje dat, připojovací řetězce)
• Přívětivé pro vývojáře: Jednoduché skripty Pythonu, které se dají spouštět místně nebo v kanálech CI/CD
• Flexibilní řízení nasazení: Nasaďte pouze konkrétní typy položek (např. sémantické modely bez sestav nebo sémantických modelů s mezipamětí dat nebo bez nich) a zajistěte konzistentní konfigurace, jako jsou výchozí stránky nebo parametry bez ručního zásahu.
• Odstranění osamocených položek: Automaticky odebere položky z pracovního prostoru, které už ve správě zdrojového kódu neexistují.
• Spolehlivé ověřování: Používá sadu Azure Identity SDK s několika možnostmi ověřování.

Poznámka:

Kompletní dokumentaci najdete v dokumentaci fabric-cicd.

Požadavky

Než začnete, ujistěte se, že máte:

• Python (verze 3.9 až 3.12)
• Projekt Power BI Desktopu uložený ve formátu PBIP
• Přístup k pracovnímu prostoru Microsoft Fabric s rolí Přispěvatel

Pro automatizovaná nasazení potřebujete také:

• Instanční objekt služby s alespoň rolí Přispěvatel v cílových pracovních prostorech Fabric
• Přístup k Azure DevOps nebo GitHub Actions
• Soubory PBIP ve správě zdrojového kódu (Git, Azure DevOps nebo GitHub)

Rychlý start

V tomto rychlém startu se dozvíte, jak nasadit projekt PBIP z místního počítače do pracovního prostoru Fabric.

1. Nainstalujte fabric-cicd

Otevřete terminál a nainstalujte fabric-cicd:

pip install fabric-cicd

2. Příprava projektu PBIP

Ujistěte se, že projekt PBIP obsahuje požadované soubory. Typická struktura projektu PBIP:

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

Podrobné informace o požadovaných souborech a formátech najdete ve složce sestav projektu Power BI Desktopu a sémantickém modelu projektu Power BI Desktopu.

Návod

Pokud chcete vytvořit projekt PBIP, otevřete soubor PBIX v Power BI Desktopu a uložte ho pomocí Soubor > Uložit jako > projekt Power BI (.pbip). Další podrobnosti najdete v projektech Power BI Desktopu .

3. Vytvoření skriptu nasazení

Vytvořte deploy.py soubor v adresáři projektu:

import argparse
import sys
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_id", type=str, required=True, help="Target workspace ID")
parser.add_argument("--environment", type=str, default="dev", help="Environment name")
args = parser.parse_args()

# Use AzureCliCredential in CI/CD, fall back to InteractiveBrowserCredential for local
try:
    credential = AzureCliCredential()
except Exception:
    credential = InteractiveBrowserCredential()

workspace_params = {
    "workspace_id": args.workspace_id,
    "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. Nasazení

Spusťte skript nasazení s ID pracovního prostoru:

python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111"

Otevře se váš prohlížeč pro ověřování. Po přihlášení nástroj fabric-cicd nasazuje vaše PBIP soubory do cílového pracoviště. Zobrazí se zprávy o průběhu, například:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Nasazení obvykle trvá 20 až 30 sekund v závislosti na velikosti sémantického modelu.

Poznámka:

Při prvním nasazení sémantického modelu se zdroji dat je potřeba na portálu Fabric ručně nakonfigurovat přihlašovací údaje ke zdroji dat. Přejděte na pracovní prostor > sémantický model > nastavení > přihlašovací údaje ke zdroji dat. Další nasazení znovu používají uložené přihlašovací údaje.

Parametrizace specifická pro prostředí

Jednou z nejvýkonnějších funkcí fabric-cicd je možnost parametrizovat soubory PBIP pro různá prostředí. To je nezbytné, když vaše sémantické modely odkazují na prostředky specifické pro prostředí, jako jsou ID pracovního prostoru, ID lakehouse nebo připojovací řetězce.

Příklad: Parametrizace ID pracovního prostoru a lakehouse

Vytvořte parameter.yml soubor v kořenovém adresáři projektu pro definování hodnot specifických pro prostředí:

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

Při spuštění python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment devpříkazu fabric-cicd automaticky:

1. Přečte soubor parameter.yml.
2. Ve vašich definičních souborech PBIP najde všechny instance find_value.
3. Nahrazuje je odpovídajícím prostředím specifickým pro replace_value.
4. Nasadí upravené definice do cílového pracovního prostoru.

Automatizovat nasazení

Nasazení PBIP můžete automatizovat tak, aby se spouštěla vždy, když se kód sloučí do konkrétních větví ve vašem úložišti. Automatizace se řídí touto logikou:

1. Kanál nebo pracovní postup se aktivuje, když se kód odešle do nakonfigurované větve (např. dev nebo main)
2. Název větve určuje cílové prostředí a ID pracovního prostoru.
3. Skript nasazení se spustí automaticky s příslušnými parametry.
4. Artefakty PBIP se nasazují do správného pracovního prostoru pro dané prostředí.

Tato část popisuje kroky nastavení, které jsou společné pro Azure DevOps i GitHub Actions a následně pokyny ke konfiguraci specifické pro platformu.

Nastavení

Před konfigurací platformy CI/CD proveďte tyto běžné kroky nastavení:

1. Vytvoření služebního objektu

Vytvořte služební účet v Azure AD s rolí Přispěvatel nebo Správce ve pracovních prostorech Fabric.

2. Přidání principálu služby do pracovních prostorů Fabric

1. Otevřete portál Fabric a přejděte do každého cílového pracovního prostoru (vývoj, prod).
2. Přejít na Nastavení > pracovního prostoru Spravovat přístup
3. Přidejte service principal s rolí Přispěvatel nebo Správce.

Poznámka:

Aby bylo možné používat Fabric APIs, musí být soubory služeb povolené na úrovni klienta. Další informace najdete v tématu Instanční objekty můžou volat veřejná rozhraní API fabric.

3. Konfigurace větví ve vašem úložišti

Vytvořte větve, které budete používat pro automatizaci. Příklady v tomto článku:

1. Vytvořte větev pro nasazení do vývojového dev prostředí
2. Vytvořte main větev pro nasazení do produkčního prostředí

Názvy větví můžete přizpůsobit a přidat další prostředí úpravou mapování pracovních prostorů v souborech YAML.

Azure DevOps

Automatizace nasazení PBIP pomocí Azure Pipelines Když se kód odešle do nakonfigurovaných větví, kanál se automaticky nasadí do odpovídajícího pracovního prostoru.

Vytvořte azure-pipelines.yml v kořenovém adresáři úložiště:

trigger:
  branches:
    include:
      - dev
      - main

variables:
  - name: workspace_ids
    value: |
      {
        "dev": "11111111-1111-1111-1111-111111111111",
        "main": "22222222-2222-2222-2222-222222222222"
      }
  - 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_ids = '$(workspace_ids)' | ConvertFrom-Json
                $environments = '$(environments)' | ConvertFrom-Json
                
                $workspace_id = $workspace_ids.$branch_name
                $environment = $environments.$branch_name
                
                python -u deploy.py --workspace_id "$workspace_id" --environment "$environment"
                
                if ($LASTEXITCODE -ne 0) {
                    Write-Error "Deployment failed with exit code: $LASTEXITCODE"
                    exit $LASTEXITCODE
                }

Konfigurace Azure DevOps

1. Vytvořte připojení služby Azure v nastavení projektu Azure DevOps:
   • Přejít na Nastavení projektu > Připojení služby
   • Vytvořte nové připojení služby Azure Resource Manager pomocí přihlašovacích údajů služebního hlavního klíče
   • Podrobné pokyny najdete v tématu Připojení k Microsoft Azure.
   • azureSubscription Aktualizujte hodnotu v YAML tak, aby odpovídala názvu připojení služby.
2. Aktualizujte ID pracovních prostorů v YAML:
   • Upravte proměnnou workspace_ids v azure-pipelines.yml
   • Nastavte ID vývojového a produkčního pracovního prostoru
   • Potvrzení a nasdílení změn do úložiště
3. Vytvořte kanál:
   • Přejít na Kanály > – nový kanál
   • Vyberte úložiště a zvolte Existující soubor YAML služby Azure Pipelines.
   • Vyberte azure-pipelines.yml
   • Podrobné pokyny najdete v tématu Vytvoření prvního kanálu.
   • Uložením a spuštěním pipeline nasadíte PBIP do Fabric.

GitHub Actions

Automatizace nasazení PBIP pomocí GitHub Actions Když se kód odešle do nakonfigurovaných větví, pracovní postup se automaticky nasadí do odpovídajícího pracovního prostoru.

Vytvořte .github/workflows/deploy.yml v úložišti:

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_ids = @{
            "dev" = "11111111-1111-1111-1111-111111111111"
            "main" = "22222222-2222-2222-2222-222222222222"
          }
          
          $environments = @{
            "dev" = "dev"
            "main" = "prod"
          }
          
          $workspace_id = $workspace_ids[$branch_name]
          $environment = $environments[$branch_name]
          
          echo "workspace_id=$workspace_id" >> $env:GITHUB_OUTPUT
          echo "environment=$environment" >> $env:GITHUB_OUTPUT
      
      - name: Azure Login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
      
      - name: Deploy PBIP to Fabric
        shell: pwsh
        run: |
          pip install fabric-cicd
          
          python -u deploy.py --workspace_id "${{ steps.workspace.outputs.workspace_id }}" --environment "${{ steps.workspace.outputs.environment }}"
          
          if ($LASTEXITCODE -ne 0) {
              Write-Error "Deployment failed with exit code: $LASTEXITCODE"
              exit $LASTEXITCODE
          }

Nakonfigurujte GitHub Actions

1. Vytvořte tajný klíč přihlašovacích údajů Azure:

   • Získejte přihlašovací údaje principálu služby ve formátu JSON:

     {
       "clientId": "<service-principal-client-id>",
       "clientSecret": "<service-principal-secret>",
       "subscriptionId": "<azure-subscription-id>",
       "tenantId": "<azure-tenant-id>"
     }
     

   • Přejděte do Nastavení úložiště GitHub > Tajemství a proměnné > Actions.
   • Přidání AZURE_CREDENTIALS pomocí výše uvedeného kódu JSON

2. Aktualizujte ID pracovního prostoru v pracovním postupu:

   • workspace_ids Upravte hashovací tabulku v kroku Nastavit proměnné pracovního prostoru v .github/workflows/deploy.yml
   • Nastavte ID vývojového a produkčního pracovního prostoru
   • Přidejte a sdílejte YAML pracovního postupu do úložiště

Související obsah

• Dokumentace k fabric-cicd
• Úložiště fabric-cicd na GitHubu
• Přehled integrace Gitu Fabric
• Plánování implementace Power BI: Správa životního cyklu obsahu