Distribuer Power BI-prosjekter (PBIP) ved bruk av fabric-cicd

fabric-cicd er et offisielt støttet, Microsoft-støttet åpen kildekode-bibliotek Python som tilbyr en kode-først-metode for Fabric-utviklere til å distribuere Fabric-elementer fra kildekontroll til arbeidsområder ved bruk av deres kodedefinisjonsformat, som semantiske modeller og rapporter med PBIP-filformatet. Verktøyet integreres med Fabric Git-integrasjon, Fabric REST API-er og Fabric CLI for å muliggjøre konsistente distribusjonsflyter på tvers av arbeidsområder.

I denne artikkelen lærer du hvordan du:

• Distribuer PBIP-filer manuelt fra din lokale maskin
• Parameteriser PBIP-filer for miljøspesifikke konfigurasjoner
• Automatiser distribusjoner med branch-based workspace targeting ved bruk av Azure DevOps eller GitHub Actions

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

Hvorfor fabric-cicd for PBIP-distribusjon?

fabric-cicd er spesielt designet for distribusjon av kildekontrollerte Fabric-artefakter og tilbyr flere fordeler:

• Bruker Fabric native REST APIer - Bygget på offisielle Microsoft Fabric API-er, som sikrer kompatibilitet og langsiktig støtte
• Automatisert avhengighetshåndtering – Bestemmer riktig distribusjonsrekkefølge og løser avhengigheter mellom elementer (som å publisere semantiske modeller før rapporter), reduserer manuell sekvensering og minimerer distribusjonsfeil
• Python-native - Sømløs integrasjon med moderne Python-baserte DevOps-arbeidsflyter
• Parameterisering – Innebygd støtte for miljøspesifikke konfigurasjoner (arbeidsområde-IDer, datakilder, tilkoblingsstrenger)
• Developer-friendly - Enkle Python skript som kan kjøres lokalt eller i CI/CD-pipelines
• Fleksibel distribusjonskontroll – Distribuer kun spesifikke objekttyper (f.eks. semantiske modeller uten rapporter, eller semantiske modeller med eller uten datacache) og sikre konsistente konfigurasjoner som standardsider eller parametere uten manuell inngripen
• Orphan-opprydding – Fjerner automatisk elementer fra arbeidsområdet som ikke lenger finnes i kildekodekontrollen
• Pålitelig autentisering - Bruker Azure Identity SDK med flere autentiseringsalternativer

Forutsetning

Før du begynner, må du sørge for at du har følgende:

• Python (versjon 3.9 til 3.12)
• Et Power BI Desktop-prosjekt lagret i PBIP-format
• Tilgang til et Microsoft Fabric-arbeidsområde med bidragsyterrolle

For automatiserte utrullinger trenger du også:

• En tjenesteprincipal med minst bidragsyter-rollen på mål-Fabric-arbeidsområder
• Tilgang til Azure DevOps eller GitHub Actions
• Dine PBIP-filer i kildekode (Git, Azure DevOps eller GitHub)

Hurtigstart

Denne hurtigstarten viser deg hvordan du distribuerer et PBIP-prosjekt fra din lokale maskin til et Fabric-arbeidsområde.

1. Installer fabric-cicd

Åpne terminalen din og installer fabric-cicd:

pip install fabric-cicd

2. Forbered ditt PBIP-prosjekt

Sørg for at PBIP-prosjektet ditt inkluderer de nødvendige filene. En typisk PBIP-prosjektstruktur:

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

For detaljert informasjon om nødvendige filer og formater, se Power BI Desktop project report folder og Power BI Desktop project semantic model-mappe.

3. Lag deployeringsskript

Opprett en fil i prosjektmappen din:

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

Kjør distribusjonsskriptet med arbeidsområdets navn:

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

Nettleseren din åpner for autentisering. Etter innlogging distribuerer fabric-cicd PBIP-filene dine til målarbeidsområdet. Du ser fremdriftsmeldinger som:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Utrullingen tar vanligvis 20-30 sekunder, avhengig av størrelsen på din semantiske modell.

Miljøspesifikk parameterisering

En av fabric-cicds kraftigste funksjoner er muligheten til å parameterisere PBIP-filene dine for ulike miljøer. Dette er essensielt når dine semantiske modeller refererer til miljøspesifikke ressurser som arbeidsområde-ID-er, lakehouse-ID-er eller tilkoblingsstrenger.

Eksempel: Parameteriser arbeidsområde- og lakehouse-ID-er

Opprett en fil i prosjektroten for å definere miljøspesifikke verdier:

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 kjører , fabric-cicd automatisk:

