Käynnistä Power BI -projektit (PBIP) fabric-cicd:llä

fabric-cicd on virallisesti tuettu, Microsoftin tukema avoimen lähdekoodin Python-kirjasto, joka tarjoaa Fabric-kehittäjille koodin ensisijaisen tavan ottaa käyttöön Fabric-elementtejä lähdekoodinhallinnasta työtiloihin käyttäen niiden koodimäärittelymuotoa, kuten semanttisia malleja ja raportteja PBIP-tiedostomuodossa. Työkalu integroituu Fabric Git -integraatioon, Fabric REST API:iin ja Fabric CLI:hen, mikä mahdollistaa johdonmukaiset käyttöönottovirrat eri työtiloissa.

Tässä artikkelissa opit

• Ota PBIP-tiedostot käyttöön manuaalisesti paikalliselta koneelta
• Parametrisoi PBIP-tiedostot ympäristökohtaisia konfiguraatioita varten
• Automatisoi käyttöönotot haarapohjaisella työtilakohdistuksella Azure DevOps tai GitHub Actions

Lue lisää PBIP-muodosta Power BI Desktop projects (PBIP) ja Fabric Git -integraatiokatsaus.

Miksi fabric-cicd PBIP:n käyttöönotossa?

fabric-cicd on suunniteltu erityisesti lähdeohjattujen Fabric-artefaktien käyttöönottoon ja tarjoaa useita etuja:

• Käyttää Fabricin natiiveja REST-rajapintoja - Rakennettu virallisille Microsoft Fabric-rajapinnoille, varmistaen yhteensopivuuden ja pitkäaikaisen tuen
• Automatisoitu riippuvuuksien käsittely – Määrittää oikean käyttöönottojärjestyksen ja ratkaisee kohteiden väliset riippuvuudet (kuten semanttisten mallien julkaiseminen ennen raportteja), mikä vähentää manuaalista sekvensointia ja minimoi käyttöönottovirheitä
• Python-native – Saumaton integraatio nykyaikaisiin Python-pohjaisiin DevOps-työnkulkuihin
• Parametrisointi – sisäinen tuki ympäristökohtaisille kokoonpanoille (työtilan tunnukset, tietolähteet, yhteysmerkkijonot)
• Kehittäjäystävällinen – Yksinkertaiset Python-skriptit, jotka voivat ajaa paikallisesti tai CI/CD-putkistoissa
• Joustava käyttöönoton hallinta : ota käyttöön vain tietyt kohdetyypit (esimerkiksi semanttiset mallit ilman raportteja tai semanttiset mallit, joissa on tai ei ole tietovälimuistia) ja varmista yhdenmukaiset kokoonpanot, kuten oletussivut tai parametrit ilman manuaalista käyttöä
• Orpojen puhdistus – poistaa työtilasta automaattisesti kohteet, joita ei enää ole lähteen hallinnassa
• Luotettava todennus - Käyttää Azure Identity SDK:ta useilla todennusvaihtoehdoilla

Edellytykset

Varmista ennen aloittamista, että sinulla on:

• Python (versiot 3.9–3.12)
• Power BI Desktop -projekti tallennettuna PBIP-muotoon
• Pääsy Microsoft Fabric -työtilaan Contributor -roolin kanssa

Automaattisiin käyttöönottoihin tarvitset myös:

• Palvelupäähenkilö, jolla on vähintään Contributor -rooli kohde-Fabric-työtiloissa
• Access to Azure DevOps tai GitHub Actions
• PBIP-tiedostosi lähdekoodin hallinnassa (Git, Azure DevOps tai GitHub)

Pika-aloitus

Tämä nopea alku näyttää, miten PBIP-projekti otetaan käyttöön paikallisesta koneestasi Fabric-työtilaan.

1. Asenna kangas-cicd

Avaa terminaali ja asenna fabric-cicd:

pip install fabric-cicd

2. Valmistele PBIP-projektisi

Varmista, että PBIP-projektissasi on tarvittavat tiedostot. Tyypillinen PBIP-projektirakenne:

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

Tarkempia tietoja vaadituista tiedostoista ja formaateista löytyy Power BI Työpöytäprojektiraporttikansio ja Power BI Työpöytäprojektin semanttinen mallikansio.

3. Luo käyttöönottoskripti

Luo deploy.py tiedosto projektihakemistoosi:

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. Lähetä

Suorita käyttöönottoskripti työtilan nimellä:

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

Selaimesi avautuu tunnistautumista varten. Kirjautumisen jälkeen fabric-cicd ottaa PBIP-tiedostosi käyttöön kohdetyötilaan. Näet edistymisviestejä kuten:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Käyttöönotto kestää tyypillisesti 20–30 sekuntia semanttisen mallin koosta riippuen.

Ympäristökohtainen parametrisointi

Yksi fabric-cicd:n tehokkaimmista ominaisuuksista on kyky parametrisoida PBIP-tiedostot eri ympäristöille. Tämä on olennaista, kun semanttiset mallit viittaavat ympäristökohtaisiin resursseihin, kuten työtilan ID:ihin, järvitalotunnisteisiin tai yhteysmerkkijonoihin.

Esimerkki: Parametrisoi työtila ja järvitalo-ID:t

