Partager via

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

Important

Les projets Power BI Desktop sont actuellement en préversion.

fabric-cicd est une bibliothèque Python développée par Microsoft qui fournit une méthode code-first permettant aux développeurs Fabric de déployer des éléments Fabric à partir du contrôle de version dans des espaces de travail en utilisant leur format de définition de code, tels que des modèles sémantiques et des rapports au format de fichier PBIP.

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 à l’aide du ciblage d’espace de travail par branche avec Azure DevOps ou GitHub Actions

En savoir plus sur le format PBIP dans les projets Power BI Desktop (PBIP) et l’aperçu de l’intégration Fabric Git.

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 :

  • Utilise les API REST natives de Fabric - Basées sur les API Microsoft Fabric officielles, garantissant ainsi la compatibilité et la prise en charge à long terme
  • Python natif - Intégration transparente avec les flux de travail DevOps modernes basés sur 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)
  • Convivial pour les développeurs : scripts 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 comme les pages par défaut ou les paramètres 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 le Kit de développement logiciel (SDK) Azure Identity avec plusieurs options d’authentification

Note

Pour obtenir une documentation complète, consultez la documentation fabric-cicd.

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 le dossier de rapports de projet Power BI Desktop et le dossier de modèle sémantique de projet Power BI Desktop.

Conseil / Astuce

Pour créer un projet PBIP, ouvrez votre fichier PBIX dans Power BI Desktop et enregistrez-le à l'aide de Fichier > Enregistrer sous > Projet Power BI (.pbip). Pour plus d’informations, consultez les projets Power BI Desktop .

3. Créer un script de déploiement

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

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. Déployer

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

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

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.

Note

La première fois que vous déployez un modèle sémantique avec des sources de données, vous devez configurer manuellement les informations d’identification de la source de données dans le portail Fabric. Accédez à l'espace de travail > modèle sémantique > Paramètres > Informations d'identification de la source de données. Les déploiements suivants réutilisent les informations d’identification enregistrées.

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 parameter.yml 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 python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev, fabric-cicd fonctionne automatiquement.

  1. Lit le fichier parameter.yml
  2. Recherche toutes les instances de find_value dans vos fichiers de définition PBIP
  3. Remplace-les par le paramètre spécifique à l’environnement correspondant replace_value
  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, dev ou main)
  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 à Azure DevOps et 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 un 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

Note

Les principaux de service doivent être activés au niveau du locataire pour utiliser les API Fabric. Pour plus d'informations, consultez les principaux de service peuvent appeler les API publiques Fabric.

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 dev pour le déploiement dans un environnement de développement
  2. Créer branche main 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 azure-pipelines.yml dans la racine de votre référentiel :

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
                }

Configurer Azure DevOps

  1. Créez 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 nouvelle connexion de service Azure Resource Manager à l’aide de vos identifiants de principal du service
    • Pour obtenir des instructions détaillées, consultez Se connecter à Microsoft Azure
    • Mettez à jour la valeur dans YAML pour qu’elle azureSubscription corresponde au nom de votre connexion de service
  2. Mettez à jour les ID d’espace de travail dans yaML :
    • Modifier la workspace_ids variable dans azure-pipelines.yml
    • Définissez vos ID d’espace de travail de développement et de production
    • 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 .github/workflows/deploy.yml 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_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
          }

Configurer GitHub Actions

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

    • Obtenez les informations d’identification de votre service principal, au format JSON : 
      {
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "subscriptionId": "<azure-subscription-id>",
  "tenantId": "<azure-tenant-id>"
}
    • Accéder aux paramètres > Secrets et variables > Actions du référentiel GitHub
    • Ajouter AZURE_CREDENTIALS avec le JSON ci-dessus

  2. Mettez à jour les ID d’espace de travail dans le flux de travail :

    • Modifier la workspace_ids table de hachage dans l’étape « Définir les variables d’espace de travail » dans .github/workflows/deploy.yml
    • Définissez vos ID d’espace de travail de développement et de production
    • Validez et poussez le fichier YAML du flux de travail vers votre référentiel

Contenu connexe

  • Last updated on