Automatizzare la pipeline di distribuzione per gli elementi di Power BI usando le API

Lo strumento pipeline di distribuzione di Power BI consente ai team di business intelligence di creare un processo di rilascio efficiente e riutilizzabile per il contenuto di Power BI.

Per ottenere l'integrazione continua e il recapito continuo (CI/CD) del contenuto, molte organizzazioni usano strumenti di automazione, tra cui Azure DevOps. Le organizzazioni che usano Azure DevOps possono usare l'estensione dello strumento di automazione di Power BI, che supporta molte delle operazioni API delle pipeline di distribuzione.

È possibile usare le API REST di Power BI per le pipeline di distribuzione per integrare Fabric nel processo di automazione dell'organizzazione. Ecco alcuni esempi di operazioni che possono essere eseguite usando le API:

• Gestire le pipeline dall'inizio alla fine, inclusa la creazione di una pipeline, l'assegnazione di un'area di lavoro a qualsiasi fase e la distribuzione e l'eliminazione della pipeline.

• Assegnare e annullare l'assegnazione di utenti a e da una pipeline.

• Integrare Fabric in strumenti DevOps familiari, ad esempio Azure DevOps o GitHub Actions.

• Pianificare le distribuzioni della pipeline in modo che vengano eseguite automaticamente in un momento specifico.

• Distribuire più pipeline contemporaneamente.

• A catena a seconda delle distribuzioni della pipeline. Se si dispone di contenuto connesso tra pipeline, è possibile assicurarsi che alcune pipeline vengano distribuite prima di altre.

Prerequisiti

Prima di usare le API delle pipeline di distribuzione, assicurarsi di avere le informazioni seguenti:

• L'entità servizio o l'utente che chiamerà le API, richiede autorizzazioni per pipeline e area di lavoro e l'accesso a un'applicazione Microsoft Entra.

• Se si intende usare gli script di PowerShell, installare i cmdlet di PowerShell di Power BI Install-Module MicrosoftPowerBIMgmt.

Funzioni API delle pipeline di distribuzione

Le API REST di Power BI per le pipeline di distribuzione consentono di eseguire le funzioni seguenti:

• Ottenere informazioni sulla pipeline: recuperare informazioni sulle pipeline e sul relativo contenuto. Ottenere le informazioni sulla pipeline consente di compilare dinamicamente le chiamate API di distribuzione. È anche possibile controllare lo stato di una distribuzione o della cronologia di distribuzione.

• Distribuisci: le chiamate REST consentono agli sviluppatori di usare qualsiasi tipo di distribuzione disponibile nel servizio Fabric.

• Creare ed eliminare pipeline: usare Crea pipeline ed Elimina pipeline per eseguire queste operazioni.

• Gestire le aree di lavoro: con Assegna area di lavoro e Annulla assegnazione dell'area di lavoro, è possibile assegnare e annullare l'assegnazione delle aree di lavoro a fasi specifiche della pipeline.

• Gestisci utenti della pipeline - Elimina utente della pipeline consente di rimuovere un utente da una pipeline. Aggiorna utente della pipeline consente di aggiungere un utente alla pipeline.

Quali tipi di distribuzione supportano le API?

Le API supportano i seguenti tipi di distribuzione:

• Distribuisci tutto: una singola chiamata API che distribuisce tutto il contenuto nell'area di lavoro alla fase successiva della pipeline. Per questa operazione, usare l'API Distribuisci tutto.

• Distribuzione selettiva: distribuisce solo elementi specifici, ad esempio report o dashboard, nella pipeline. Per questa operazione, usare l'API Distribuzione selettiva.

• Distribuzione con le versioni precedenti: distribuisce nuovi elementi nella fase precedente. La distribuzione con le versioni precedenti funziona solo se gli elementi distribuiti non esistono già nella fase di destinazione. Per questa operazione, usare le API Distribuisci tutto o Distribuzione selettiva, con isBackwardDeployment impostato su True.

• Aggiornare l'app: come parte della chiamata API di distribuzione, è possibile aggiornare il contenuto dell'app correlata a tale fase. Gli elementi aggiornati sono automaticamente disponibili per gli utenti finali, dopo il completamento di una distribuzione. Per questa operazione, usare le API Distribuisci tutto o Distribuzione selettiva con PipelineUpdateAppSettings.

Integrare la pipeline con Azure DevOps

Per automatizzare i processi di distribuzione dall'interno della pipeline di rilascio in Azure DevOps, è possibile usare uno di questi metodi:

• PowerShell: lo script accede a Fabric usando un'entità servizio o un utente.

• Strumenti di automazione di Power BI: questa estensione funziona con un'entità servizio o un utente.

