Automatisieren der Bereitstellungspipeline für Power BI-Elemente mithilfe von APIs

Mit dem Microsoft Power BI-Bereitstellungspipelines-Tool können Business Intelligence-Teams einen effizienten und wiederverwendbaren Releaseprozess für ihre Power BI-Inhalte erstellen.

Hinweis

Die hier aufgeführten Bereitstellungspipeline-APIs gelten nur für Power BI-Elemente. Informationen zu Fabric-APIs finden Sie in der Fabric-API-Dokumentation.

Um Continuous Integration und Continuous Delivery (CI/CD) von Inhalten zu erreichen, verwenden viele Organisationen Automatisierungstools, einschließlich Azure DevOps. Organisationen, die Azure DevOps verwenden, können die Erweiterung „Power BI automation tools“ (Power BI-Automatisierungstools) verwenden, die viele API-Vorgänge für Bereitstellungspipelines unterstützt.

Sie können die Power BI-REST-APIs für Bereitstellungspipelines verwenden, um Fabric in den Automatisierungsprozess Ihrer Organisation zu integrieren. Im Folgenden finden Sie einige Beispiele dafür, was mithilfe der APIs möglich ist:

• Verwalten von Pipelines von Anfang bis Ende, darunter Erstellen einer Pipeline, Zuweisen eines Arbeitsbereichs zu einer beliebigen Phase sowie Bereitstellen und Löschen einer Pipeline.

• Zuweisen von Benutzer*innen zu einer Pipeline und Zuweisungen aufheben.

• Integrieren Sie Fabric in vertraute DevOps-Tools wie Azure DevOps oder GitHub Actions.

• Planen Sie Pipelinebereitstellungen so, dass sie zu einem bestimmten Zeitpunkt automatisch erfolgen.

• Stellen Sie mehrere Pipelines gleichzeitig bereit.

• Kaskadieren Sie abhängig von Pipelinebereitstellungen. Wenn Sie über Inhalte verfügen, die pipelineübergreifend verbunden sind, können Sie sicherstellen, dass einige Pipelines vor anderen bereitgestellt werden.

API-Funktionen für Bereitstellungspipelines

Die Power BI-REST-APIs für Bereitstellungspipelines machen die folgenden Funktionen möglich:

• Abrufen von Pipelineinformationen: Rufen Sie Informationen zu Ihren Pipelines und deren Inhalt ab. Durch das Abrufen der Pipelineinformationen können Sie die Bereitstellungs-API-Aufrufe dynamisch erstellen. Sie können auch den Status einer Bereitstellung oder den Bereitstellungsverlauf überprüfen.

• Bereitstellen: Die REST-Aufrufe ermöglichen es Entwickler*innen, jede Art von Bereitstellung zu verwenden, die im Fabric-Dienst verfügbar ist.

• Erstellen und Löschen von Pipelines: Verwenden Sie Pipeline erstellen und Pipeline löschen, um diese Vorgänge auszuführen.

• Arbeitsbereiche verwalten: Mit Arbeitsbereich zuweisen und Zuweisung des Arbeitsbereichs aufheben können Sie Arbeitsbereiche bestimmten Pipelinephasen zuweisen und Zuweisungen aufheben.

• Verwalten von Pipelinebenutzer*innen: Mit Delete Pipeline User (Pipelinebenutzer löschen) können Sie Benutzer*innen aus einer Pipeline entfernen. Mit Update Pipeline User (Pipelinebenutzer*innen aktualisieren) können Sie Ihrer Pipeline Benutzer*innen hinzufügen.

Welche Bereitstellungstypen unterstützen die APIs?

Die APIs unterstützen die folgenden Bereitstellungstypen:

• Alle bereitstellen: Ein einzelner API-Aufruf, der den gesamten Inhalt im Arbeitsbereich in der nächsten Phase der Pipeline bereitstellt. Verwenden Sie für diesen Vorgang die API Alle bereitstellen.

• Selektive Bereitstellung: Stellen Sie nur bestimmte Elemente (z. B. Berichte oder Dashboards) in der Pipeline bereit. Verwenden Sie für diesen Vorgang die API Selektive Bereitstellung.

• Rückwärtsbereitstellung: Stellt neue Elemente in der vorherigen Phase bereit. Die Rückwärtsbereitstellung funktioniert nur, wenn die bereitgestellten Elemente noch nicht in der Zielphase vorhanden sind. Verwenden Sie für diesen Vorgang entweder die API Alle bereitstellen oder die API Selektive Bereitstellung, wobei isBackwardDeployment auf Truefestgelegt ist.

