Udrul Power BI-projekter (PBIP) ved hjælp af fabric-cicd

fabric-cicd er et officielt understøttet, Microsoft-støttet open source Python-bibliotek, der tilbyder en kode-først metode for Fabric-udviklere til at deployere Fabric-elementer fra versionskontrol til arbejdsområder ved hjælp af deres kodedefinitionsformat, såsom semantiske modeller og rapporter i PBIP-filformatet. Værktøjet integreres med Fabric Git Integration, Fabric REST API'er og Fabric CLI for at muliggøre ensartede deploymentsflows på tværs af arbejdsområder.

I denne artikel lærer du, hvordan du:

• Udrul PBIP-filer manuelt fra din lokale maskine
• Parametriser PBIP-filer til miljøspecifikke konfigurationer
• Automatiser udrulninger med branch-based workspace targeting ved brug af Azure DevOps eller GitHub Actions

Lær mere om PBIP-formatet i Power BI Desktop projects (PBIP) og Fabric Git-integrationsoversigt.

Hvorfor fabric-cicd til PBIP-implementering?

fabric-cicd er specifikt designet til at implementere kildekodekontrollerede Fabric-artefakter og tilbyder flere fordele:

• Bruger Fabric native REST API'er - Bygget på officielle Microsoft Fabric API'er, hvilket sikrer kompatibilitet og langsigtet support
• Automatiseret håndtering af afhængigheder – bestemmer den korrekte installationsrækkefølge og løser afhængigheder mellem elementer (f.eks. publicering af semantiske modeller før rapporter), reduktion af manuel rækkefølge og minimering af installationsfejl
• Python-native - Sømløs integration med moderne Python-baserede DevOps-arbejdsgange
• Parameterization – indbygget understøttelse af miljøspecifikke konfigurationer (arbejdsområde-id'er, datakilder, forbindelsesstrenge)
• Udviklervenlig - Enkle Python scripts, der kan køre lokalt eller i CI/CD-pipelines
• Fleksibel udrulningskontrol – Udrul kun bestemte elementtyper (f.eks. semantiske modeller uden rapporter eller semantiske modeller med eller uden datacache), og sørg for ensartede konfigurationer som standardsider eller parametre uden manuel indgriben
• Orphan cleanup – fjerner automatisk elementer fra arbejdsområdet, der ikke længere findes i kildekontrolelementet
• Pålidelig autentificering - Bruger Azure Identity SDK med flere autentificeringsmuligheder

Forudsætninger

Før du begynder, skal du sikre dig, at du har:

• Python (version 3.9 til 3.12)
• Et Power BI Desktop-projekt gemt i PBIP-format
• Adgang til et Microsoft Fabric-arbejdsområde med bidragyderrolle

For automatiserede udrulninger skal du også bruge:

• En serviceprincipal med mindst bidragyderrollen på mål-Fabric-arbejdsområder
• Adgang til Azure DevOps eller GitHub Actions
• Dine PBIP-filer i versionskontrol (Git, Azure DevOps eller GitHub)

Hurtig start

Denne hurtigstart viser dig, hvordan du deployer et PBIP-projekt fra din lokale maskine til et Fabric-arbejdsområde.

1. Installer fabric-cicd

Åbn din terminal og installer fabric-cicd:

pip install fabric-cicd

2. Forbered dit PBIP-projekt

Sørg for, at dit PBIP-projekt indeholder de nødvendige filer. En typisk PBIP-projektstruktur:

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

For detaljeret information om nødvendige filer og formater, se Power BI Desktop projektrapportmappe og Power BI Desktop project semantic model-mappe.

3. Opret deployment-script

Opret en deploy.py fil i din projektmappe:

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. Udsend

Kør deployment-scriptet med dit workspace-navn:

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

Din browser åbner for autentificering. Efter login deployerer fabric-cicd dine PBIP-filer til målarbejdsområdet. Du ser fremskridtsbeskeder som:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Udrulningen tager typisk 20-30 sekunder afhængigt af størrelsen på din semantiske model.

Miljøspecifik parameterisering

En af fabric-cicds mest kraftfulde funktioner er muligheden for at parametrisere dine PBIP-filer til forskellige miljøer. Dette er essentielt, når dine semantiske modeller refererer til miljøspecifikke ressourcer som workspace ID'er, lakehouse-ID'er eller forbindelsesstrenge.

Eksempel: Parametriser arbejdsområde- og lakehouse-ID'er

Opret en parameter.yml fil i din projektrod for at definere miljøspecifikke værdier:

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

Når du kører python deploy.py --workspace_name "PBIP Fabric CICD Dev" --environment dev, fabric-cicd automatisk:

1. Læser parameter.yml filen
2. Finder alle instanser af find_value i dine PBIP-definitionsfiler
3. Erstatter dem med det tilsvarende miljøspecifikke replace_value
4. Udruler de modificerede definitioner til målarbejdsområdet

Automatiser udrulning

Du kan automatisere PBIP-udrulninger, så de kører, når kode er flettet ind i specifikke branchs i dit repository. Automatiseringen følger denne logik:

1. En pipeline eller arbejdsgang udløses, når kode sendes til en konfigureret gren (f.eks. dev eller main)
2. Grennavnet bestemmer målmiljøet og arbejdsområdets ID
3. Deployeringsscriptet kører automatisk med de relevante parametre
4. Dine PBIP-artefakter deployeres til det korrekte arbejdsområde for det miljø

Dette afsnit dækker opsætningstrin, der er fælles for både Azure DevOps og GitHub Actions, efterfulgt af platformspecifikke konfigurationsinstruktioner.

Opsæt

Før du konfigurerer din CI/CD-platform, skal du gennemføre disse almindelige opsætningstrin:

1. Opret en serviceprincip

Opret en serviceprincipal i Azure AD med bidragyder eller administratorrolle på dine Fabric-arbejdsområder.

2. Tilføj service principal til Fabric-arbejdsområder

1. Åbn Fabric-portalen og naviger til hvert målarbejdsområde (udvikler, produktion)
2. Gå til Workspace Settings > Administrer adgang
3. Tilføj tjenesteprincipalen med rollen som bidragyder eller administrator

3. Konfigurér grene i dit repository

Opret de branches, du vil bruge til automatisering. For eksemplerne i denne artikel:

1. Opret en dev gren til implementering af udviklingsmiljøer
2. Opret en main gren til udrulninger af produktionsmiljøer

Du kan tilpasse grennavne og tilføje flere miljøer ved at ændre arbejdsområdemappingerne i YAML-filerne.

Azure DevOps

Automatiser PBIP-udrulninger med Azure Pipelines. Når kode sendes til konfigurerede grene, deployeres pipelinen automatisk til det tilsvarende arbejdsområde.

Opret azure-pipelines.yml roden i dit repository:

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
                }