È anche possibile usare altre chiamate API REST di Power BI per completare operazioni correlate, ad esempio l'importazione di un file con estensione .pbix nella pipeline, l'aggiornamento di origini dati e parametri.

Usare l'estensione degli strumenti di automazione di Power BI

L'estensione degli strumenti di automazione di Power BI è un'estensione open source di Azure DevOps che offre una gamma di operazioni di pipeline di distribuzione che possono essere eseguite in Azure DevOps. L'estensione elimina la necessità di API o script per gestire le pipeline. Ogni operazione può essere usata singolarmente per eseguire un'attività, ad esempio la creazione di una pipeline. Le operazioni possono essere usate insieme in una pipeline di Azure DevOps per creare uno scenario più complesso, ad esempio la creazione di una pipeline, l'assegnazione di un'area di lavoro alla pipeline, l'aggiunta di utenti e la distribuzione.

Dopo aver aggiunto l'estensione degli strumenti di automazione di Power BI a DevOps, è necessario creare una connessione al servizio. Sono disponibili le connessioni seguenti:

• Entità servizio (scelta consigliata): questa connessione viene autenticata usando un'entità servizio e richiede il codice segreto e l'ID applicazione dell'app Microsoft Entra. Quando si usa questa opzione, verificare che le impostazioni di amministrazione del servizio per l'entità servizio siano abilitate.

• Nome utente e password: configurato come connessione di servizio generico con un nome utente e una password. Questo metodo di connessione non supporta l'autenticazione a più fattori. È consigliabile usare il metodo di connessione dell'entità servizio perché non richiede l'archiviazione delle credenziali utente in Azure DevOps.

Dopo aver abilitato una connessione al servizio per gli strumenti di automazione di Power BI di Azure DevOps, è possibile creare attività della pipeline. L'estensione include le attività di pipeline di distribuzione seguenti:

• Crea una nuova pipeline

• Assegnare un'area di lavoro a una fase della pipeline

• Aggiungere un utente a una pipeline di distribuzione

• Aggiungere un utente a un'area di lavoro

• Distribuire il contenuto in una pipeline di distribuzione

• Rimuovere un'area di lavoro da una pipeline di distribuzione

• Eliminare una pipeline

Accedere agli esempi di PowerShell

È possibile usare gli script di PowerShell seguenti per comprendere come eseguire diversi processi di automazione. Per visualizzare o copiare il testo in un esempio di PowerShell, usare i collegamenti in questa sezione.

È anche possibile scaricare l'intera PowerBI-Developer-Samples cartella GitHub.

• Distribuisci tutto

• Distribuzione selettiva

• Attendere la distribuzione

• Esempio end-to-end della creazione della pipeline e distribuzione con le versioni precedenti

• Assegnare un utente amministratore a una pipeline

Esempio di PowerShell

Questa sezione descrive uno script di PowerShell di esempio che distribuisce un modello semantico, un report e una dashboard, dalla fase di sviluppo alla fase di test. Lo script verifica quindi se la distribuzione ha avuto esito positivo.

Per eseguire uno script di PowerShell che esegue una distribuzione, sono necessari i componenti seguenti. È possibile aggiungere una di queste parti alle attività nelle fasi della pipeline di Azure.

1. Accesso: prima di poter distribuire il contenuto, è necessario accedere a Fabric usando un'entità servizio o un utente. Usare il comando Connect-PowerBIServiceAccount per accedere.

2. Compilare il corpo della richiesta: in questa parte dello script si specificano gli elementi (ad esempio report e dashboard) da distribuire.

   $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. Distribuisci: qui si esegue la distribuzione.

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

4. (Facoltativo) Notifica di completamento della distribuzione: poiché l'API di distribuzione è asincrona, è possibile programmare lo script per inviare una notifica al completamento della distribuzione.

   $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
   }
   

Considerazioni e limitazioni

• La distribuzione tramite API è soggetta alle stesse limitazioni dell'interfaccia utente delle pipeline di distribuzione.

• Un'entità servizio non può configurare le credenziali OAuth. Dopo aver distribuito nuovi elementi, l'entità servizio con accesso diventa il proprietario di tutti i report impaginati e modelli semantici distribuiti. In questi casi, non è possibile completare un aggiornamento.

• La distribuzione di flussi di dati tramite un'entità servizio non è supportata.

• Il numero massimo di elementi che si possono distribuire in una singola distribuzione è 300.

• Le API delle pipeline di distribuzione attualmente supportano solo gli elementi di Power BI.

• La creazione di una pipeline personalizzata di 2-10 fasi è attualmente supportata solo tramite l'interfaccia utente.

Contenuto correlato

• Iniziare a usare le pipeline di distribuzione
• Procedure consigliate per le pipeline di distribuzione
• Risoluzione dei problemi delle pipeline di distribuzione