🚀 CI/CD für Microsoft Fabric mit Azure DevOps & dem `fabric-cicd` Python-Paket

In diesem Lernprogramm verwenden Sie die fabric-cicd Python-Bibliothek, um geänderte Elemente (z. B. ein bestimmtes Notizbuch) vom Entwicklungsarbeitsbereich in den Testarbeitsbereich zu überführen und schließlich in die Produktionsumgebung.

1. Szenarioübersicht

Treffen Sie Alex – einen Dev Lead, der mit Microsoft Fabric arbeitet.

Das Team von Alex erstellt Notizbücher, Daten-Pipelines, semantische Modelle und Berichte in einem Entwicklungs-Fabric-Arbeitsbereich. Wenn Features bereit sind, muss Alex geänderte Elemente (z. B. ein bestimmtes Notizbuch) vom Entwicklerarbeitsbereich zum Testarbeitsbereich und schließlich zum Produktheraufstufen.

Die Herausforderung

Alex' Notebooks verwenden den %%configure magischen Befehl, um sich mit einem bestimmten Lakehouse zu verbinden. Dies bedeutet, dass die Notizbuchdefinitionen hartcodierte GUIDs – Arbeitsbereichs-IDs, Lakehouse-IDs und SQL-Endpunkt-IDs – enthalten, die in jeder Umgebung unterschiedlich sind.

Was Alex erwartet

Anforderung	Lösung
Zusammengeführte geänderte Elemente in den Branch bereitstellen	`fabric-cicd` `publish_all_items()` stellt alle In-Scope-Elementtypen bereit.
Explizite Bereichsdefinition für Elementtypen	Pipelineparameter `items_in_scope` – Sie müssen angeben, welche Elementtypen bereitgestellt werden sollen.
Genehmigungsworkflow vor der Bereitstellung für Test/Produktivbetrieb	ADO-Umgebungen mit Freigabegates
Automatische GUID-Ersetzung (Dev → Test/Prod)	`fabric-cicd` Parameterdateien (`parameter.yml`)
Sichere Verwaltung von Anmeldeinformationen	Azure Key Vault + ADO-Variablengruppen
Automatisierter Trigger beim Zusammenführen zu Branch	ADO-Pipeline mit Verzweigungstriggern

Die Tools

Werkzeug	Zweck
Azure DevOps (ADO)	CI/CD-Orchestrierung, Git-Hosting, Genehmigungen
`fabric-cicd` Python-Paket	Open-Source-Bibliothek von Microsoft zum Bereitstellen von Fabric-Elementen
Azure Key Vault	Speichert Zugangsdaten für Dienstprinzipal sicher
Service Principal (SPN)	Authentifiziert sich für die Fabric-REST-API

2. Architekturdiagramm

Das folgende Diagramm veranschaulicht den Fluss des Lernprogramms.

3. Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Folgendes vorhanden ist:

#	Voraussetzung	Einzelheiten
1	Azure DevOps Organization & Project	Ein Projekt mit aktivierten Repos und Pipelines
2	Microsoft Fabric-Arbeitsbereiche	Drei Arbeitsbereiche – jeweils für Entwicklungs-, Test- und Prod-Bereiche
3	Dienstprinzipal (SPN)	Eine Entra-ID (Azure AD) App-Registrierung mit einem geheimen Clientschlüssel
4	SPN-Berechtigungen in Fabric	Der SPN muss in jedem Fabric-Zielarbeitsbereich als Mitglied oder Administrator hinzugefügt werden.
5	Azure Key Vault	Ein Schlüsseltresor mit drei geheimen Schlüsseln: Mandanten-ID, Client-ID und geheimer Clientschlüssel
6	Fabric Git-Integration	Der Dev-Arbeitsbereich muss mit der `dev` Verzweigung Ihres ADO-Repositorys verbunden sein.
7	Python 3.12+	Wird im Pipeline-Agent zum Ausführen des Bereitstellungsskripts verwendet
8	`fabric-cicd` Python-Paket	Open-Source-Bereitstellungsbibliothek von Microsoft (PyPI)
9	Fabric-Administratoreinstellung für SPN	Ein Fabric-Administrator muss "Dienstprinzipale können Fabric-APIs verwenden" im Fabric Admin Portal unter Mandanteneinstellungen aktivieren.

💡 Tipp: Um den Dienstprinzipalzugriff in Fabric zu aktivieren, muss ein Fabric-Administrator "Dienstprinzipale können Fabric-APIs verwenden" im Fabric Admin Portal unter Mandanteneinstellungen aktivieren.

Herunterladen der Quelldateien

Erstellen Sie einen Fork des Fabric-samples-Repositorys für Ihr GitHub-Konto.
Klonen Sie Ihr Fork auf Ihren lokalen Rechner.

git clone https://github.com/<your-account>/fabric-samples.git
cd fabric-samples

4. Anfängliches Azure DevOps-Setup

In diesem Abschnitt werden alle Azure DevOps-Ressourcen erläutert, die Sie konfigurieren müssen, bevor die Pipeline ausgeführt werden kann.

4.1 Azure Key Vault-Integration

Ihre Dienstprinzipalanmeldeinformationen (Mandanten-ID, Client-ID und Geheimer Schlüssel) sollten niemals im Nur-Text gespeichert werden. Speichern Sie sie stattdessen im Azure Key Vault.

Schritte zum Einrichten von Azure Key Vault

Erstellen Sie einen Key Vault im Azure-Portal (oder verwenden Sie eine vorhandene).
Fügen Sie drei geheime Schlüssel hinzu:

Geheimer Name	Description	Beispielwert
`aztenantid`	Ihre Azure AD/Entra ID-Mandanten-ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`azclientid`	Die Anwendungs-ID des Dienstprinzipals (Client)	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`azspnsecret`	Der Clientschlüsselwert des Dienstprinzipals	`your-secret-value`