Konfigurer Azure DevOps

1. Opret en Azure serviceforbindelse i Azure DevOps projektindstillinger:
   • Gå til Projektindstillinger > Serviceforbindelser
   • Opret en ny Azure Resource Manager-serviceforbindelse ved hjælp af dine service principal-legitimationsoplysninger
   • For detaljerede instruktioner, se Forbind til Microsoft Azure
   • Opdater værdien azureSubscription i YAML, så den matcher dit serviceforbindelsesnavn
2. Opdater navnene på arbejdsområdet i YAML:
   • Rediger variablen workspace_names i azure-pipelines.yml
   • Sæt dine udvikler- og produktionsarbejdsområdenavne
   • Commit og skub ændringerne til dit repository
3. Skab pipelinen:
   • Gå til Pipelines > Ny pipeline
   • Vælg dit repository og vælg "Existing Azure Pipelines YAML file"
   • Vælg azure-pipelines.yml
   • For detaljerede instruktioner, se Opret din første pipeline
   • Gem og kør pipelinen for at deploye din PBIP til Fabric

GitHub Actions

Automatiser PBIP-udrulninger med GitHub Actions. Når kode sendes til konfigurerede branches, deployeres workflowet automatisk til det tilsvarende arbejdsområde.

Opret .github/workflows/deploy.yml i dit repository:

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
          }

Konfigurér GitHub Actions

1. Opret Azure logins hemmelighed:

   • Få dine servicechef-credentials i JSON-format:

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

   • Gå til GitHub repository Indstillinger > Hemmeligheder og variabler > Handlinger
   • Tilføj AZURE_CREDENTIALS med JSON'en ovenfor

2. Opdater navnene på arbejdsområdet i arbejdsprocessen:

   • Rediger workspace_names hashtabellen i trinnet "Sæt workspace-variable" i .github/workflows/deploy.yml
   • Sæt dine udvikler- og produktionsarbejdsområdenavne
   • Commit og push workflow-YAML til dit repository

Relateret indhold

• Fabric-CICD-dokumentation
• fabric-cicd GitHub lager
• Oversigt over Fabric Git-integration
• Power BI implementeringsplanlægning: Indholdslivscyklusstyring