Condividi tramite

Distribuire progetti di Power BI (PBIP) usando fabric-cicd

Importante

I progetti di Power BI Desktop sono attualmente in anteprima.

fabric-cicd è una libreria Python sviluppata da Microsoft che fornisce un metodo code-first per gli sviluppatori di Fabric per distribuire elementi di Fabric dal controllo del codice alle aree di lavoro usando il formato di definizione del codice, ad esempio modelli semantici e report usando il formato di file PBIP.

In questo articolo vengono illustrate le operazioni seguenti:

  • Distribuire manualmente i file PBIP dal computer locale
  • Parametrizzare i file PBIP per configurazioni specifiche dell'ambiente
  • Automatizzare le distribuzioni mirando a workspace basati su branch utilizzando Azure DevOps o GitHub Actions

Altre informazioni sul formato PBIP nei progetti Power BI Desktop (PBIP) e panoramica dell'integrazione git di Fabric.

Perché fabric-cicd per la distribuzione PBIP?

fabric-cicd è progettato specificamente per il deployment di artefatti di Fabric gestiti tramite controllo del codice sorgente e offre diversi vantaggi:

  • Usa le API REST native di Fabric : basate sulle API ufficiali di Microsoft Fabric, garantendo la compatibilità e il supporto a lungo termine
  • Python-native - Integrazione facile con flussi di lavoro DevOps moderni basati su Python
  • Parametrizzazione: supporto predefinito per configurazioni specifiche dell'ambiente (ID area di lavoro, origini dati, stringhe di connessione)
  • Facile da sviluppatore: semplici script Python che possono essere eseguiti in locale o in pipeline CI/CD
  • Controllo di distribuzione flessibile: distribuire solo tipi di elementi specifici (ad esempio, modelli semantici senza report o modelli semantici con o senza cache dei dati) e garantire configurazioni coerenti come pagine o parametri predefiniti senza intervento manuale
  • Pulizia degli orfani: rimuove automaticamente gli elementi dallo spazio di lavoro che non esistono più nel controllo del codice sorgente
  • Autenticazione affidabile: usa Azure Identity SDK con più opzioni di autenticazione

Annotazioni

Per la documentazione completa, vedere la documentazione di fabric-cicd.

Prerequisiti

Prima di iniziare, assicurarsi di disporre di:

  • Python (da 3.9 a 3.12)
  • Un progetto di Power BI Desktop salvato in formato PBIP
  • Accesso a un'area di lavoro di Microsoft Fabric con ruolo Collaboratore

Per le distribuzioni automatizzate, è anche necessario:

  • Un'entità del servizio con almeno il ruolo di collaboratore negli spazi di lavoro Fabric di destinazione
  • Accesso ad Azure DevOps o GitHub Actions
  • I tuoi file PBIP nel sistema di controllo del codice sorgente (Git, Azure DevOps o GitHub)

Avvio rapido

Questa guida introduttiva illustra come distribuire un progetto PBIP dal computer locale a uno spazio di lavoro Fabric.

1. Installare fabric-cicd

Aprire il terminale e installare fabric-cicd:

pip install fabric-cicd

2. Preparare il progetto PBIP

Assicurarsi che il progetto PBIP includa i file necessari. Struttura di progetto PBIP tipica:

my-powerbi-project/
├── SalesAnalytics.Report/
│   ├── definition.pbir
│   └── definition/
│       └── pages/
├── SalesAnalytics.SemanticModel/
│   ├── definition.pbism
│   └── definition/
│       ├── model.tmdl
│       ├── tables/
│       └── ...
└── SalesAnalytics.pbip

Per informazioni dettagliate sui file e i formati necessari, vedere Cartella del report del progetto di Power BI Desktop e cartella del modello semantico del progetto di Power BI Desktop.

Suggerimento

Per creare un progetto PBIP, aprire il file PBIX in Power BI Desktop e salvarlo usando File >, Salva con nome > Power BI Project (.pbip). Per altri dettagli, vedere Progetti di Power BI Desktop .

3. Creare uno script di distribuzione

Creare un deploy.py file nella directory del progetto:

import argparse
import sys
from azure.identity import InteractiveBrowserCredential, AzureCliCredential
from fabric_cicd import FabricWorkspace, publish_all_items

parser = argparse.ArgumentParser(description="Deploy PBIP to Fabric")
parser.add_argument("--workspace_id", type=str, required=True, help="Target workspace ID")
parser.add_argument("--environment", type=str, default="dev", help="Environment name")
args = parser.parse_args()

# Use AzureCliCredential in CI/CD, fall back to InteractiveBrowserCredential for local
try:
    credential = AzureCliCredential()
except Exception:
    credential = InteractiveBrowserCredential()

workspace_params = {
    "workspace_id": args.workspace_id,
    "environment": args.environment,
    "repository_directory": ".",
    "item_type_in_scope": ["SemanticModel", "Report"],
    "token_credential": credential,
}