Luo parameter.yml tiedosto projektin juureen määritelläksesi ympäristökohtaiset arvot:

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

Kun suoritat python deploy.py --workspace_name "PBIP Fabric CICD Dev" --environment dev, fabric-cicd automaattisesti:

1. Lukee parameter.yml-tiedoston
2. Löytää kaikki instanssit find_value PBIP-määrittelutiedostoistasi
3. Korvaa ne vastaavalla ympäristökohtaisella replace_value
4. Ottaa muokatut määritelmät käyttöön kohdetyötilassa

Automatisoi käyttöönotto

Voit automatisoida PBIP-käyttöönotot aina, kun koodi yhdistetään tiettyihin haaroihin varastossasi. Automaatio noudattaa tätä logiikkaa:

1. Putki tai työnkulku käynnistyy, kun koodi lähetetään konfiguroituun haaraan (esim. dev tai main)
2. Haaran nimi määrittää kohdeympäristön ja työtilan ID:n
3. Käyttöönottoskripti suoritetaan automaattisesti sopivilla parametreilla
4. PBIP-artefaktit sijoituvat oikeaan työtilaan kyseiselle ympäristölle

Tässä osiossa käsitellään asennusvaiheita, jotka ovat yleisiä sekä Azure DevOps:lle että GitHub Actions:lle, ja sen jälkeen on alustakohtaiset konfigurointiohjeet.

Asetusten määrittäminen

Ennen CI/CD-alustan konfigurointia suorita nämä yleiset asennusvaiheet:

1. Luo palveluperiaate

Luo palvelupäähenkilö Azure AD:ssa Contributor- tai Admin-roolilla Fabric-työtiloissasi.

2. Lisää palveluperiaate Fabric-työtiloihin

1. Avaa Fabric-portaali ja siirry jokaiseen kohdetyötilaan (kehittäjä, tuotanto)
2. Mene Workspace Settings > -kohtaan Hallinnoi pääsyä
3. Lisää palvelupäähenkilö Contributorin tai Adminin rooliin

3. Määritä haarat varastossasi

Luo haarat, joita käytät automaatioon. Tässä artikkelissa olevat esimerkit:

1. Luo haara dev kehitysympäristön käyttöönottoa varten
2. Luo haara main tuotantoympäristön käyttöönottoja varten

Voit muokata haarojen nimiä ja lisätä lisää ympäristöjä muokkaamalla YAML-tiedostojen työtilan karttoja.

Azure DevOps

Automatisoi PBIP-käyttöönotot Azure Pipelines -ohjelmalla. Kun koodia työnnetään konfiguroituihin haaroihin, putkisto siirtyy automaattisesti vastaavaan työtilaan.

Luo azure-pipelines.yml arkistosi juureen:

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
                }

Azure DevOps määrittäminen

1. Luo Azure palveluyhteys Azure DevOps projektiasetuksissa:
   • Mene Projektiasetuksiin > Palveluyhteydet
   • Luo uusi Azure Resource Manager -palveluyhteys käyttäen palvelupäähenkilön tunnuksiasi
   • Yksityiskohtaiset ohjeet löydät Connect to Microsoft Azure
   • Päivitä YAML:n azureSubscription arvo vastaamaan palveluyhteyden nimeä
2. Päivitä työtilan nimet YAML:ssä:
   • Muokkaa muuttujaa workspace_names azure-pipelines.yml
   • Aseta kehittäjä- ja tuotantotyötilojen nimet
   • Sitoudu ja työnnä muutokset repositorioosi
3. Luo putkisto:
   • Mene kohtaan Pipelines > Uudet putkisto
   • Valitse repositoriosi ja valitse "Existing Azure Pipelines YAML file"
   • Valitse azure-pipelines.yml
   • Yksityiskohtaiset ohjeet löydät kohdasta Luo ensimmäinen putki
   • Tallenna ja suorita putkisto, jotta PBIP voidaan ottaa käyttöön Fabriciin

GitHub Actions

Automatisoi PBIP-käyttöönotot GitHub Actions -toiminnolla. Kun koodi lähetetään konfiguroituihin haaroihin, työnkulku siirtyy automaattisesti vastaavaan työtilaan.

Luo .github/workflows/deploy.yml tietovarastoosi:

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
          }

GitHub Actions määrittäminen

1. Luo Azure tunnistetiedot salassa:

   • Hanki palveluspäämiehen tunnuksesi JSON-muodossa:

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

   • Mene GitHub repositoryn asetuksiin > Salaisuudet ja muuttujat > Toiminnot
   • Lisää AZURE_CREDENTIALS yllä oleva JSON

2. Päivitä työnkulun työtilan nimet:

   • Muokkaa hajautustaulua workspace_names "Aseta työtilamuuttujat" -vaiheessa .github/workflows/deploy.yml
   • Aseta kehittäjä- ja tuotantotyötilojen nimet
   • Sitoudu ja työnnä työntyönkulun YAML repositorioosi

Aiheeseen liittyvä sisältö

• Fabric-CICD-dokumentaatio
• kangas- GitHub säilö
• Fabric Git -integraation yleiskatsaus
• Power BI toteutussuunnittelu: Sisällön elinkaaren hallinta