• App aktualisieren: Im Rahmen des API-Aufrufs zur Bereitstellung können Sie den Inhalt der App aktualisieren, die mit dieser Phase verknüpft ist. Aktualisierte Elemente stehen Ihren Endbenutzer*innen automatisch zur Verfügung, nachdem eine Bereitstellung abgeschlossen wurde. Verwenden Sie für diesen Vorgang entweder die API Alle bereitstellen oder die API Selektive Bereitstellung mit PipelineUpdateAppSettings.

Voraussetzungen

Bevor Sie die Bereitstellungspipeline-APIs verwenden, stellen Sie sicher, dass Sie über Folgendes verfügen:

• Die Dienstprinzipale, oder Benutzer die die APIs aufrufen, benötigen Pipeline- und Arbeitsbereichsberechtigungen und Zugriff auf eine Microsoft Entra Anwendung.

• Wenn Sie PowerShell-Skripts verwenden möchten, installieren Sie die Power BI-PowerShell-Cmdlets Install-Module MicrosoftPowerBIMgmt.

Integrieren Ihrer Pipeline in Azure DevOps

Verwenden Sie eine dieser Methoden, um die Bereitstellungsprozesse in Ihrer Releasepipeline in Azure DevOps zu automatisieren:

• PowerShell: Das Skript meldet sich mithilfe eines Dienstprinzipals oder eines Benutzers bei Fabric an.

• Power BI automation tools: Diese Erweiterung kann mit einem Dienstprinzipal oder einem Benutzer verwendet werden.

Sie können auch andere Power BI-REST-API-Aufrufe verwenden, um verwandte Vorgänge wie das Importieren einer PBIX-Datei in die Pipeline oder das Aktualisieren von Datenquellen und Parametern durchzuführen.

Verwenden der Erweiterung „Power BI automation tools“

Die Erweiterung „Power BI automation tools“ ist eine Open-Source-Erweiterung für Azure DevOps, die Vorgänge für Bereitstellungspipelines bietet, die in Azure DevOps ausgeführt werden können. Durch die Erweiterung entfällt die Notwendigkeit, Pipelines mithilfe von APIs und Skripts zu verwalten. Jeder Vorgang kann einzeln verwendet werden, um eine Aufgabe wie das Erstellen einer Pipeline auszuführen. Vorgänge können zusammen in einer Azure DevOps-Pipeline verwendet werden, um ein komplexeres Szenario zu erstellen, z. B. das Erstellen einer Pipeline, das Hinzufügen eines Arbeitsbereichs zur Pipeline, das Hinzufügen von Benutzern und das Bereitstellen.

Nachdem Sie die Erweiterung Power BI automation tools zu DevOps hinzugefügt haben, müssen Sie eine Dienstverbindung erstellen. Die folgenden Verbindungen können verwendet werden:

• Dienstprinzipale (empfohlen): Diese Verbindung wird mit einem Dienstprinzipal authentifiziert und erfordert die geheime Microsoft Entra App und die Anwendungs-ID. Stellen Sie bei Verwendung dieser Option sicher, dass die Dienstadministratoreinstellungen für den Dienstprinzipal aktiviert sind.

• Benutzername und Kennwort: Diese Verbindung ist als generische Dienstverbindung mit einem Benutzernamen und einem Kennwort konfiguriert. Mit dieser Verbindungsmethode ist keine Multi-Faktor-Authentifizierung möglich. Es wird empfohlen, die Dienstprinzipal-Verbindungsmethode zu verwenden, da dabei keine Anmeldeinformationen von Benutzern auf Azure DevOps gespeichert werden müssen.

Hinweis

Die Erweiterung „Power BI automation tools“ verwendet eine Azure DevOps-Dienstverbindung zum Speichern von Anmeldeinformationen. Weitere Informationen finden Sie unter Speichern Ihrer Anmeldeinformationen für Azure DevOps Services.

Nachdem Sie eine Dienstverbindung für Ihre „Power BI automation tools“-Erweiterung für Azure DevOps hergestellt haben, können Sie Pipelineaufgaben erstellen. In der Erweiterung sind die folgenden Aufgaben für Bereitstellungspipelines enthalten:

• Erstellen einer neuen Pipeline

• Zuweisen eines Arbeitsbereichs zu einer Pipelinephase

• Hinzufügen eines Benutzers zu einer Bereitstellungspipeline

• Hinzufügen eines Benutzers zu einem Arbeitsbereich

• Bereitstellen von Inhalten in einer Bereitstellungspipeline

• Entfernen eines Arbeitsbereichs aus einer Bereitstellungspipeline

• Löschen einer Pipeline

Zugreifen auf die PowerShell-Beispiele

