Delen via

Power BI-projecten (PBIP) implementeren met fabric-cicd

Belangrijk

Power BI Desktop-projecten zijn momenteel beschikbaar als preview-versie.

fabric-cicd is een Python-bibliotheek die is ontwikkeld door Microsoft, dat een code-first methode biedt voor Fabric-ontwikkelaars om Fabric-items te implementeren van broncodebeheer naar werkruimten met behulp van hun codedefinitie-indeling, zoals semantische modellen en rapporten met behulp van de PBIP-bestandsindeling.

In dit artikel leert u het volgende:

  • PBIP-bestanden handmatig implementeren vanaf uw lokale computer
  • PBIP-bestanden parameteriseren voor omgevingsspecifieke configuraties
  • Automatiseer implementaties met branch-gebaseerde werkruimten door gebruik te maken van Azure DevOps of GitHub Actions

Meer informatie over PBIP-indeling in Power BI Desktop-projecten (PBIP) en overzicht van Git-integratie met Fabric.

Waarom fabric-cicd voor PBIP-implementatie?

fabric-cicd is speciaal ontworpen voor het implementeren van brongestuurde Fabric-artefacten en biedt verschillende voordelen:

  • Maakt gebruik van systeemeigen REST API's van Fabric - gebouwd op officiële Microsoft Fabric-API's, waardoor compatibiliteit en langetermijnondersteuning worden gegarandeerd
  • Systeemeigen Python - naadloze integratie met moderne DevOps-werkstromen op basis van Python
  • Parameterisatie: ingebouwde ondersteuning voor omgevingsspecifieke configuraties (werkruimte-id's, gegevensbronnen, verbindingsreeksen)
  • Ontwikkelaarsvriendelijk: Eenvoudige Python-scripts die lokaal of in CI/CD-pijplijnen kunnen worden uitgevoerd
  • Flexibel implementatiebeheer: implementeer alleen specifieke itemtypen (bijvoorbeeld semantische modellen zonder rapporten of semantische modellen met of zonder gegevenscache) en zorg voor consistente configuraties zoals standaardpagina's of parameters zonder handmatige tussenkomst
  • Verweesde opschoning: Verwijdert automatisch items uit de werkruimte die niet meer bestaan in het broncodebeheer.
  • Betrouwbare verificatie: Maakt gebruik van Azure Identity SDK met meerdere verificatieopties

Opmerking

Zie de fabric-cicd-documentatie voor volledige documentatie.

Vereiste voorwaarden

Voordat u begint, moet u ervoor zorgen dat u het volgende hebt:

  • Python (versie 3.9 tot 3.12)
  • Een Power BI Desktop-project dat is opgeslagen in PBIP-indeling
  • Toegang tot een Microsoft Fabric-werkruimte met de rol Inzender

Voor geautomatiseerde implementaties hebt u ook het volgende nodig:

  • Een service-principal met ten minste de rol Inzender voor doel-Fabric-werkruimten
  • Toegang tot Azure DevOps of GitHub Actions
  • Uw PBIP-bestanden in broncodebeheer (Git, Azure DevOps of GitHub)

Snel aan de slag

In deze snelle start legt u uit hoe u een PBIP-project vanaf uw computer implementeert in een Fabric-werkruimte.

1. fabric-cicd installeren

Open uw terminal en installeer fabric-cicd:

pip install fabric-cicd

2. Uw PBIP-project voorbereiden

Zorg ervoor dat uw PBIP-project de vereiste bestanden bevat. Een typische PBIP-projectstructuur:

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

Voor gedetailleerde informatie over de vereiste bestanden en indelingen, zie de Power BI Desktop-projectrapportmap en de semantische modelmap van het Power BI Desktop-project.

Aanbeveling

Als u een PBIP-project wilt maken, opent u uw PBIX-bestand in Power BI Desktop en slaat u het op met Bestand > Opslaan als > Power BI-project (.pbip). Zie Power BI Desktop-projecten voor meer informatie.

3. Implementatiescript maken

Maak een deploy.py bestand in de projectmap:

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

Voer het implementatiescript uit met uw werkruimte-id:

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

Uw browser wordt geopend voor verificatie. Nadat u zich hebt aangemeld, implementeert fabric-cicd uw PBIP-bestanden in de doelwerkruimte. U ziet voortgangsberichten zoals:

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

[info] Publishing Report 'SalesAnalytics'
       Published

De implementatie duurt doorgaans 20-30 seconden, afhankelijk van de grootte van uw semantische model.

Opmerking

De eerste keer dat u een semantisch model met gegevensbronnen implementeert, moet u de referenties van de gegevensbron handmatig configureren in de Fabric-portal. Ga naar werkruimte > semantisch model > Instellingen > Gegevensbronreferenties. Volgende implementaties gebruiken de opgeslagen referenties opnieuw.

Omgevingsspecifieke parameterisatie

Een van de krachtigste functies van fabric-cicd is de mogelijkheid om uw PBIP-bestanden te parameteriseren voor verschillende omgevingen. Dit is essentieel wanneer uw semantische modellen verwijzen naar omgevingsspecifieke resources, zoals werkruimte-id's, lakehouse-id's of verbindingsreeksen.

Voorbeeld: Werkruimte- en lakehouse-id's parameteriseren

Maak een parameter.yml bestand in de hoofdmap van uw project om omgevingsspecifieke waarden te definiëren:

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

Wanneer je python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev uitvoert, voert fabric-cicd automatisch:

  1. Leest het parameter.yml-bestand
  2. Hiermee vindt u alle exemplaren van find_value in uw PBIP-definitiebestanden
  3. Vervangt deze door de bijbehorende omgevingsspecifieke replace_value
  4. Hiermee worden de gewijzigde definities geïmplementeerd in de doelwerkruimte

Implementatie automatiseren

U kunt PBIP-implementaties automatiseren zodat ze worden uitgevoerd wanneer code wordt samengevoegd in specifieke branches in uw repository. De automatisering volgt deze logica:

  1. Een pijplijn of werkstroom triggert wanneer code naar een geconfigureerde vertakking wordt gepusht (bijvoorbeeld dev of main)
  2. De naam van de vertakking bepaalt de doelomgeving en de werkruimte-ID
  3. Het implementatiescript wordt automatisch uitgevoerd met de juiste parameters
  4. Uw PBIP-artefacten worden geïmplementeerd in de juiste werkruimte voor die omgeving

In deze sectie worden de installatiestappen beschreven die gebruikelijk zijn voor zowel Azure DevOps als GitHub Actions, gevolgd door platformspecifieke configuratie-instructies.

Inrichten

Voordat u uw CI/CD-platform configureert, voert u de volgende algemene installatiestappen uit:

1. Een service-principal maken

Maak een service-principal in Azure AD met de rol Inzender of Beheerder in uw Fabric-werkruimten.

2. Service-principal toevoegen aan Fabric-werkruimten

  1. Open de Fabric-portal en navigeer naar elke doelwerkruimte (dev, prod)
  2. Ga naar Werkruimte-instellingen > : toegang beheren
  3. De service-principal toevoegen met de rol Inzender of Beheerder

Opmerking

Service-principals moeten zijn ingeschakeld op tenantniveau om Fabric-API's te kunnen gebruiken. Zie Service-principals openbare Fabric-API's aanroepen voor meer informatie.

Configureer de vertakkingen in uw opslagplaats

Maak de vertakkingen die u gaat gebruiken voor automatisering. Voor de voorbeelden in dit artikel:

  1. Maak een dev branch voor implementaties van ontwikkelomgevingen
  2. Een main tak maken voor implementaties in de productieomgeving

U kunt vertakkingsnamen aanpassen en meer omgevingen toevoegen door de werkruimtetoewijzingen in de YAML-bestanden te wijzigen.

Azure DevOps

AUTOMATISEER PBIP-implementaties met Azure Pipelines. Wanneer code naar geconfigureerde vertakkingen wordt gepusht, wordt de pijplijn automatisch geïmplementeerd in de bijbehorende werkruimte.

Maak azure-pipelines.yml in de hoofdmap van uw opslagplaats.

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
                }

