Automatizzare la pipeline di distribuzione usando le API e Azure DevOps

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

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 degli strumenti di automazione di Power BI, che supporta molte delle operazioni API delle pipeline di distribuzione.

È possibile usare le pipeline di distribuzione api REST di Power BI 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.

Funzioni API delle pipeline di distribuzione

Nota

Le API delle pipeline di distribuzione attualmente funzionano solo per gli elementi di Power BI.

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.

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

Quali distribuzioni sono supportate dalle API?

Le API supportano i tipi di distribuzione seguenti:

  • 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 Deploy all (Distribuisci tutto) o Selective deploy (Distribuisci tutte le API di distribuzione selettiva) con PipelineUpdateApp Impostazioni.

Operazioni preliminari

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

Integrare la pipeline con Azure DevOps

Per automatizzare i processi di distribuzione dall'interno della pipeline di versione in Azure DevOps, usare uno dei metodi seguenti:

  • 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 l'ID applicazione e il segreto dell'app Microsoft Entra. Quando si usa questa opzione, verificare che le impostazioni di amministratore 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.

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

Esempio di PowerShell

Questa sezione descrive uno script di PowerShell di esempio che distribuisce un modello semantico, 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 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 Connessione-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 connesso diventa il proprietario di tutti i report impaginati distribuiti e i modelli semantici. 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 è possibile 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.