Die folgenden PowerShell-Skripts verdeutlichen, wie mehrere Automatisierungsprozesse ausgeführt werden. Verwenden Sie die Links in diesem Abschnitt, um den Text in einem PowerShell-Beispiel anzuzeigen oder zu kopieren.

Sie können auch den gesamten GitHub-Ordner PowerBI-Developer-Samples herunterladen.

• Alle bereitstellen

• Selektive Bereitstellung

• Auf die Bereitstellung warten

• End-to-End-Beispiel der Pipelineerstellung und abwärtskompatiblen Pipelinebereitstellung

• Zuweisen eines Administratorbenutzers zu einer Pipeline

PowerShell-Beispiel

In diesem Abschnitt wird ein PowerShell-Beispielskript beschrieben, das ein Semantikmodell, einen Bericht und ein Dashboard aus der Entwicklungsphase in der Testphase bereitstellt. Das Skript überprüft dann, ob die Bereitstellung erfolgreich war.

Um ein PowerShell-Skript auszuführen, das eine Bereitstellung ausführt, benötigen Sie die folgenden Komponenten. Sie können jeden dieser Teile in Aufgaben in Ihren Azure-Pipelinephasen hinzufügen.

1. Anmelden: Bevor Sie Ihre Inhalte bereitstellen können, müssen Sie sich bei Fabric anmelden, indem Sie einen Dienstprinzipal oder einen Benutzer verwenden. Verwenden Sie den Befehl Connect-PowerBIServiceAccount, um sich anzumelden.

2. Erstellen des Anforderungstexts: In diesem Teil des Skripts geben Sie an, welche Elemente (z. B. Berichte und Dashboards) bereitgestellt werden.

   $body = @{ 
       sourceStageOrder = 0 # The order of the source stage. Development (0), Test (1).   
       datasets = @(
           @{sourceId = "Insert your dataset ID here" }
       )      
       reports = @(
           @{sourceId = "Insert your report ID here" }
       )            
       dashboards = @(
           @{sourceId = "Insert your dashboard ID here" }
       )
   
       options = @{
           # Allows creating new item if needed on the Test stage workspace
           allowCreateArtifact = $TRUE
   
           # Allows overwriting existing item if needed on the Test stage workspace
           allowOverwriteArtifact = $TRUE
       }
   } | ConvertTo-Json
   

3. Bereitstellen: Hier führen Sie die Bereitstellung aus.

   $url = "pipelines/{0}/Deploy" -f "Insert you pipeline ID here"
   $deployResult = Invoke-PowerBIRestMethod -Url $url  -Method Post -Body $body | ConvertFrom-Json
   

4. (Optional) Benachrichtigung zum Abschluss der Bereitstellung: Da die Bereitstellungs-API asynchron ist, können Sie das Skript so programmieren, dass Sie benachrichtigt werden, wenn die Bereitstellung abgeschlossen ist.

   $url =  "pipelines/{0}/Operations/{1}" -f "Insert you pipeline ID here",$deployResult.id
   $operation = Invoke-PowerBIRestMethod -Url $url -Method Get | ConvertFrom-Json    
   while($operation.Status -eq "NotStarted" -or $operation.Status -eq "Executing")
   {
       # Sleep for 5 seconds
       Start-Sleep -s 5
       $operation = Invoke-PowerBIRestMethod -Url $url -Method Get | ConvertFrom-Json
   }
   

Überlegungen und Einschränkungen

• Die Bereitstellung mithilfe von APIs unterliegt den gleichen Einschränkungen wie die Benutzeroberfläche für Bereitstellungspipelines.

• Ein Dienstprinzipal kann keine OAuth-Anmeldeinformationen konfigurieren. Nachdem Sie neue Elemente bereitgestellt haben, wird der angemeldete Dienstprinzipal zum Besitzer aller bereitgestellten paginierten Berichte und Semantikmodelle. In solchen Fällen kann eine Aktualisierung nicht abgeschlossen werden.

• Das Bereitstellen von Dataflows mithilfe eines Dienstprinzipals wird nicht unterstützt.

• Die maximale Anzahl von Elementen in einer einzelnen Bereitstellung liegt bei 300.

• Die Bereitstellungspipelines-APIs unterstützen derzeit nur Power BI-Elemente.

• Das Erstellen einer benutzerdefinierten Pipeline mit 2 bis 10 Phasen wird derzeit nur über die Benutzeroberfläche unterstützt.

Zugehöriger Inhalt

• Erste Schritte mit Bereitstellungspipelines
• Bewährte Methoden für Bereitstellungspipelines
• Problembehandlung bei Bereitstellungspipelines