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 python-Bibliothek , die von Microsoft entwickelt wurde, 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 mithilfe des PBIP-Dateiformats.

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 von Bereitstellungen mit arbeitsbereichsbasierter Zielausrichtung mithilfe von Azure DevOps oder GitHub Actions

Erfahren Sie mehr über das PBIP-Format in Power BI Desktop-Projekten (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 fabric native REST-APIs – Basierend auf offiziellen Microsoft Fabric-APIs, um Kompatibilität und langfristige Unterstützung zu gewährleisten
Python-native – Nahtlose Integration in moderne Python-basierte DevOps-Workflows
Parametrisierung: Integrierte Unterstützung für umgebungsspezifische Konfigurationen (Arbeitsbereichs-IDs, Datenquellen, Verbindungszeichenfolgen)
Entwicklerfreundliche: 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 das 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 Desktop-Projekt, 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-Aktionen
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 Power BI Desktop-Projektberichtsordner und im Power BI Desktop-Projektsemantikmodellordner.

Tipp

Um ein PBIP-Projekt zu erstellen, öffnen Sie Ihre PBIX-Datei in Power BI Desktop und speichern Sie sie mit Datei > Speichern unter > Power BI-Projekt (.pbip). Weitere Details finden Sie unter Power BI Desktop-Projekte .

3. Erstellen eines Bereitstellungsskripts

Erstellen Sie eine deploy.py 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 parameter.yml 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 python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev ausführen, wird fabric-cicd automatisch gestartet.

Liest die parameter.yml Datei
Findet alle Instanzen von find_value in Ihren PBIP-Definitionsdateien.
Ersetzt sie durch die entsprechende umgebungsspezifische replace_value
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 dev . oder main) 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-Aktionen 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 und weisen Sie ihm die Mitwirkender- oder Administratorrolle in Ihren Fabric-Arbeitsbereichen zu.

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 dev Branches für Bereitstellungen in der Entwicklungsumgebung
Erstellen Sie einen main 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 azure-pipelines.yml 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

Erstellen Sie eine Azure-Dienstverbindung in den Azure DevOps-Projekteinstellungen:
- Gehen Sie zu Project Settings > Dienstverbindungen
- Erstellen einer neuen Azure Resource Manager-Dienstverbindung mit Ihren Dienstprinzipalanmeldeinformationen
- Ausführliche Anweisungen finden Sie unter Herstellen einer Verbindung mit Microsoft Azure
- Aktualisieren Sie den azureSubscription Wert im YAML so, dass er ihrem Dienstverbindungsnamen entspricht.
Aktualisieren sie die Arbeitsbereichs-IDs im YAML:
- Bearbeiten der workspace_ids 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 aus, und wählen Sie "Vorhandene YAML-Datei für Azure-Pipelines" 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-Aktionen

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

Erstellen Sie .github/workflows/deploy.yml 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-Aktionen

Erstellen Sie den geheimen Azure-Anmeldeinformationsschlüssel:
- 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 den GitHub-Repository-Einstellungen > Geheimnisse und Variablen > Aktionen
- Fügen Sie AZURE_CREDENTIALS mit dem obigen JSON hinzu.
Aktualisieren Sie die Arbeitsbereichs-IDs im Workflow:
- Bearbeiten der workspace_ids Hashtabelle im Schritt "Arbeitsbereichsvariablen festlegen" in .github/workflows/deploy.yml
- Legen Sie Ihre Entwicklungs- und Produktionsarbeitsbereich-IDs fest
- Committen und Pushen der Workflow-YAML-Datei in Ihr Repository

Feedback

War diese Seite hilfreich?

Last updated on 2026-01-23

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-Aktionen

Konfigurieren von GitHub-Aktionen

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen