Bereitstellen von Power BI Projekten (PBIP) mithilfe von fabric-cicd

Von Bedeutung

Power BI Desktop-Projekte befinden sich derzeit in der Vorschau.

fabric-cicd ist eine offiziell unterstützte, von Microsoft gesicherte Open Source-Python-Bibliothek, die eine Code-first-Methode für Fabric-Entwickler bereitstellt, um Fabric-Elemente aus der Quellcodeverwaltung in Arbeitsbereichen mithilfe ihres Codedefinitionsformats bereitzustellen, z. B. semantische Modelle und Berichte im PBIP-Dateiformat. Das Tool ist in Fabric Git Integration, Fabric REST-APIs und Fabric CLI integriert, um konsistente Bereitstellungsabläufe für alle Arbeitsbereiche zu ermöglichen.

In diesem Artikel erfahren Sie, wie Sie:

Manuelles Bereitstellen von PBIP-Dateien von Ihrem lokalen Computer
Parametrisieren von PBIP-Dateien für umgebungsspezifische Konfigurationen
Automatisieren Sie Bereitstellungen mit verzweigungsbasierter Zieladressierung von Arbeitsbereichen mithilfe von Azure DevOps oder GitHub Actions

Erfahren Sie mehr über das PBIP-Format in Power BI Desktopprojekten (PBIP) und Fabric Git Integrationsübersicht.

Warum fabric-cicd für die PBIP-Bereitstellung?

fabric-cicd wurde speziell für die Bereitstellung von quellcodegesteuerten Fabric-Artefakten entwickelt und bietet mehrere Vorteile:

Verwendet native REST-APIs von Fabric – Basiert auf offiziellen Microsoft Fabric-APIs, um Kompatibilität und langfristige Unterstützung sicherzustellen
Automatisierte Abhängigkeitsbehandlung – Bestimmt die richtige Bereitstellungsreihenfolge und löst Abhängigkeiten zwischen Elementen (z. B. veröffentlichen von semantischen Modellen vor Berichten), reduzierung der manuellen Sequenzierung und Minimierung von Bereitstellungsfehlern
Python-native – Nahtlose Integration in moderne Python-basierte DevOps-Workflows
Parametrisierung: Integrierte Unterstützung für umgebungsspezifische Konfigurationen (Arbeitsbereichs-IDs, Datenquellen, Verbindungszeichenfolgen)
Developer-friendly: Einfache Python Skripts, die lokal oder in CI/CD-Pipelines ausgeführt werden können
Flexible Bereitstellungskontrolle: Stellen Sie nur bestimmte Elementtypen bereit (z. B. semantische Modelle ohne Berichte oder semantische Modelle mit oder ohne Datencache), und stellen Sie konsistente Konfigurationen wie Standardseiten oder Parameter ohne manuelle Eingriffe sicher.
Verwaiste Objekte bereinigen: Entfernt automatisch Elemente aus dem Arbeitsbereich, die nicht mehr im Quellcodeverwaltungssystem vorhanden sind.
Zuverlässige Authentifizierung: Verwendet Azure Identity SDK mit mehreren Authentifizierungsoptionen.

Hinweis

Vollständige Dokumentation finden Sie in der Fabric-cicd-Dokumentation.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

Python (Version 3.9 bis 3.12)
Ein Power BI Desktopprojekt, das im PBIP-Format gespeichert ist
Zugriff auf einen Microsoft Fabric Arbeitsbereich mit Mitwirkenderrolle

Für automatisierte Bereitstellungen benötigen Sie außerdem Folgendes:

Ein Dienstprinzipalprofil mit mindestens der Rolle "Mitwirkender" in den Ziel-Fabric-Arbeitsbereichen
Zugriff auf Azure DevOps oder GitHub Actions
Ihre PBIP-Dateien in der Quellcodeverwaltung (Git, Azure DevOps oder GitHub)

Schnellstart

In diesem Schnellstart wird gezeigt, wie Sie ein PBIP-Projekt von Ihrem lokalen Computer in einem Fabric-Arbeitsbereich bereitstellen.

1. Installieren Sie fabric-cicd

Öffnen Sie Ihr Terminal, und installieren Sie fabric-cicd:

pip install fabric-cicd

2. Vorbereiten Ihres PBIP-Projekts

Stellen Sie sicher, dass Ihr PBIP-Projekt die erforderlichen Dateien enthält. Eine typische PBIP-Projektstruktur:

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

