Automatizzare la pipeline di distribuzione usando API e Azure DevOps

Articolo
06/04/2023

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.

Importante

Microsoft Fabric è attualmente in ANTEPRIMA. Queste informazioni si riferiscono a un prodotto di versione preliminare che può essere modificato sostanzialmente prima che venga rilasciato. Microsoft non garantisce alcuna garanzia, espressa o implicita, rispetto alle informazioni fornite qui.

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 API REST della pipeline di distribuzione Fabric per integrare Fabric 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 e la distribuzione e l'eliminazione della pipeline.
Assegnare e annullare l'assegnazione degli utenti a e da una pipeline.
Integrare Fabric in strumenti DevOps noti, ad esempio Azure DevOps o GitHub Actions.
Pianificare le distribuzioni della pipeline da eseguire automaticamente in un momento specifico.
Distribuire più pipeline contemporaneamente.
Catena a seconda delle distribuzioni della pipeline. Se si dispone di contenuti connessi tra pipeline, è possibile assicurarsi che alcune pipeline vengano distribuite prima di altre.

Funzioni API pipeline di distribuzione

Le API REST dell'infrastruttura 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 della distribuzione.
Distribuire : 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 Unssign area di lavoro, è 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. L'utente della pipeline di aggiornamento 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 : distribuisce solo elementi specifici, ad esempio report o dashboard, nella pipeline. Per questa operazione, usare l'API di distribuzione selettiva .
Distribuzione indietro : distribuisce nuovi elementi alla fase precedente. La distribuzione con versioni precedenti funziona solo se gli elementi 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. Gli elementi aggiornati sono automaticamente disponibili per gli utenti finali, dopo il completamento di una distribuzione. Per questa operazione, usare le API Distribuisci tutte o le API di distribuzione selettiva con PipelineUpdateAppSettings.

Prima di iniziare

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

L'entità servizio o l'utente che chiamerà le API, necessita delle autorizzazioni della pipeline e dell'area di lavoro e dell'accesso a un'applicazione Azure AD.
Se si useranno script di PowerShell, installare i cmdlet di Power BI PowerShell Install-Module MicrosoftPowerBIMgmt.

Integrare la pipeline con Azure DevOps

Per automatizzare i processi di distribuzione dall'interno della pipeline di rilascio in Azure DevOps, 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 Fabric 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 Azure DevOps che fornisce un'ampia 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 segreto e l'applicazione dell'app di Azure AD. Quando si usa questa opzione, verificare che le impostazioni di amministratore del servizio per l'entità servizio siano abilitate.
Nome utente e password : configurata come connessione generica al servizio 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 Azure DevOps Power BI, è possibile creare attività della 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 seguenti. È possibile aggiungere una di queste parti alle attività nelle fasi della pipeline di Azure.

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.

Compilare il corpo della richiesta : in questa parte dello script vengono specificati gli elementi (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

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

(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 usando le 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 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 che possono essere distribuiti in una singola distribuzione è 300.