Automatizzare la pipeline di distribuzione con API e Azure DevOps

Lo strumento di pipeline di distribuzione di Power BI consente ai team BI 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 vari 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 sfruttare le pipeline di distribuzione delle API REST di Power BI per integrare Power BI nel processo di automazione dell'organizzazione. Ecco alcuni esempi di cosa è possibile eseguire 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, la distribuzione e l'eliminazione della pipeline.

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

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

  • Pianificare le distribuzioni della pipeline da eseguire automaticamente in un determinato momento.

  • Distribuire più pipeline contemporaneamente.

  • Catena a seconda delle distribuzioni della pipeline: se si dispone di contenuto connesso tra le pipeline, è possibile assicurarsi che alcune pipeline vengano distribuite prima di altre.

Funzioni API 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 la cronologia della distribuzione.

  • Distribuire : le chiamate REST consentono agli sviluppatori di usare qualsiasi tipo di distribuzione disponibile nel servizio Power BI.

  • Creare ed eliminare pipeline: usare la pipeline di creazione ed eliminazione della pipeline per eseguire queste operazioni.

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

  • Gestire gli utenti - della pipeline Eliminare l'utente della pipeline consente di rimuovere un utente da una pipeline. Update Pipeline User consente di aggiungere un utente alla pipeline.

Quali distribuzioni sono supportate dalle API?

Ecco un elenco dei diversi tipi di distribuzione supportati dalle API:

  • Distribuire 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 : distribuire solo elementi di Power BI specifici (ad esempio report o dashboard) nella pipeline. Per questa operazione, usare l'API di distribuzione selettiva .

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

  • Aggiorna app : nell'ambito della chiamata API di distribuzione è possibile aggiornare il contenuto dell'app correlata a tale fase. Usando questa funzionalità, gli elementi di Power BI nuovi o aggiornati saranno automaticamente disponibili per gli utenti finali, una volta completata una distribuzione. Per questa operazione, usare le API Distribuisci tutte o le API di distribuzione selettiva con PipelineUpdateAppSettings.

Prima di iniziare

Prima di iniziare a usare le API delle pipeline di distribuzione, assicurarsi di avere quanto segue:

Integrare la pipeline con Azure DevOps

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

  • PowerShell: lo script accede a Power BI 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 PBIX nella pipeline, l'aggiornamento di origini dati e parametri.

Usare l'estensione degli strumenti di automazione di Power BI

Gli strumenti di automazione di Power BI sono un'estensione Azure DevOps open source che offre un'ampia gamma di operazioni di pipeline di distribuzione che possono essere eseguite in Azure DevOps. Elimina la necessità di usare API o script per gestire le pipeline. Ogni operazione può essere usata singolarmente per eseguire una semplice attività, ad esempio la creazione di una pipeline o usata 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 esegue l'autenticazione usando un'entità servizio e richiede l'ID segreto e l'applicazione dell'app Azure AD. Quando si usa questa opzione, verificare che le impostazioni di amministratore del servizio Power BI per l'entità servizio siano abilitate.

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

Nota

L'estensione degli strumenti di automazione di Power BI usa una connessione al servizio Azure DevOps per archiviare le credenziali. Per altre informazioni, vedere Come archiviare le credenziali per Azure DevOps Services.

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

  • Creare 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.

Esempio di PowerShell

Questa sezione descrive uno script di PowerShell di esempio che distribuisce un set di dati, un report e un 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 elencati di seguito. È 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 Power BI 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 di Power BI (ad esempio report e dashboard) distribuiti.

    $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 notificare 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 con le API è soggetta alle stesse limitazioni dell'interfaccia utente delle pipeline di distribuzione di Power BI.

  • Un'entità servizio non può configurare le credenziali OAuth. Dopo la distribuzione di nuovi elementi, l'entità servizio con accesso diventa il proprietario di eventuali report e set di dati impaginati distribuiti. In questi casi, non è possibile completare un aggiornamento.

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

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

Passaggi successivi