Zugriff gewähren: Die ADO-Dienstverbindung (oder die ADO-Projektidentität) muss über Berechtigungen zum Abrufen und Auflisten von geheimen Schlüsseln in der Zugriffsrichtlinien des Schlüsseltresors (oder der RBAC-Rolle Key Vault Secrets User) verfügen.

4.2 Variable-Gruppe: `fabric_cicd_group_sensitive`

Diese Variablengruppe ist mit Azure Key Vault verknüpft, was bedeutet, dass die geheimen Werte zur Laufzeit abgerufen und nie in der ADO-Benutzeroberfläche verfügbar gemacht werden.

Schritte zum Erstellen

Navigieren Sie zu Pipelines → Library in Ihrem ADO-Projekt.
Klicken Sie auf +Variablengruppe.
Benennen Sie ihn: fabric_cicd_group_sensitive
Aktivieren Sie "Geheimnisse aus einem Azure Key Vault als Variablen verknüpfen".
Wählen Sie Ihr Azure-Abonnement und Key Vault aus.
Klicken Sie auf +Hinzufügen , und wählen Sie die drei geheimen Schlüssel aus:

aztenantid
azclientid
azspnsecret

Klicken Sie auf Speichern.

Variable	Quelle	Empfindlich?
`aztenantid`	Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel)	✅ Ja
`azclientid`	Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel)	✅ Ja
`azspnsecret`	Azure Key Vault (ein Dienst zur sicheren Verwaltung kryptografischer Schlüssel)	✅ Ja

Von Bedeutung

Da diese Variablen mit Key Vault verknüpft sind, werden sie in der Pipeline YAML als $(aztenantid), $(azclientid)und $(azspnsecret). Sie werden automatisch in Protokollen maskiert.

4.3 Variablengruppe: `fabric_cicd_group_non_sensitive`

Diese Variablengruppe speichert nicht geheime Konfigurationswerte, insbesondere die Arbeitsbereichsnamen pro Umgebung und den Git-Verzeichnispfad.

Schritte zum Erstellen

Navigieren Sie zu Pipelines → Library in Ihrem ADO-Projekt.
Klicken Sie auf +Variablengruppe.
Benennen Sie ihn: fabric_cicd_group_non_sensitive
Fügen Sie die folgenden Variablen hinzu:

Variablenname	Wert	Description
`devWorkspaceName`	`MyProject-Dev`	Name des DEV Fabric-Arbeitsbereichs
`testWorkspaceName`	`MyProject-Test`	Name des TEST Fabric-Arbeitsbereichs
`prodWorkspaceName`	`MyProject-Prod`	Name des PROD Fabric-Arbeitsbereichs
`gitDirectory`	`fabric`	Der Ordner in Ihrem Repository, der die Fabric-Elementdefinitionen enthält

Klicken Sie auf Speichern.

💡 Funktionsweise im Code: Das Python-Skript liest diese Werte mithilfe von os.environ. Wenn Sie beispielsweise auf test bereitstellen, erstellt das Skript den Variablennamen testWorkspaceName, konvertiert ihn in Großbuchstaben (TESTWORKSPACENAME), und liest ihn aus der Umgebung, da ADO nicht vertrauliche Variablengruppenwerte automatisch als Umgebungsvariablen in Großbuchstaben einfügt.

4.4 ADO-Umgebungen und Genehmigungsgates

Mit ADO-Umgebungen können Sie manuelle Genehmigungsprüfungen hinzufügen, bevor die Bereitstellungen fortgesetzt werden. Dies ist entscheidend für die Beförderung zu test und prod.

Schritte zum Erstellen von Umgebungen

Navigieren Sie zu Pipelines → Umgebungen in Ihrem ADO-Projekt.
Erstellen Sie drei Umgebungen mit genauen Namen , die Ihren Verzweigungsnamen entsprechen:

Umgebungsname	Genehmigung erforderlich?	Genehmigende Personen
`dev`	❌ Nein (automatische Bereitstellung)	—
`test`	✅ Ja	Admin-Team / Leitung
`prod`	✅ Ja	Admin-Team / Leitung

Klicken Sie für test und prod auf die Umgebung → ⋮ (Weitere Optionen) → Genehmigungen und Überprüfungen → + Prüfung hinzufügen → Genehmigungen.
Fügen Sie die erforderlichen Genehmiger hinzu.

Beispiel für die Umgebungsstatusansicht:

Umwelt	Der Status
Entwickler	✅ #20260211.1 auf fabric_cicd_pipeline
test	✅ #20260216.8 auf fabric_cicd_pipeline
prod	✅ #20260131.12 auf fabric_cicd_pipeline

💡 Warum Umgebungen? Die Pipeline YAML verwendet deployment Aufträge mit environment: $(target_env). Wenn target_env oder prod ist, hält ADO die Pipeline an und wartet, bis die konfigurierten Genehmiger genehmigt haben, bevor sie fortfahren.

4.5 Git Branch-Strategie

Die Verzweigungsstrategie ist von zentraler Bedeutung für diese CI/CD-Einrichtung. Sie benötigen drei langlebige Zweige:

Die wichtigsten Punkte

Branch	Mit Fabric-Arbeitsbereich verbunden?	Zweck
`dev`	✅ Ja-synchronisiert mit dem DEV-Arbeitsbereich	Quelle der Wahrheit. Änderungen, die im DEV-Arbeitsbereich vorgenommen wurden, werden hier übernommen.
`test`	❌ Nein	Empfängt höhergestufte Elemente über die PR-Zusammenführung. Verfolgt, was für TEST bereitgestellt wird.
`prod`	❌ Nein	Empfängt höhergestufte Elemente über die PR-Zusammenführung. Verfolgt, was für PROD bereitgestellt wird.

Warum nur `dev` verbunden ist

Die Git-Integration von Fabric synchronisiert Arbeitsbereichselemente bidirektional mit einer Git-Verzweigung.
Die test Und prod Verzweigungen sind nicht mit Arbeitsbereichen verbunden, da das fabric-cicd Paket die Bereitstellung direkt über die Fabric-REST-API verarbeitet.
Diese Verzweigungen dienen als Aufzeichnung der genauen Elementversionen, die für jede Umgebung bereitgestellt wurden.