1. Leser parameter.yml-filen
2. Finner alle instanser av i dine PBIP-definisjonsfiler
3. Erstatter dem med den tilsvarende miljøspesifikke
4. Distribuerer de modifiserte definisjonene til målarbeidsområdet

Automatiser utrulling

Du kan automatisere PBIP-distribusjoner slik at de kjøres hver gang kode slås sammen med spesifikke grener i repositoriet ditt. Automatiseringen følger denne logikken:

1. En pipeline eller arbeidsflyt utløses når kode pushes til en konfigurert gren (f.eks. eller )
2. Grennavnet bestemmer målmiljøet og arbeidsområdets ID
3. Distribusjonsskriptet kjører automatisk med de riktige parameterne
4. Dine PBIP-artefakter distribueres til riktig arbeidsområde for det miljøet

Denne seksjonen dekker oppsettstrinn som er felles for både Azure DevOps og GitHub Actions, etterfulgt av plattformspesifikke konfigurasjonsinstruksjoner.

Definer

Før du konfigurerer CI/CD-plattformen din, fullfør du disse vanlige oppsettstegene:

1. Opprette en tjenesteprinsipp

Opprett en tjenesteprincipal i Azure AD med bidragsyter- eller administratorrolle på dine Fabric-arbeidsområder.

2. Legg til tjenesteprinsipp i Fabric-arbeidsområder

1. Åpne Fabric-portalen og naviger til hvert målarbeidsområde (utvikler, produksjon)
2. Gå til Arbeidsområdeinnstillinger Administrer tilgang
3. Legg til tjenesteprincipalen med rollen som bidragsyter eller administrator

3. Konfigurer grener i repositoriet ditt

Lag grenene du skal bruke til automatisering. For eksemplene i denne artikkelen:

1. Opprett en gren for utviklingsmiljødistribusjon
2. Lag en gren for distribusjon av produksjonsmiljøer

Du kan tilpasse grennavn og legge til flere miljøer ved å endre arbeidsområdets kartlegging i YAML-filene.

Azure DevOps

Automatiser PBIP-distribusjoner med Azure Pipelines. Når kode pushes til konfigurerte grener, distribueres pipelinen automatisk til det tilsvarende arbeidsområdet.

Opprett roten i repositoriet ditt:

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
                }

Configure Azure DevOps

1. Opprett en Azure tjenesteforbindelse i Azure DevOps prosjektinnstillinger:
   • Gå til Prosjektinnstillinger Tjenesteforbindelser
   • Opprett en ny Azure Resource Manager-tjenesteforbindelse ved å bruke dine tjenesteprincipal-legitimasjoner
   • For detaljerte instruksjoner, se Connect to Microsoft Azure
   • Oppdater verdien i YAML slik at den matcher tjenesteforbindelsens navn
2. Oppdater arbeidsområdets navn i YAML:
   • Rediger variabelen i azure-pipelines.yml
   • Sett navn på utvikler- og produksjonsarbeidsområdet ditt
   • Commit og push endringene til ditt repositorium
3. Lag pipelinen:
   • Gå til Rørledninger Ny rørledning
   • Velg ditt repository og velg "Existing Azure Pipelines YAML file"
   • Velg azure-pipelines.yml
   • For detaljerte instruksjoner, se Lag din første pipeline
   • Lagre og kjør pipelinen for å distribuere PBIP-en din til Fabric

GitHub Actions

Automatiser PBIP-distribusjoner med GitHub Actions. Når kode pushes til konfigurerte grener, distribueres arbeidsflyten automatisk til det tilsvarende arbeidsområdet.

Opprett i ditt arkiv:

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
          }

Konfigurer GitHub Actions

1. Opprett den Azure legitimasjonshemmeligheten:

   • Få dine tjenesteleder-kvalifikasjoner i JSON-format:

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

   • Gå til GitHub repository Innstillinger > Hemmeligheter og variabler > Handlinger
   • Legg til med JSON-en ovenfor

2. Oppdater arbeidsområdets navn i arbeidsflyten:

   • Rediger hashtabellen i steget «Sett arbeidsområdevariabler» i
   • Sett navn på utvikler- og produksjonsarbeidsområdet ditt
   • Commit og push arbeidsflyt-YAML til ditt repository

Relatert innhold

• Fabric-CICD-dokumentasjon
• fabric-cicd GitHub repository
• Oversikt over Fabric Git-integrasjon
• Power BI implementeringsplanlegging: Innholdslivssyklusstyring