Déployer des projets Power BI (PBIP) à l’aide de fabric-cicd

fabric-cicd est une bibliothèque Python open source officiellement prise en charge par Microsoft qui fournit une méthode code-first pour les développeurs Fabric de déployer des éléments Fabric du contrôle de code source vers des espaces de travail à l’aide de leur format de définition de code, comme des modèles sémantiques et des rapports au format de fichier PBIP. L’outil s’intègre à l’intégration Git Fabric, aux API REST Fabric et à l’interface CLI Fabric pour permettre des flux de déploiement cohérents entre les espaces de travail.

Dans cet article, vous allez apprendre à :

• Déployer manuellement des fichiers PBIP à partir de votre ordinateur local
• Paramétrer les fichiers PBIP pour les configurations spécifiques à l’environnement
• Automatiser les déploiements avec le ciblage d’espace de travail basé sur des branches à l’aide de Azure DevOps ou de GitHub Actions

En savoir plus sur le format PBIP dans Power BI Projets de bureau (PBIP) et Vue d’ensemble de l’intégration Git deFabric.

Pourquoi fabric-cicd pour le déploiement PBIP ?

Fabric-cicd est spécifiquement conçu pour déployer des artefacts Fabric contrôlés par la source et offre plusieurs avantages :

• Utilisation des API REST natives de Fabric - Construit sur les API officielles de Microsoft Fabric, assurant la compatibilité et le support à long terme
• Gestion automatisée des dépendances : détermine l’ordre de déploiement correct et résout les dépendances entre les éléments (tels que la publication de modèles sémantiques avant les rapports), la réduction du séquencement manuel et la réduction des erreurs de déploiement
• Python native - Intégration transparente avec les flux de travail DevOps modernes basés sur des Python
• Paramétrage - Prise en charge intégrée des configurations spécifiques à l’environnement (ID d’espace de travail, sources de données, chaînes de connexion)
• Developer-friendly - Scripts de Python simples qui peuvent s’exécuter localement ou dans des pipelines CI/CD
• Contrôle de déploiement flexible : déployer uniquement des types d’éléments spécifiques (par exemple, des modèles sémantiques sans rapports, des modèles sémantiques avec ou sans cache de données) et garantir des configurations cohérentes telles que les pages ou paramètres par défaut sans intervention manuelle
• Nettoyage orphelin : supprime automatiquement les éléments de l’espace de travail qui n’existent plus dans le contrôle de code source
• Authentification fiable - Utilise Azure Sdk Identity avec plusieurs options d’authentification

Prerequisites

Avant de commencer, vérifiez que vous disposez des points suivants :

• Python (version 3.9 à 3.12)
• Un projet Power BI Desktop enregistré au format PBIP
• Accès à un espace de travail Microsoft Fabric avec le rôle Contributeur

Pour les déploiements automatisés, vous avez également besoin des éléments suivants :

• Un principal de service avec au moins le rôle Contributeur sur les espaces de travail Fabric cibles
• Accès à Azure DevOps ou GitHub Actions
• Vos fichiers PBIP dans le contrôle de code source (Git, Azure DevOps ou GitHub)

Démarrage rapide

Ce guide de démarrage rapide vous montre comment déployer un projet PBIP à partir de votre ordinateur local vers un espace de travail Fabric.

1. Installer le fabric-cicd

Ouvrez votre terminal et installez fabric-cicd :

pip install fabric-cicd

2. Préparer votre projet PBIP

Vérifiez que votre projet PBIP inclut les fichiers requis. Structure de projet PBIP classique :

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

Pour plus d’informations sur les fichiers et les formats requis, consultez Power BI dossier de rapports de projet de bureau et Power BI dossier de modèle sémantique de projet Desktop.

3. Créer un script de déploiement

Créez un fichier dans le répertoire de votre projet :