4.6 ADO-Pipeline-Setup

Erstellen Sie eine Pipeline in ADO, die auf die YAML-Datei in Ihrem Repository verweist.

Steps

Navigieren Sie zu Pipelines → Pipelines → Neue Pipeline.
Wählen Sie Azure Repos Git aus, und wählen Sie Ihr Repository aus.
Wählen Sie vorhandene YaML-Datei für Azure-Pipelines aus.
Zeigen Sie auf den Pfad: Deploy-To-Fabric.yml (oder wo Sie ihn platziert haben).
Benennen Sie die Pipeline: fabric_cicd_pipeline.
Stellen Sie unter Pipelineberechtigungen sicher, dass sie Zugriff auf Folgendes hat:

Beide Variablengruppen (fabric_cicd_group_sensitive und fabric_cicd_group_non_sensitive)
Alle drei Umgebungen (dev, test, prod)

Speichern (noch nicht ausgeführt).

⚠– Berechtigungstipp: Wenn die Pipeline zum ersten Mal ausgeführt wird, fordert ADO Sie möglicherweise auf, den Zugriff auf die variablen Gruppen und Umgebungen zu autorisieren. Ein ADO-Administrator kann diese unter Pipeline-→-Einstellungen vorab autorisieren.

5. Code Deep Dive: ADO Pipeline YAML

Datei:Deploy-To-Fabric.yml-befindet sich im GitHub-Repository, das zuvor heruntergeladen wurde.

Unten sehen Sie die vollständige Pipeline mit Anmerkungen zu jeder Zeile.