Stel Azure DevOps in

  1. Maak een Azure-serviceverbinding in azure DevOps-projectinstellingen:
    • Ga naar Projectinstellingen > Serviceverbindingen
    • Een nieuwe Azure Resource Manager-serviceverbinding maken met behulp van uw service-principalreferenties
    • Zie Verbinding maken met Microsoft Azure voor gedetailleerde instructies
    • Werk de azureSubscription waarde in de YAML bij zodat deze overeenkomt met de naam van uw serviceverbinding
  2. Werk de werkruimte-id's in de YAML bij:
    • workspace_ids De variabele bewerken in azure-pipelines.yml
    • Stel uw dev- en prod-werkruimte-id's in
    • Voer de wijzigingen door en push ze naar uw repository
  3. Maak de pijplijn:
    • Ga naar Pijplijnen > Nieuwe pijplijn
    • Selecteer uw opslagplaats en kies 'Bestaand YAML-bestand voor Azure Pipelines'
    • Selecteer azure-pipelines.yml
    • Zie Uw eerste pijplijn maken voor gedetailleerde instructies
    • Sla de pijplijn op en voer deze uit om uw PBIP in Fabric te implementeren

GitHub Actions (GitHub-acties)

AUTOMATISEER PBIP-implementaties met GitHub Actions. Wanneer code naar geconfigureerde takken wordt gepusht, wordt de workflow automatisch gedistribueerd naar de bijbehorende werkruimte.

Maak .github/workflows/deploy.yml in je 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
          }

GitHub Actions configureren

  1. Maak het Azure-referentiesgeheim:

    • Haal uw service-principal referenties op in JSON-indeling: 
      {
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "subscriptionId": "<azure-subscription-id>",
  "tenantId": "<azure-tenant-id>"
}
    • Ga naar de instellingen van de GitHub-opslagplaats > Geheimen en variabelen > Acties
    • Voeg AZURE_CREDENTIALS toe met de JSON hierboven

  2. Werk de werkruimte-id's in de werkstroom bij:

    • Bewerk de workspace_ids hashtabel in de stap Werkruimtevariabelen instellen in .github/workflows/deploy.yml
    • Stel uw dev- en prod-werkruimte-id's in
    • De YAML van de werkstroom doorvoeren en pushen naar uw opslagplaats

Verwante inhoud

  • Last updated on