target_workspace = FabricWorkspace(**workspace_params)
publish_all_items(target_workspace)

4. Dispiegazione

Eseguire lo script di distribuzione con l'ID dell'area di lavoro:

python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111"

Viene aperto il browser per l'autenticazione. Dopo l'accesso, fabric-cicd distribuisce i file PBIP nell'area di lavoro di destinazione. Vengono visualizzati messaggi di stato come:

[info] Publishing SemanticModel 'SalesAnalytics'
       Operation in progress. Checking again in 1 second (Attempt 1)...
       Published

[info] Publishing Report 'SalesAnalytics'
       Published

La distribuzione richiede in genere 20-30 secondi a seconda delle dimensioni del modello semantico.

Annotazioni

La prima volta che si distribuisce un modello semantico con origini dati, è necessario configurare manualmente le credenziali dell'origine dati nel portale di Fabric. Recarsi a Impostazioni dell'area di lavoro > modello semantico > Credenziali origine dati >. Le distribuzioni successive riutilizzano le credenziali salvate.

Parametrizzazione specifica dell'ambiente

Una delle funzionalità più potenti di fabric-cicd è la possibilità di parametrizzare i file PBIP per ambienti diversi. Questo è essenziale quando i modelli semantici fanno riferimento a risorse specifiche dell'ambiente, ad esempio ID area di lavoro, ID lakehouse o stringhe di connessione.

Esempio: Parametrizzare l'area di lavoro e gli ID lakehouse

Creare un parameter.yml file nella radice del progetto per definire valori specifici dell'ambiente:

find_replace:
  # Replace workspace ID for DirectLake connection
  - find_value: "11111111-1111-1111-1111-111111111111"
    replace_value:
      dev: "11111111-1111-1111-1111-111111111111"  # Dev workspace
      prod: "22222222-2222-2222-2222-222222222222"  # Prod workspace

  # Replace lakehouse ID for DirectLake semantic model
  - find_value: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
    replace_value:
      dev: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"  # Dev lakehouse
      prod: "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"  # Prod lakehouse

Quando si esegue python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev, fabric-cicd lo fa automaticamente:

  1. Legge il file parameter.yml
  2. Trova tutte le istanze di find_value nei file di definizione PBIP.
  3. Li sostituisce con i corrispondenti specifici per l'ambiente replace_value
  4. Distribuisce le definizioni modificate nell'area di lavoro di destinazione

Automatizzare la distribuzione

È possibile automatizzare l'esecuzione delle distribuzioni PBIP ogni volta che il codice viene unito in rami specifici nel repository. L'automazione segue questa logica:

  1. Una pipeline o un flusso di lavoro si attiva quando viene eseguito il push del codice in un ramo configurato (ad esempio, dev o main)
  2. Il nome del ramo determina l'ambiente di destinazione e l'ID dell'area di lavoro
  3. Lo script di distribuzione viene eseguito automaticamente con i parametri appropriati
  4. Gli artefatti PBIP vengono distribuiti nell'area di lavoro corretta per tale ambiente

Questa sezione illustra i passaggi di configurazione comuni sia per Azure DevOps che per GitHub Actions, seguiti da istruzioni di configurazione specifiche della piattaforma.

Configurazione

Prima di configurare la piattaforma CI/CD, completare questi passaggi di configurazione comuni:

1. Creare un'entità servizio

Creare un'entità servizio in Azure AD con ruolo di Contributor o di Administrator sulle aree di lavoro di Fabric.

2. Aggiungere un'entità servizio alle aree di lavoro di Fabric

  1. Aprire il portale di Fabric e passare a ogni area di lavoro di destinazione (sviluppo, produzione)
  2. Vai a Impostazioni dell'area di lavoro > Gestione accesso
  3. Aggiungere il principale del servizio con il ruolo di Collaboratore o Amministratore

Annotazioni

Le entità servizio devono essere abilitate a livello di tenant per usare le Fabric API. Per ulteriori informazioni, vedere I principali di servizio possono chiamare le API pubbliche di Fabric.

3. Configurare i branch nel tuo repository

Creare i rami che verranno usati per l'automazione. Per gli esempi in questo articolo:

  1. Creare un branch dev per le distribuzioni nell'ambiente di sviluppo
  2. Creare un main ramo per le distribuzioni dell'ambiente di produzione

È possibile personalizzare i nomi dei rami e aggiungere altri ambienti modificando i mapping delle aree di lavoro nei file YAML.

Azure DevOps

Automatizzare le distribuzioni PBIP con Azure Pipelines. Quando viene eseguito il push del codice in rami configurati, la pipeline viene distribuita automaticamente nell'area di lavoro corrispondente.

Crea azure-pipelines.yml nella radice del repository:

trigger:
  branches:
    include:
      - dev
      - main

