Power BI -projektien (PBIP) käyttöönotto fabric-cicd:n avulla

Tärkeää

Power BI Desktop -projektit ovat tällä hetkellä esikatseluvaiheessa.

fabric-cicd on Microsoftin kehittämä Python-kirjasto, joka tarjoaa Fabric-kehittäjille koodilähtöisen menetelmän Fabric-elementtien käyttöönottoon lähdekoodin hallinnasta työtiloihin käyttäen koodimäärittelymuotoa, kuten semanttisia malleja ja raportteja PBIP-tiedostomuodossa.

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 DevOpsin tai GitHub Actionsin avulla

Lue lisää PBIP-muodosta Power BI Desktop Projectsissa (PBIP) ja Fabric Git -integraation yleiskatsauksesta.

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 API:lle, varmistaen yhteensopivuuden ja pitkäaikaisen tuen
• Python-natiivi – Saumaton integraatio nykyaikaisiin Python-pohjaisiin DevOps-työnkulkuihin
• Parametrisointi: Sisäänrakennettu tuki ympäristökohtaisille konfiguraatioille (työtilan ID:t, tietolähteet, yhteysmerkkijonot)
• Kehittäjäystävällinen: Yksinkertaiset Python-skriptit, jotka toimivat paikallisesti tai CI/CD-putkistoissa
• Joustava käyttöönoton hallinta: Ota käyttöön vain tietyt alkiotyypit (esim. semanttiset mallit ilman raportteja tai semanttiset mallit, joissa on tai ilman datavälimuistia) ja varmista johdonmukaiset asetukset, kuten oletussivut tai parametrit, ilman manuaalista puuttumista
• Orphan-puhdistus: Poistaa automaattisesti työtilasta kohteet, joita ei enää ole lähdekoodin hallinnassa
• Luotettava tunnistautuminen: Käyttää Azure Identity SDK:ta useilla todennusvaihtoehdoilla

Note

Täydellistä dokumentaatiota löytyy fabric-cicd-dokumentaatiosta.

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 Contributorin roolilla

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

Yksityiskohtaista tietoa vaadituista tiedostoista ja formaateista löydät Power BI Desktop -projektiraporttikansiosta ja Power BI Desktop -projektin semanttisen mallin kansiosta.

Tip

Luodaksesi PBIP-projektin, avaa PBIX-tiedostosi Power BI Desktopissa ja tallenna se File > Save As > Power BI Project (.pbip) -toiminnolla. Katso lisätietoja Power BI Desktop -projekteista .

3. Luo käyttöönottoskripti

Luo deploy.py tiedosto projektihakemistoosi:

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

Suorita käyttöönottoskripti työtilan ID:llä:

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

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.

Note

Ensimmäisellä kerralla, kun otat käyttöön semanttisen mallin tietolähteillä, sinun täytyy konfiguroida tietolähteiden tunnistetiedot manuaalisesti Fabric-portaalissa. Mene Workspace > Semantic Model > Settings > Data source credentials -kohtaan. Myöhemmissä käyttöönotoissa tallennetut tunnukset kierrätetään.

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_id "11111111-1111-1111-1111-111111111111" --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 Azure DevOpsin ja GitHub Actionsin yhteisiä asennusvaiheita, joita seuraavat alustakohtaiset konfiguraatio-ohjeet.

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

Note

Palveluperiaatteet on oltava käytössä vuokralaistasolla, jotta ne voivat käyttää Fabric-rajapintoja. Lisätietoja löytyy kohdasta Service principals can call Fabricin julkisia API-rajapintoja.

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 Pipelinesilla. 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_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
                }

Configure Azure DevOps

1. Luo Azure Service Connection Azure DevOps -projektiasetuksissa:
   • Mene Projektiasetuksiin > Palveluyhteydet
   • Luo uusi Azure Resource Manager -palveluyhteys käyttämällä palvelupäähenkilön tunnuksiasi
   • Yksityiskohtaiset ohjeet löytyvät katsosta Connect to Microsoft Azure
   • Päivitä YAML:n azureSubscription arvo vastaamaan palveluyhteyden nimeä
2. Päivitä työtilan ID:t YAML:ssä:
   • Muokkaa muuttujaa workspace_ids azure-pipelines.yml
   • Aseta kehittäjä- ja tuotantotyötila-ID:t
   • Sitoudu ja työnnä muutokset repositorioosi
3. Luo putkisto:
   • Mene kohtaan Pipelines > Uudet putkisto
   • Valitse repositoriosi ja valitse "Existing Azure Pipelines YAML -tiedosto"
   • 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-toiminnoilla. 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_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
          }

Määritä GitHub-toiminnot

1. Luo Azure-tunnuksen salaisuus:

   • Hanki palveluspäämiehen tunnuksesi JSON-muodossa:

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

   • Mene GitHub-repositorioon Asetukset > Salaisuudet ja muuttujat > Toiminnot
   • Lisää AZURE_CREDENTIALS yllä oleva JSON

2. Päivitä työtilan ID:t työnkulussa:

   • Muokkaa hajautustaulua workspace_ids "Aseta työtilamuuttujat" -vaiheessa .github/workflows/deploy.yml
   • Aseta kehittäjä- ja tuotantotyötila-ID:t
   • Sitoudu ja työnnä työntyönkulun YAML repositorioosi

Aiheeseen liittyvä sisältö

• Fabric-CICD-dokumentaatio
• fabric-cicd GitHub-repository
• Fabric Git -integraation yleiskatsaus
• Power BI:n toteutussuunnittelu: Sisällön elinkaaren hallinta