# ──────────────────────────────────────────────────────────────
# TRIGGER: Runs automatically when code is pushed to dev, test, or prod
# Only triggers when changes are in the "fabric/" folder
# ──────────────────────────────────────────────────────────────
trigger:
 branches:
 include: [test, prod]
 paths:
 include:
  - fabric/**

🔍 Erklärungs-Auslöser

Die Pipeline löst automatisch einen Commit für die test Oder prod Verzweigungen aus. Er wird nicht ausgelöst, wenn dev verbunden ist, da dev die Quellverzweigung ist, die mit der Fabric Git-Integration verbunden ist.
Der paths Filter stellt sicher, dass er nur ausgelöst wird , wenn Dateien innerhalb des fabric/ Verzeichnisses geändert werden, wodurch unnötige Ausführungsvorgänge an Dokumentation, Skripts usw. verhindert werden.
In der Praxis: Wenn ein PR von dev nach test zusammengeführt wird, landet der Merge-Commit auf dem test Zweig und löst die Pipeline für die TEST-Umgebung aus.

# ──────────────────────────────────────────────────────────────
# PARAMETERS: Runtime input-which Fabric item types to deploy
# ──────────────────────────────────────────────────────────────
parameters:
 - name: items_in_scope
 displayName: Enter Fabric items to be deployed
 type: string
 default: '["Notebook","DataPipeline","Lakehouse","SemanticModel","Report","VariableLibrary"]'

🔍 Erläuterungsparameter

Dadurch wird ein Laufzeitparameter definiert, der steuert, welche Fabric-Elementtypen für die Bereitstellung vorgesehen sind.
Wenn dieser Parameter nicht angegeben ist, werden alle vom Paket unterstützten fabric-cicd Elementtypen bereitgestellt.
Dies dient auch als Option für die selektive Bereitstellung, zum Beispiel können Sie nur ["Notebook"] übergeben, um ausschließlich Notizbücher bereitzustellen.

⚠– Warnung zur selektiven Bereitstellung: Wenn Sie sich für eine selektive Bereitstellung einschränkenitems_in_scope, sollten Sie das Python-Skript nicht aufrufenunpublish_all_orphan_items(), da elemente der typen entfernt werden, die im items_in_scopeArbeitsbereich angegeben sind, aber nicht in der Release-Verzweigung vorhanden sind. Wenn Sie beispielsweise nur ["Notebook"] bereitstellen und Notizbücher im Arbeitsbereich vorhanden sind, die sich nicht im Branch befinden, werden sie gelöscht, obwohl sie möglicherweise noch gültig sind. Elemente anderer Typen (z. B. Pipelines, Berichte usw.) werden nicht entfernt. Verwenden Sie unpublish_all_orphan_items() nur, wenn die Verzweigung den vollständigen gewünschten Zustand der Elementtypen im Geltungsbereich darstellt.

# ──────────────────────────────────────────────────────────────
# VARIABLES: Environment-specific config & secrets
# ──────────────────────────────────────────────────────────────
variables:
 - name: target_env
 value: ${{ replace(variables['Build.SourceBranch'], 'refs/heads/', '') }}
 - group: fabric_cicd_group_sensitive
 - group: fabric_cicd_group_non_sensitive

🔍 Erklärvariable

Variable	Funktionsweise
`target_env`	Extrahiert den Verzweigungsnamen dynamisch aus `Build.SourceBranch`. Beispiel: `refs/heads/test` → `test`. Diese einzelne Variable steuert das gesamte umgebungsbewusste Verhalten.
`fabric_cicd_group_sensitive`	Zieht `aztenantid`, `azclientid` und `azspnsecret` zur Laufzeit aus Azure Key Vault.
`fabric_cicd_group_non_sensitive`	Ruft Arbeitsbereichsnamen und `gitDirectory` als einfache Umgebungsvariablen ab.

# ──────────────────────────────────────────────────────────────
# STAGES & JOBS: Single deployment stage
# ──────────────────────────────────────────────────────────────
stages:
 - stage: DeployToFabric
 displayName: "Deploy to Fabric Workspace"
 jobs:
  - deployment: Deployment
  displayName: "Deploy Resources"
  environment: $(target_env)  # ◀── THIS triggers the approval gate!
  pool:
   name: Azure Pipelines
  strategy:
   runOnce:
   deploy:
    steps:

🔍 Erklärung-Deployment-Job

Element	Zweck
`deployment:` (nicht `job:`)	Für die Verwendung von ADO-Umgebungen ist ein Bereitstellungsauftrag erforderlich. Es ermöglicht Genehmigungs-Checkpoints, Bereitstellungsverlauf und Audit-Protokolle.
`environment: $(target_env)`	Ordnet der ADO-Umgebung zu, die dem Verzweigungsnamen (`dev`, `test`, oder `prod`) entspricht. Wenn Genehmigungen für diese Umgebung konfiguriert sind, wird die Pipeline hier bis zur Genehmigung angehalten .
`strategy: runOnce`	Führt die Bereitstellungsschritte genau einmal aus (im Gegensatz zu Canary- oder Rolling-Strategien).

    steps:
    # Step 1: Checkout the source code
    - checkout: self

    # Step 2: Set up Python 3.12
    - task: UsePythonVersion@0
     inputs:
     versionSpec: '3.12'
     addToPath: true
     displayName: "Set up Python Environment"

    # Step 3: Install dependencies
    - script: |
     python -m pip install --upgrade pip
     pip install fabric-cicd
     displayName: "Install Fabric CICD Library"

    # Step 4: Run the deployment script
    - task: PythonScript@0
     inputs:
     scriptSource: 'filePath'
     scriptPath: '.deploy/deploy-to-fabric.py'
     arguments: >-
      --aztenantid $(aztenantid)
      --azclientid $(azclientid)
      --azspsecret $(azspnsecret)
      --items_in_scope ${{ parameters.items_in_scope }}
      --target_env $(target_env)
     displayName: 'Run deployment using fabric-cicd'

🔍 Erklärungsschritte

Schritt	Funktionsweise
Kasse	Klont das Repository, sodass die Pipeline Zugriff auf die Fabric-Elementdefinitionen im `fabric/` Ordner und auf das Bereitstellungsskript hat.
Python-Setup	Installiert Python 3.12 auf dem Build-Agent. Das `fabric-cicd` Paket erfordert Python 3.10+.
Abhängigkeiten installieren	Installiert das `fabric-cicd` Paket von PyPI. Dies ist die offizielle Bibliothek von Microsoft für automatisierte Fabric-Bereitstellungen.
Skript ausführen	Führt das Python-Bereitstellungsskript aus und übergibt alle erforderlichen Argumente: SPN-Anmeldeinformationen (aus Key Vault), die Liste der bereitzustellenden Elementtypen und den Namen der Zielumgebung.

⚠• Sicherheitshinweis: Die $(aztenantid)Werte $(azclientid)und Werte $(azspnsecret) werden aus der Gruppe der mit Key Vault verknüpften Variablen abgerufen. Sie werden automatisch in Pipelineprotokollen maskiert – sie werden anstelle der tatsächlichen Werte angezeigt *** .

6. Code Deep Dive: Python-Bereitstellungsskript

Datei:.deploy/deploy-to-fabric.py – befindet sich im GitHub-Repository, das zuvor heruntergeladen wurde.

Dies ist das Herzstück der Bereitstellung. Sehen wir uns die einzelnen Abschnitte an.

6.1 Importe & Abhängigkeiten

import os, argparse, requests, ast
from fabric_cicd import (
 FabricWorkspace,
 publish_all_items,
 unpublish_all_orphan_items,
 change_log_level,
 append_feature_flag,
)
from azure.identity import ClientSecretCredential

Importieren	Zweck
`os`	Access-Umgebungsvariablen (nicht vertrauliche Variablengruppenwerte)
`argparse`	Analysieren von Befehlszeilenargumenten, die von der Pipeline übergeben werden
`requests`	Ausführen von HTTP-Aufrufen an die Fabric-REST-API (für die Arbeitsbereichs-ID-Suche)
`fabric_cicd`	Microsoft-Bibliothek – übernimmt die anspruchsvollen Aufgaben bei der Bereitstellung von „Fabric“-Elementen
`ClientSecretCredential`	Azure Identity-Bibliothek – authentifiziert sich mit SPN-Anmeldeinformationen

6.2 Arbeitsbereichs-ID-Suchfunktion

def get_workspace_id(p_ws_name, p_token):
 url = "https://api.fabric.microsoft.com/v1/workspaces"
 headers = {
  "Authorization": f"Bearer {p_token.token}",
  "Content-Type": "application/json"
 }
 response = requests.get(url, headers=headers)
 ws_id = ''
 if response.status_code == 200:
  workspaces = response.json()["value"]
  for workspace in workspaces:
   if workspace["displayName"] == p_ws_name:
    ws_id = workspace["id"]
    return workspace["id"]
  if ws_id == '':
   return f"Error: Workspace {p_ws_name} could not found."
 else:
  return f"Error: {response.status_code}, {response.text}"

Was dies bewirkt:

Ruft die Fabric-REST-API (GET /v1/workspaces) auf, um alle Arbeitsbereiche auflisten, auf die der SPN Zugriff hat.
Sucht nach einem Arbeitsbereich, dessen displayName Name dem Zielarbeitsbereich entspricht.
Gibt die Arbeitsbereich-GUID zurück, wenn sie gefunden wurde, oder eine Fehlermeldung, wenn nicht.

💡 Warum wird die Arbeitsbereichs-ID nicht hartcodiert? Durch die dynamische Suche nach dem Namen ist das Skript robuster gegenüber der Neuerstellung von Arbeitsbereichen und vermeidet das Speichern von GUIDs in der Variablengruppe.

6.3 Featurekennzeichnungen & Protokollierung

append_feature_flag("enable_shortcut_publish")
change_log_level("DEBUG")

Setting	Zweck
`enable_shortcut_publish`	Ermöglicht die Bereitstellung von Lakehouse-Verknüpfungen – ein Feature, das über ein Funktionsflag in `fabric-cicd` aktiviert werden kann.
`DEBUG` Protokollebene	Bietet ausführliche Ausgabe während der Bereitstellung – sehr hilfreich für die Fehlerbehandlung. Das `"DEBUG"` Argument ist optional – Wenn `change_log_level()` ohne dieses aufgerufen wird, wird eine ausführlichere Protokollierung aktiviert. Entfernen Sie die change_log_level(), wenn Keine Debugprotokolle erforderlich sind.

6.4 Argumentanalyse

parser = argparse.ArgumentParser(description='Process Azure Pipeline arguments.')
parser.add_argument('--aztenantid', type=str, help='tenant ID')
parser.add_argument('--azclientid', type=str, help='SP client ID')
parser.add_argument('--azspsecret', type=str, help='SP secret')
parser.add_argument('--target_env', type=str, help='target environment')
parser.add_argument('--items_in_scope', type=str, help='Defines the item types to be deployed')
args = parser.parse_args()

Diese Argumente werden aus dem YaML-Pipelineschritt übergeben. Der Parser stellt sie als args.aztenantid, args.azclientidusw. zur Verfügung.

6.5 Authentifizierung

token_credential = ClientSecretCredential(
 client_id=args.azclientid,
 client_secret=args.azspsecret,
 tenant_id=args.aztenantid,
)

Dadurch wird ein Azure-Anmeldeinformationsobjekt mithilfe der Client-ID, des geheimen Schlüssels und der Mandanten-ID des Dienstprinzipals erstellt. Diese Anmeldeinformationen werden für Folgendes verwendet:

Aufrufen der Fabric-REST-API (Arbeitsbereichssuche)
Übergabe an FabricWorkspace für die Bereitstellung von fabric-cicd

6.6 Dynamische Arbeitsbereichauflösung

tgtenv = args.target_env       # e.g., "test"
ws_name = f'{tgtenv}WorkspaceName'    # e.g., "testWorkspaceName"
workspace_name = os.environ[ws_name.upper()]  # reads TESTWORKSPACENAME from env vars

Der clevere Teil: Die Variablengruppe fabric_cicd_group_non_sensitive enthält Variablen wie devWorkspaceName, testWorkspaceNameusw. ADO fügt diese als Großbuchstaben Umgebungsvariablen ein. Das Skript erstellt dynamisch den Variablennamen basierend auf der Zielumgebung.

# Generate a token and look up the workspace ID
resource = 'https://api.fabric.microsoft.com/'
scope = f'{resource}.default'
token = token_credential.get_token(scope)

lookup_response = get_workspace_id(workspace_name, token)
if lookup_response.startswith("Error"):
 raise ValueError(f"{lookup_response}. Perhaps workspace name is set incorrectly...")
else:
 wks_id = lookup_response

6.7 Initialisieren von FabricWorkspace & Deploy

repository_directory = os.environ["GITDIRECTORY"] # e.g., "fabric"

item_types = args.items_in_scope.strip("[]").split(",") # Convert string to list

target_workspace = FabricWorkspace(
 workspace_id=wks_id,
 environment=tgtenv,
 repository_directory=repository_directory,
 item_type_in_scope=item_types,
 token_credential=token_credential,
)

# Deploy!
publish_all_items(target_workspace)
unpublish_all_orphan_items(target_workspace)

Methode	Funktionsweise
`FabricWorkspace(...)`	Initialisiert den Bereitstellungskontext – liest Elementdefinitionen aus dem Git-Repository, lädt Parameterdateien für die GUID-Ersetzung und bereitet den Bereitstellungsplan vor.
`publish_all_items()`	Stellt alle In-Scope-Elemente im Zielarbeitsbereich bereit. Behandelt die Erstellung neuer Elemente und die Aktualisierung vorhandener Elemente.
`unpublish_all_orphan_items()`	Entfernt Elemente aus dem Ziel-Arbeitsbereich, die nicht mehr in der Git-Verzweigung vorhanden sind, um den Arbeitsbereich sauber zu halten.

— WICHTIG — Verständnis : Diese Methode löscht Elemente der im angegebenen Typen aus dem Zielarbeitsbereich, die in der Release-Verzweigung nicht vorhanden sind (d. h. die Verzweigung, die als Quelle für das Paket verwendet wird). Es berührt keine Elemente anderer Typen. In diesem Lernprogramm enthält die test Verzweigung alle Elemente, die für den TEST-Arbeitsbereich vorgesehen sind, daher ist es sicher, aufzurufen unpublish_all_orphan_items() – es werden nur Elemente entfernt, die absichtlich aus der Verzweigung gelöscht wurden.

Wenn Sie jedoch eine selektive Bereitstellung durchführen (z. B. nur Notizbücher über einen eingeschränkten items_in_scope bereitstellen), seien Sie vorsichtig mit unpublish_all_orphan_items() - es würde alle Notizbücher im Arbeitsbereich löschen, die sich nicht im Branch befinden, auch wenn sie noch gültig sind und einfach nicht Teil der selektiven Freigabe waren.

💡 Tipp:unpublish_all_orphan_items() unterstützt das Ausschließen bestimmter Elemente vom Entfernen durch Übergeben eines regex-Musters. Alle Elemente, deren Namen mit dem regex übereinstimmen, werden im Arbeitsbereich beibehalten, auch wenn sie sich nicht in der Quellzweigung befinden. Weitere Details und Verwendungsbeispiele finden Sie in der offiziellen API-Referenz.

7. Code Deep Dive: Parameterdateien (GUID-Ersetzung)

Hier geschieht die Magie – wie %%configure GUIDs pro Umgebung ausgetauscht werden.

Funktionsweise

Das fabric-cicd-Paket sucht im .deploy-Verzeichnis (oder der Repository-Wurzel) nach einer Datei namens parameter.yml. Diese Datei definiert Find-and-Replace-Regeln , die vor der Bereitstellung auf Elementdefinitionen angewendet werden.

💡 Tipp: Das parameter.yml Feature "Suchen und Ersetzen" unterstützt viele Ansätze , die über die in diesem Lernprogramm gezeigten Vorgehensweisen hinausgehen– einschließlich Regex-Mustern, Dateibereichsersetzungen und vieles mehr. Die vollständige Liste der Optionen und der erweiterten Nutzung finden Sie in der offiziellen Dokumentation: 👉fabric-cicd Parameter File Documentation

💡 Tipp – Variable Bibliothek: Es wird empfohlen, die Variable Bibliothek immer dann zu nutzen, wenn möglich, um umgebungsspezifische Werte zu verwalten, anstatt sich ausschließlich auf find_replace Parameterdateien zu verlassen. Variable Bibliotheken bieten eine zentrale, wiederverwendbare Möglichkeit zum Verwalten der Konfiguration in allen Umgebungen. Weitere Informationen finden Sie unter "Erste Schritte mit Variablenbibliotheken".

Datei:`parameter.yml` – befindet sich im GitHub-Repository, das zuvor heruntergeladen wurde.

7.1-Parameterdateistruktur

find_replace:
 - find_value: "bfddf0b6-5b74-461a-a963-e89ddc32f852"  # DEV Workspace ID
 replace_value:
  test: " $workspace.$id"         # Replaced with TEST workspace ID
  prod: " $workspace.$id"         # Replaced with PROD workspace ID

🔍 Grundlegendes zu jedem Eintrag

Eintrag 1 – Arbeitsbereichs-ID-Ersatz

- find_value: "bfddf0b6-5b74-461a-a963-e89ddc32f852" # DEV Workspace ID
 replace_value:
 test: " $workspace.$id" # Auto-resolves to the TEST workspace's actual ID
 prod: " $workspace.$id" # Auto-resolves to the PROD workspace's actual ID

find_value: Die im Befehl des Notizbuchs %%configure gefundene GUID — dies ist die DEV-Arbeitsbereichs-ID.
replace_value: Der $workspace.$id ist ein integriertes Token in fabric-cicd, das sich zum Zeitpunkt der Bereitstellung automatisch in die ID des Zielarbeitsbereichs auflöst.
Da dev nicht in replace_value aufgeführt ist, wird die GUID nur bei der Bereitstellung nach test oder prod ersetzt.

Eintrag 2 – Lakehouse-ID-Austausch

- find_value: "981f2f9a-0436-4942-b158-019bd73cdf1c" # DEV DemoLakehouse GUID
 replace_value:
 test: "$items.Lakehouse.DemoLakehouse.$id" # Resolves to TEST Lakehouse ID
 prod: "$items.Lakehouse.DemoLakehouse.$id" # Resolves to PROD Lakehouse ID

$items.Lakehouse.DemoLakehouse.$id ist ein dynamisches Token, das im Zielarbeitsbereich das Lakehouse mit dem Namen DemoLakehouse nachschlägt und seine ID zurückgibt.
Muster:$items.<ItemType>.<ItemName>.$id

Eintrag 3 – SQL Endpoint ID Replacement (Dynamische Notation)

- find_value: "91280ad0-b76e-4c98-a656-95d8f09a5e28" # DEV SQL Endpoint GUID
 replace_value:
 test: $items.Lakehouse.DemoLakehouse.$sqlendpointid # Resolved dynamically at deploy time
 prod: $items.Lakehouse.DemoLakehouse.$sqlendpointid # Resolved dynamically at deploy time

Anstatt die GUID des SQL-Endpunkts für jede Umgebung (zum Beispiel 204fd20c-e34c-4bef-9dce-4ecf53b0e878 für TEST oder 29bda5ec-ebc7-466e-a618-ef5bbea75e13 für PROD) hart zu codieren, verwendet diese Methode dynamische Schreibweise — $items.Lakehouse.DemoLakehouse.$sqlendpointid.
Das fabric-cicd Paket löst dies während der Bereitstellung, indem es die SQL-Endpunkt-ID des DemoLakehouse Lakehouse im Zielarbeitsbereich aufsucht. Dadurch ist es nicht erforderlich, SQL-Endpunkt-GUIDs in allen Umgebungen manuell zu finden und zu verwalten.

7.2 Zusammenfassung dynamischer Token

Token	Ergibt
`$workspace.$id`	GUID des Zielarbeitsbereichs
`$items.Lakehouse.<name>.$id`	Die GUID eines Lakehouses mit dem Namen `<name>` im Zielarbeitsbereich
`$items.<ItemType>.<ItemName>.$id`	Generisches Muster für jeden Elementtyp
`$items.Lakehouse.<name>.$sqlendpointid`	Die GUID des SQL-Endpunkts von Lakehouse (dynamisch aufgelöst)

7.3 Parameterdatei für Feature Branches (Erweitert)

Für Teams, die Feature-Verzweigungen verwenden (nicht nur dev), gibt es eine Variant-Parameterdatei, in der alle drei Umgebungen (Dev, Test, prod) Ersatz haben:

- find_value: "d34e3a2a-96ba-4461-9a80-496894ca4cda" # Feature branch Workspace ID
 replace_value:
 dev: " $workspace.$id"
 test: " $workspace.$id"
 prod: " $workspace.$id"

Dies ist nützlich, wenn Entwickler in ihren eigenen Fabric-Arbeitsbereichen arbeiten und GUIDs ersetzen müssen, auch wenn sie in DEV bereitgestellt werden.

8. Bereitstellungsablauf: End-to-End-Durchlauf

Hier sehen Sie den vollständigen Ablauf, wenn Alex ein Notebook von dev nach test befördern möchte.

Schritt 1: 🔧 Entwickler nimmt Änderungen an DEV vor

Alex ändert das IngestApiData Notizbuch im DEV Fabric-Arbeitsbereich (z. B. fügt eine neue Zelle hinzu). Die Git-Integration von Fabric synchronisiert diese Änderung automatisch mit dem dev Branch oder alternativ über einen manuellen Commit.

Schritt 2: 📋 Erstellen einer Pullanforderung (Dev → Test)

Alex erstellt eine Pullanforderung in ADO:

Quellzweig:dev
Zielzweig:test
Titel: "Fördern geänderter Notizbuchelemente zum Test"

Die PR enthält alle geänderten Elemente, die Alex in der TEST-Umgebung bereitstellen möchte.

Schritt 3: ✅ PR-Genehmigung und Zusammenführung

Ein Prüfer (oder der Administrator von Alex) überprüft den PR:

Überprüft die Änderungen an den Notizbuchdefinitionsdateien.
Genehmigt die PR
Schließt den Merge ab → Die Änderungen befinden sich jetzt im test Branch.

Schritt 4: 🚀 Automatische Auslöser für Pipelines

Der Zusammenführungs-Commit für die test Verzweigung löst das fabric_cicd_pipeline aus, weil:

Die test Verzweigung befindet sich in der Liste des Triggers include.
Die Änderungen befinden sich innerhalb des Pfads fabric/ .

Die Pipeline beginnt mit der Ausführung:

Pipeline Variable: target_env = "test"

Schritt 5: ⏸️ Genehmigungsgate

Da die Pipeline environment: $(target_env) und target_env = test verwendet, überprüft ADO die Testumgebung auf Genehmigungsgates.

Die Pipeline hält an und sendet eine Benachrichtigung an die konfigurierten Genehmigenden.
Der Administrator überprüft und klickt auf "Genehmigen".

Schritt 6: ⚡ Skriptausführung

Nach der Genehmigung der Pipeline:

⚙️ Einrichten von Python 3.12
📦 Installiert fabric-cicd
▶️ Läuft deploy-to-fabric.py mit:

SPN-Anmeldeinformationen aus Key Vault
--target_env test
--items_in_scope ["Notebook","Lakehouse",...]

Das Python-Skript:

🔐 Authentifiziert sich mithilfe des SPN
🔍 Ermittelt die Arbeitsbereichs-ID testWorkspaceName
📄 Lädt parameter.yml und wendet GUID-Ersetzungen an.
📤 Veröffentlicht Elemente im TEST-Arbeitsbereich
🧹 Bereinigt verwaiste Elemente

Schritt 7: ✅ Bereitstellung abgeschlossen

Das Notizbuch wird jetzt im TEST-Arbeitsbereich bereitgestellt mit:

✅ Die neu hinzugefügte Zelle, die vorhanden ist
✅ Alle GUIDs in %%configure wurden durch TEST-Umgebungswerte ersetzt

9. Überprüfung: Bestätigen einer erfolgreichen Bereitstellung

Nachdem die Pipeline abgeschlossen ist, überprüfen Sie, ob die Bereitstellung erfolgreich war.

Überprüfung 1: Pipeline-Status

Vergewissern Sie sich, dass in ADO → Pipelines → Ausführungen die Pipelineausführung für die test Umgebung mit ✅ Erfolgreich angezeigt wird.

Prüfung 2: Inhalt des Notizbuchs im TEST-Arbeitsbereich

Öffnen Sie das IngestApiData Notizbuch im Test Fabric-Arbeitsbereich, und überprüfen Sie Folgendes:

Neue Zelle ist vorhanden: Die neu hinzugefügte Zelle, die in DEV entwickelt wurde, sollte nun in der TESTversion des Notizbuchs angezeigt werden.
GUIDs werden in Zelle 1 ersetzt: Im %%configure Befehl (in der Regel in Zelle 1) stellen Sie Folgendes sicher:

GUID-Typ	Sollte angezeigt werden	Sollte NICHT angezeigt werden
Arbeitsbereichs-ID	ID des TEST-Arbeitsbereichs	~~DEV-Arbeitsbereichs-ID~~
DemoLakehouse-ID	TEST Lakehouse-ID	~~DEV Lakehouse ID~~
SQL-Endpunkt-ID	SQL-Endpunkt-ID testen (dynamisch aufgelöst)	~~DEV SQL-Endpunkt-ID (`91280ad0-...`)~~

✅ Erfolg! Die %%configure Zelle verweist nun auf TEST Seehäuser, und die neue Entwicklungsarbeit wurde sauber gefördert.

10. Problembehandlung & häufige Fallstricke

Das Problem	Ursache	Lösung
Pipeline schlägt mit "Arbeitsbereich nicht gefunden" fehl.	Der Arbeitsbereichsname in variabler Gruppe stimmt nicht mit Fabric überein.	Überprüfen Sie `testWorkspaceName` erneut in der `fabric_cicd_group_non_sensitive` Variablengruppe
GUIDs, die nicht ersetzt werden	`parameter.yml` nicht an der erwarteten Position	Stellen Sie sicher, dass sich die Datei im `.deploy/` Ordner neben dem Skript oder im Stammverzeichnis des Repositorys befindet.
`Permission denied` Fehler aus der Fabric-API	SPN hat keinen Arbeitsbereichszugriff	Hinzufügen des SPN als Mitglied oder Administrator zum Ziel-Fabric-Arbeitsbereich
Pipeline löst beim Zusammenführen nicht aus	Pfadfilterkonflikt	Stellen Sie sicher, dass sich Die Fabric-Elemente im `fabric/` Verzeichnis im Repository befinden.
`ModuleNotFoundError: fabric_cicd`	Paket nicht installiert	Sicherstellen, dass der `pip install fabric-cicd` Schritt vorhanden ist und erfolgreich ist
Genehmigungsbenachrichtigung nicht empfangen	Umgebung nicht konfiguriert	Überprüfen, ob der ADO-Umgebungsname exakt übereinstimmt `target_env` (Groß-/Kleinschreibung beachtet)
SQL-Endpunkt-GUID nicht ersetzt	Dynamische Schreibweise falsch konfiguriert	Sicherstellen, dass `$items.Lakehouse.<name>.$sqlendpointid` die Syntax korrekt ist und das Lakehouse im Zielarbeitsbereich vorhanden ist
`os.environ` Schlüsselfehler	Variable Gruppe, die nicht mit der Pipeline verknüpft ist	Autorisieren Sie die Pipeline für den Zugriff `fabric_cicd_group_non_sensitive`
Fehler bei Feature-Flags für Verknüpfungen	`fabric-cicd` Version zu alt	Upgrade `fabric-cicd` auf die neueste Version: `pip install fabric-cicd --upgrade`

11. Zusammenfassung

In diesem Lernprogramm wurde ein CI/CD-Workflow auf Produktionsniveau für Microsoft Fabric mit Azure DevOps veranschaulicht:

Komponente	Was Wir Einrichten
Azure Key Vault	Speichert SPN-Anmeldeinformationen sicher (Mandanten-ID, Client-ID, Geheimer Schlüssel)
ADO-Variablengruppen	Ein Schlüsseltresor–verknüpft (vertraulich), eine einfache (Arbeitsbereichsnamen)
ADO-Umgebungen	`dev`, `test` mit `prod` Genehmigungstoren an `test` und `prod`
Git Branches	`dev` (mit Fabric verbunden) `test` und `prod` (Bereitstellungsziele)
Pipeline-YAML	Automatische Auslöser bei Branch-Merge, parametrisierte Elementauswahl
Python-Skript	Authentifiziert über SPN, bestimmt Arbeitsbereich, stellt über `fabric-cicd`
Parameterdatei	Vertauscht DEV-GUIDs mit umgebungsspezifischen Werten mithilfe dynamischer Token

Wichtige Erkenntnisse

Nur die dev Verzweigung ist mit einem Fabric-Arbeitsbereich verbunden – test und prod Verzweigungen dienen als Bereitstellungsdatensätze.
fabric-cicdParameterdateien verarbeiten die GUID-Ersetzung automatisch mithilfe dynamischer Token wie $workspace.$id und $items.Lakehouse.<name>.id.
ADO-Umgebungen mit Genehmigungen bieten Governance – keine Bereitstellung in höheren Umgebungen ohne explizite Genehmigung.
Die Dienstprinzipalauthentifizierung über Azure Key Vault stellt sicher, dass Anmeldeinformationen nie in Code oder Protokollen verfügbar gemacht werden.

📚 Weitere Lektüre:

fabric-cicd Dokumentation

Microsoft Fabric Git Integration

Azure DevOps-Umgebungen und -Genehmigungen

Verknüpfte Azure Key Vault-Variablengruppen

Feedback

War diese Seite hilfreich?

Last updated on 2026-02-20

Freigeben über

🚀 CI/CD für Microsoft Fabric mit Azure DevOps & dem fabric-cicd Python-Paket

1. Szenarioübersicht

Die Herausforderung

Was Alex erwartet

Die Tools

2. Architekturdiagramm

3. Voraussetzungen

Herunterladen der Quelldateien

4. Anfängliches Azure DevOps-Setup

4.1 Azure Key Vault-Integration

Schritte zum Einrichten von Azure Key Vault

4.2 Variable-Gruppe: fabric_cicd_group_sensitive

Schritte zum Erstellen

4.3 Variablengruppe: fabric_cicd_group_non_sensitive

Schritte zum Erstellen

4.4 ADO-Umgebungen und Genehmigungsgates

Schritte zum Erstellen von Umgebungen

4.5 Git Branch-Strategie

Die wichtigsten Punkte

Warum nur dev verbunden ist

4.6 ADO-Pipeline-Setup

Steps

5. Code Deep Dive: ADO Pipeline YAML

🔍 Erklärungs-Auslöser

🔍 Erläuterungsparameter

🔍 Erklärvariable

🔍 Erklärung-Deployment-Job

🔍 Erklärungsschritte

6. Code Deep Dive: Python-Bereitstellungsskript

6.1 Importe & Abhängigkeiten

6.2 Arbeitsbereichs-ID-Suchfunktion

6.3 Featurekennzeichnungen & Protokollierung

6.4 Argumentanalyse

6.5 Authentifizierung

6.6 Dynamische Arbeitsbereichauflösung

6.7 Initialisieren von FabricWorkspace & Deploy

7. Code Deep Dive: Parameterdateien (GUID-Ersetzung)

Funktionsweise

Datei:parameter.yml – befindet sich im GitHub-Repository, das zuvor heruntergeladen wurde.

7.1-Parameterdateistruktur

🔍 Grundlegendes zu jedem Eintrag

Eintrag 1 – Arbeitsbereichs-ID-Ersatz

Eintrag 2 – Lakehouse-ID-Austausch

Eintrag 3 – SQL Endpoint ID Replacement (Dynamische Notation)

7.2 Zusammenfassung dynamischer Token

7.3 Parameterdatei für Feature Branches (Erweitert)

8. Bereitstellungsablauf: End-to-End-Durchlauf

Schritt 1: 🔧 Entwickler nimmt Änderungen an DEV vor

Schritt 2: 📋 Erstellen einer Pullanforderung (Dev → Test)

Schritt 3: ✅ PR-Genehmigung und Zusammenführung

Schritt 4: 🚀 Automatische Auslöser für Pipelines

Schritt 5: ⏸️ Genehmigungsgate

Schritt 6: ⚡ Skriptausführung

Schritt 7: ✅ Bereitstellung abgeschlossen

9. Überprüfung: Bestätigen einer erfolgreichen Bereitstellung

Überprüfung 1: Pipeline-Status

Prüfung 2: Inhalt des Notizbuchs im TEST-Arbeitsbereich

10. Problembehandlung & häufige Fallstricke

11. Zusammenfassung

Wichtige Erkenntnisse

Feedback

Zusätzliche Ressourcen

🚀 CI/CD für Microsoft Fabric mit Azure DevOps & dem `fabric-cicd` Python-Paket

4.2 Variable-Gruppe: `fabric_cicd_group_sensitive`

4.3 Variablengruppe: `fabric_cicd_group_non_sensitive`

Warum nur `dev` verbunden ist

Datei:`parameter.yml` – befindet sich im GitHub-Repository, das zuvor heruntergeladen wurde.