variables:
  - name: workspace_ids
    value: |
      {
        "dev": "11111111-1111-1111-1111-111111111111",
        "main": "22222222-2222-2222-2222-222222222222"
      }
  - name: environments
    value: |
      {
        "dev": "dev",
        "main": "prod"
      }

stages:
  - stage: Deploy
    jobs:
      - job: DeployPBIP
        pool:
          vmImage: 'windows-latest'
        steps:
          - checkout: self
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.12'
              addToPath: true
          - task: AzureCLI@2
            displayName: 'Deploy PBIP to Fabric'
            inputs:
              azureSubscription: 'your-azure-service-connection'
              scriptType: 'ps'
              scriptLocation: 'inlineScript'
              inlineScript: |
                cd "$(Build.SourcesDirectory)"
                
                pip install fabric-cicd
                
                $branch_ref = $env:BUILD_SOURCEBRANCH
                $branch_name = $branch_ref -replace '^refs/heads/', ''
                
                $workspace_ids = '$(workspace_ids)' | ConvertFrom-Json
                $environments = '$(environments)' | ConvertFrom-Json
                
                $workspace_id = $workspace_ids.$branch_name
                $environment = $environments.$branch_name
                
                python -u deploy.py --workspace_id "$workspace_id" --environment "$environment"
                
                if ($LASTEXITCODE -ne 0) {
                    Write-Error "Deployment failed with exit code: $LASTEXITCODE"
                    exit $LASTEXITCODE
                }

Configurare Azure DevOps

  1. Creare una connessione al servizio di Azure nelle impostazioni del progetto Azure DevOps:
    • Vai a Impostazioni progetto > Connessioni al servizio
    • Creare una nuova connessione al servizio Azure Resource Manager usando le credenziali dell'entità servizio
    • Per istruzioni dettagliate, vedere Connettersi a Microsoft Azure
    • Aggiornare il azureSubscription valore in YAML in modo che corrisponda al nome della connessione al servizio
  2. Aggiornare gli ID dell'area di lavoro in YAML:
    • Modificare la variabile workspace_ids in azure-pipelines.yml
    • Imposta gli ID dell'area di lavoro di sviluppo e produzione
    • Effettuare il commit e il push delle modifiche sul repository
  3. Creare la pipeline:
    • Passare a Pipeline > nuova pipeline
    • Seleziona il tuo repository e scegli "File YAML esistente di Azure Pipelines"
    • Seleziona azure-pipelines.yml
    • Per istruzioni dettagliate, vedere Creare la prima pipeline
    • Salva ed esegui la pipeline per distribuire il PBIP su Fabric

GitHub Actions

Automatizzare le distribuzioni PBIP con GitHub Actions. Quando viene eseguito il push del codice in rami configurati, il flusso di lavoro viene distribuito automaticamente nell'area di lavoro corrispondente.

Crea .github/workflows/deploy.yml nel repository:

name: Deploy PBIP to Fabric

on:
  push:
    branches: [dev, main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      
      - name: Set workspace variables
        id: workspace
        shell: pwsh
        run: |
          $branch_name = "${{ github.ref_name }}"
          
          $workspace_ids = @{
            "dev" = "11111111-1111-1111-1111-111111111111"
            "main" = "22222222-2222-2222-2222-222222222222"
          }
          
          $environments = @{
            "dev" = "dev"
            "main" = "prod"
          }
          
          $workspace_id = $workspace_ids[$branch_name]
          $environment = $environments[$branch_name]
          
          echo "workspace_id=$workspace_id" >> $env:GITHUB_OUTPUT
          echo "environment=$environment" >> $env:GITHUB_OUTPUT
      
      - name: Azure Login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
      
      - name: Deploy PBIP to Fabric
        shell: pwsh
        run: |
          pip install fabric-cicd
          
          python -u deploy.py --workspace_id "${{ steps.workspace.outputs.workspace_id }}" --environment "${{ steps.workspace.outputs.environment }}"
          
          if ($LASTEXITCODE -ne 0) {
              Write-Error "Deployment failed with exit code: $LASTEXITCODE"
              exit $LASTEXITCODE
          }

Configurare GitHub Actions

  1. Creare il segreto delle credenziali di Azure:

    • Ottieni le credenziali del principale del servizio in formato JSON: 
      {
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "subscriptionId": "<azure-subscription-id>",
  "tenantId": "<azure-tenant-id>"
}
    • Passare al repository GitHub Impostazioni > segreti e variabili > Azioni
    • Aggiungere AZURE_CREDENTIALS con il JSON sopra menzionato

  2. Aggiornare gli ID dell'area di lavoro nel flusso di lavoro:

    • Modificare la workspace_ids tabella hash nella fase "Imposta le variabili dell'area di lavoro" in .github/workflows/deploy.yml
    • Imposta gli ID dell'area di lavoro di sviluppo e produzione
    • Eseguire il commit e il push del flusso di lavoro YAML nel repository

Contenuti correlati

  • Last updated on