Ausführliche Informationen zu erforderlichen Dateien und Formaten finden Sie im Ordner Power BI Desktopprojektbericht und Power BI Desktopprojektsemantikmodellordner.

Tipp

Um ein PBIP-Projekt zu erstellen, öffnen Sie Ihre PBIX-Datei in Power BI Desktop, und speichern Sie sie mit File > Save As > Power BI Project (.pbip). Weitere Informationen finden Sie unter Power BI Desktopprojekte.

3. Erstellen eines Bereitstellungsskripts

Erstellen Sie eine Datei in Ihrem Projektverzeichnis:

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

Führen Sie das Bereitstellungsskript mit Ihrer Arbeitsbereichs-ID aus:

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

Ihr Browser wird zur Authentifizierung geöffnet. Nach der Anmeldung stellt fabric-cicd Ihre PBIP-Dateien im Zielarbeitsbereich bereit. Statusmeldungen werden wie folgt angezeigt:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Die Bereitstellung dauert in der Regel 20 bis 30 Sekunden, abhängig von der Größe Des semantischen Modells.

Hinweis

Wenn Sie ein semantisches Modell zum ersten Mal mit Datenquellen bereitstellen, müssen Sie die Datenquellenanmeldeinformationen im Fabric-Portal manuell konfigurieren. Gehen Sie zu Arbeitsbereich Semantikmodell Einstellungen Datenquellenanmeldeinformationen. Nachfolgende Bereitstellungen verwenden die gespeicherten Anmeldeinformationen wieder.

Umgebungsspezifische Parametrisierung

Eines der leistungsstärksten Features von fabric-cicd ist die Möglichkeit, Ihre PBIP-Dateien für verschiedene Umgebungen zu parametrisieren. Dies ist wichtig, wenn Ihre semantischen Modelle auf umgebungsspezifische Ressourcen wie Arbeitsbereichs-IDs, Lakehouse-IDs oder Verbindungszeichenfolgen verweisen.

Beispiel: Parametrisierung von Arbeitsbereichs- und Lakehouse-IDs

Erstellen Sie eine Datei im Projektstamm, um umgebungsspezifische Werte zu definieren:

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

Wenn Sie ausführen, wird fabric-cicd automatisch gestartet.

Liest die parameter.yml Datei
Findet alle Instanzen von in Ihren PBIP-Definitionsdateien.
Ersetzt sie durch die entsprechende umgebungsspezifische
Stellt die geänderten Definitionen im Zielarbeitsbereich bereit.

Automatisieren der Bereitstellung

Sie können PBIP-Bereitstellungen so automatisieren, dass sie immer dann ausgeführt werden, wenn Code in festgelegten Verzweigungen in Ihrem Repository zusammengeführt wird. Die Automatisierung folgt dieser Logik:

Eine Pipeline oder ein Workflow wird ausgelöst, wenn Code an eine konfigurierte Verzweigung (z. B . oder ) weitergeleitet wird.
Der Branch-Name bestimmt die Zielumgebung und Arbeitsbereichs-ID.
Das Bereitstellungsskript wird automatisch mit den entsprechenden Parametern ausgeführt.
Ihre PBIP-Artefakte werden in den richtigen Arbeitsbereich dieser Umgebung bereitgestellt.

In diesem Abschnitt werden die Einrichtungsschritte behandelt, die sowohl für Azure DevOps als auch für GitHub Actions gelten, gefolgt von plattformspezifischen Konfigurationsanweisungen.

Einrichten

Führen Sie vor dem Konfigurieren Ihrer CI/CD-Plattform die folgenden allgemeinen Einrichtungsschritte aus:

1. Erstellen eines Dienstprinzipals

Erstellen Sie einen Dienstprinzipal in Azure AD mit Mitwirkender- oder Administratorrolle in Ihren Fabric-Arbeitsbereichen.

2. Hinzufügen des Dienstprinzipals zu Fabric-Arbeitsbereichen

Öffnen Sie das Fabric-Portal, und navigieren Sie zu jedem Zielarbeitsbereich (Dev, prod)
Öffnen Sie Arbeitsbereichseinstellungen und verwalten Sie den Zugriff
Hinzufügen des Service Principals mit der Rolle "Mitwirkender" oder "Administrator"

Hinweis

Dienstprinzipale müssen auf Mandantenebene freigeschaltet sein, um Fabric-APIs verwenden zu können. Weitere Informationen finden Sie unter Dienstprinzipal kann öffentliche Fabric-APIs aufrufen.

3. Konfigurieren von Filialen in Ihrem Repository