import argparse
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_name", type=str, required=False, help="Target workspace name", default="PBIP Fabric CICD Dev")
parser.add_argument("--environment", type=str, default="dev", help="Environment name")
parser.add_argument("--spn-auth", action="store_true", help="Use SPN authentication via Azure CLI")
args = parser.parse_args()

# Use InteractiveBrowserCredential for local development, AzureCliCredential for CI/CD pipelines
if not args.spn_auth:
    credential = InteractiveBrowserCredential()
else:
    credential = AzureCliCredential()

workspace_params = {
    "workspace_name": args.workspace_name,
    "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. Déployer

Exécutez le script de déploiement avec le nom de votre espace de travail :

python deploy.py --workspace_name "PBIP Fabric CICD Dev"

Votre navigateur s’ouvre pour l’authentification. Une fois connecté, fabric-cicd déploie vos fichiers PBIP sur l’espace de travail cible. Vous voyez des messages de progression tels que :

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

[info] Publishing Report 'SalesAnalytics'
       Published

Le déploiement prend généralement 20 à 30 secondes en fonction de la taille de votre modèle sémantique.

Paramétrage spécifique à l’environnement

L’une des fonctionnalités les plus puissantes de fabric-cicd est la possibilité de paramétrer vos fichiers PBIP pour différents environnements. Cela est essentiel lorsque vos modèles sémantiques référencent des ressources spécifiques à l’environnement, telles que les ID d’espace de travail, les ID lakehouse ou les chaînes de connexion.

Exemple : Paramétrer les ID d’espace de travail et de lakehouse

Créez un fichier à la racine de votre projet pour définir des valeurs spécifiques à l’environnement :

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

Lorsque vous exécutez , fabric-cicd fonctionne automatiquement.

1. Lit le fichier parameter.yml
2. Recherche toutes les instances de dans vos fichiers de définition PBIP
3. Remplace-les par le paramètre spécifique à l’environnement correspondant
4. Déploie les définitions modifiées sur l’espace de travail cible

Automatiser le déploiement

Vous pouvez automatiser les déploiements PBIP pour s’exécuter chaque fois que le code est fusionné dans des branches spécifiques de votre référentiel. L’automatisation suit cette logique :

1. Un pipeline ou un flux de travail se déclenche lorsque le code est envoyé à une branche configurée (par exemple, ou )
2. Le nom de la branche détermine l’environnement cible et l’ID d’espace de travail
3. Le script de déploiement s’exécute automatiquement avec les paramètres appropriés
4. Vos artefacts PBIP se déploient sur l’espace de travail approprié pour cet environnement

Cette section décrit les étapes de configuration communes aux Azure DevOps et aux GitHub Actions, suivies d’instructions de configuration spécifiques à la plateforme.

Configurer

Avant de configurer votre plateforme CI/CD, procédez comme suit :

1. Créer un principal de service

Créez un principal de service dans Azure AD avec le rôle Contributeur ou Administrateur sur vos espaces de travail Fabric.

2. Ajouter un service principal aux espaces de travail Fabric

1. Ouvrez le portail Fabric et accédez à chaque espace de travail cible (dev, prod)
2. Accéder aux paramètres de l’espace de travail Gérer l’accès
3. Ajouter le principal de service avec le rôle Contributeur ou Administrateur

3. Configurer des branches dans votre référentiel

Créez les branches que vous utiliserez pour l’automatisation. Pour obtenir les exemples de cet article :

1. Créer une branche pour le déploiement dans un environnement de développement
2. Créer branche pour les déploiements dans l'environnement de production

Vous pouvez personnaliser les noms de branche et ajouter d’autres environnements en modifiant les mappages d’espace de travail dans les fichiers YAML.

Azure DevOps

Automatisez les déploiements PBIP avec Azure Pipelines. Lorsque le code est poussé vers des branches configurées, le pipeline se déploie automatiquement sur l’espace de travail correspondant.

Créez dans la racine de votre référentiel :

trigger:
  branches:
    include:
      - dev
      - main

variables:
  - name: workspace_names
    value: |
      {
        "dev": "PBIP Fabric CICD Dev",
        "main": "PBIP Fabric CICD Prod"
      }
  - 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_names = '$(workspace_names)' | ConvertFrom-Json
                $environments = '$(environments)' | ConvertFrom-Json
                
                $workspace_name = $workspace_names.$branch_name
                $environment = $environments.$branch_name
                
                python -u deploy.py --spn-auth --workspace_name "$workspace_name" --environment "$environment"
                
                if ($LASTEXITCODE -ne 0) {
                    Write-Error "Deployment failed with exit code: $LASTEXITCODE"
                    exit $LASTEXITCODE
                }

Configurer Azure DevOps

1. Créer une connexion de service Azure dans les paramètres du projet Azure DevOps :
   • Accéder aux Paramètres du projet, connexions de service
   • Créer une connexion de service Azure Resource Manager utilisant vos informations d’identification de principal du service
   • Pour obtenir des instructions détaillées, consultez Connect to Microsoft Azure
   • Mettez à jour la valeur dans YAML pour qu’elle corresponde au nom de votre connexion de service
2. Mettez à jour les noms de l’espace de travail dans YAML :
   • Modifier la variable dans azure-pipelines.yml
   • Définir les noms de votre espace de travail dev et prod
   • Valider et envoyer (push) les modifications à votre référentiel
3. Créez le pipeline :
   • Accédez à Pipelines Nouveau pipeline
   • Sélectionnez votre référentiel et choisissez « Fichier YAML Azure Pipelines existant »
   • Sélectionnez azure-pipelines.yml
   • Pour obtenir des instructions détaillées, consultez Créer votre premier pipeline
   • Enregistrez et exécutez le pipeline pour déployer votre PBIP sur Fabric

GitHub Actions

Automatisez les déploiements PBIP avec GitHub Actions. Lorsque le code est envoyé (push) à des branches configurées, le flux de travail se déploie automatiquement sur l’espace de travail correspondant.

Créez dans votre référentiel :

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_names = @{
            "dev" = "PBIP Fabric CICD Dev"
            "main" = "PBIP Fabric CICD Prod"
          }
          
          $environments = @{
            "dev" = "dev"
            "main" = "prod"
          }
          
          $workspace_name = $workspace_names[$branch_name]
          $environment = $environments[$branch_name]
          
          echo "workspace_name=$workspace_name" >> $env:GITHUB_OUTPUT
          echo "environment=$environment" >> $env:GITHUB_OUTPUT
      
      - name: Azure Login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
          allow-no-subscriptions: true
      
      - name: Deploy PBIP to Fabric
        shell: pwsh
        run: |
          pip install fabric-cicd
          
          python -u deploy.py --spn-auth --workspace_name "${{ steps.workspace.outputs.workspace_name }}" --environment "${{ steps.workspace.outputs.environment }}"
          
          if ($LASTEXITCODE -ne 0) {
              Write-Error "Deployment failed with exit code: $LASTEXITCODE"
              exit $LASTEXITCODE
          }

Configurer GitHub Actions

1. Créer le secret des informations d’identification de Azure :

   • Obtenez les informations d’identification de votre service principal, au format JSON :

     {
       "clientId": "<service-principal-client-id>",
       "clientSecret": "<service-principal-secret>",
       "tenantId": "<azure-tenant-id>"
     }
     

   • Accédez aux paramètres du référentiel GitHub > Secrets et variables > Actions
   • Ajouter avec le JSON ci-dessus

2. Mettez à jour les noms de l’espace de travail dans le flux de travail :

   • Modifier la table de hachage dans l’étape « Définir les variables d’espace de travail » dans
   • Définir les noms de votre espace de travail dev et prod
   • Validez et poussez le fichier YAML du flux de travail vers votre référentiel

Contenu connexe

• documentation fabric-cicd
• dépôt GitHub fabric-cicd
• Vue d’ensemble de l’intégration Fabric Git
• Power BI planification de l’implémentation : gestion du cycle de vie du contenu