Erstellen Sie die Verzweigungen, die Sie für die Automatisierung verwenden. Für die Beispiele in diesem Artikel:

Erstellen eines Branches für Bereitstellungen in der Entwicklungsumgebung
Erstellen Sie einen Branch für die Bereitstellungen in der Produktionsumgebung

Sie können Verzweigungsnamen anpassen und weitere Umgebungen hinzufügen, indem Sie die Arbeitsbereichszuordnungen in den YAML-Dateien ändern.

Azure DevOps

Automatisieren Sie PBIP-Bereitstellungen mit Azure Pipelines. Wenn Code an konfigurierte Branches übertragen wird, wird die Pipeline automatisch für den entsprechenden Workspace bereitgestellt.

Erstellen Sie im Root-Verzeichnis Ihres Repositories.

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
                }

Konfigurieren von Azure DevOps

Create an Azure service connection in Azure DevOps Projekteinstellungen:
- Gehen Sie zu Project Settings Dienstverbindungen
- Erstellen Sie eine neue Azure Resource Manager-Dienstverbindung mithilfe Ihrer Dienstprinzipal-Anmeldeinformationen
- Ausführliche Anweisungen finden Sie unter Verbinden mit Microsoft Azure
- Aktualisieren Sie den Wert im YAML so, dass er ihrem Dienstverbindungsnamen entspricht.
Aktualisieren sie die Arbeitsbereichs-IDs im YAML:
- Bearbeiten der Variablen in azure-pipelines.yml
- Legen Sie Ihre Entwicklungs- und Produktionsarbeitsbereich-IDs fest
- Commit und Pushen der Änderungen an Ihr Repository
Erstellen Sie die Pipeline:
- Gehe zu Pipelines Neue Pipeline
- Wählen Sie Ihr Repository und dann "Vorhandene Azure Pipelines YAML-Datei" aus.
- Wählen Sie azure-pipelines.yml
- Ausführliche Anweisungen finden Sie unter Erstellen Ihrer ersten Pipeline
- Speichern Sie und führen Sie die Pipeline aus, um Ihre PBIP in Fabric bereitzustellen.

GitHub Actions

Automatisieren Sie PBIP-Bereitstellungen mit GitHub Actions. Wenn Code an konfigurierte Branches übertragen wird, wird der Workflow automatisch für den entsprechenden Arbeitsbereich deployt.

Erstellen Sie in Ihrem 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_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
          }

Konfigurieren von GitHub Actions

Azure-Anmeldeinformationen-Geheimnis erstellen:
- Rufen Sie Ihre Dienstprinzipalanmeldeinformationen im JSON-Format ab:
```
{
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "subscriptionId": "<azure-subscription-id>",
  "tenantId": "<azure-tenant-id>"
}
```
- Wechseln Sie zu GitHub Repositoryeinstellungen > Geheime Schlüssel und Variablen > Aktionen
- Fügen Sie mit dem obigen JSON hinzu.
Aktualisieren Sie die Arbeitsbereichs-IDs im Workflow:
- Bearbeiten der Hashtabelle im Schritt "Arbeitsbereichsvariablen festlegen" in
- Legen Sie Ihre Entwicklungs- und Produktionsarbeitsbereich-IDs fest
- Committen und Pushen der Workflow-YAML-Datei in Ihr Repository

Fabric-cicd-Dokumentation
fabric-cicd GitHub Repository
Übersicht über die Fabric Git-Integration
Power BI Implementierungsplanung: Content Lifecycle Management

Feedback

War diese Seite hilfreich?

Last updated on 2026-03-06

Freigeben über

Bereitstellen von Power BI Projekten (PBIP) mithilfe von fabric-cicd

Warum fabric-cicd für die PBIP-Bereitstellung?

Voraussetzungen

Schnellstart

1. Installieren Sie fabric-cicd

2. Vorbereiten Ihres PBIP-Projekts

3. Erstellen eines Bereitstellungsskripts

4. Einsatz

Umgebungsspezifische Parametrisierung

Beispiel: Parametrisierung von Arbeitsbereichs- und Lakehouse-IDs

Automatisieren der Bereitstellung

Einrichten

1. Erstellen eines Dienstprinzipals

2. Hinzufügen des Dienstprinzipals zu Fabric-Arbeitsbereichen

3. Konfigurieren von Filialen in Ihrem Repository

Azure DevOps

Konfigurieren von Azure DevOps

GitHub Actions

Konfigurieren von GitHub Actions

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen