Menyebarkan proyek Power BI (PBIP) menggunakan fabric-cicd

Penting

Proyek Power BI Desktop saat ini dalam pratinjau.

fabric-cicd adalah pustaka Python yang dikembangkan oleh Microsoft yang menyediakan metode code-first bagi pengembang Fabric untuk menyebarkan item Fabric dari kontrol sumber ke ruang kerja menggunakan format definisi kode mereka, seperti model semantik dan laporan menggunakan format file PBIP.

Dalam artikel ini, Anda akan mempelajari cara:

Menyebarkan file PBIP secara manual dari komputer lokal Anda
Membuat parameter file PBIP untuk konfigurasi khusus lingkungan
Mengotomatiskan penyebaran dengan penargetan ruang kerja berbasis cabang menggunakan Azure DevOps atau GitHub Actions

Pelajari selengkapnya tentang format PBIP di proyek Power BI Desktop (PBIP) dan gambaran umum integrasi Fabric Git.

Mengapa fabric-cicd untuk implementasi PBIP?

fabric-cicd dirancang khusus untuk menyebarkan artefak Fabric yang dikontrol sumber dan menawarkan beberapa keuntungan:

Menggunakan REST API asli Fabric - Dibangun di atas API Microsoft Fabric resmi, memastikan kompatibilitas dan dukungan jangka panjang
Python-native - Integrasi mulus dengan alur kerja DevOps berbasis Python modern
Parameterisasi: Dukungan bawaan untuk konfigurasi khusus lingkungan (ID ruang kerja, sumber data, string koneksi)
Ramah pengembang: Skrip Python sederhana yang dapat berjalan secara lokal atau di alur CI/CD
Kontrol penyebaran fleksibel: Sebarkan hanya jenis item tertentu (misalnya, model semantik tanpa laporan, atau model semantik dengan atau tanpa cache data) dan pastikan konfigurasi yang konsisten seperti halaman atau parameter default tanpa intervensi manual
Pembersihan yatim piatu: Secara otomatis menghapus item dari ruang kerja yang tidak lagi ada di kontrol sumber
Autentikasi andal: Menggunakan Azure Identity SDK dengan beberapa opsi autentikasi

Nota

Untuk dokumentasi lengkap, lihat dokumentasi fabric-cicd.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Python (versi 3.9 hingga 3.12)
Proyek Power BI Desktop disimpan dalam format PBIP
Akses ke ruang kerja Microsoft Fabric dengan peran Kontributor

Untuk penyebaran otomatis, Anda juga perlu:

Perwakilan layanan dengan peran setidaknya sebagai Kontributor di ruang kerja Fabric yang ditargetkan
Akses ke Azure DevOps atau GitHub Actions
File PBIP Anda di kontrol sumber (Git, Azure DevOps, atau GitHub)

Memulai dengan Cepat

Panduan memulai cepat ini menunjukkan cara untuk menyebarkan proyek PBIP dari komputer lokal Anda ke ruang kerja Fabric.

1. Instal fabric-cicd

Buka terminal Anda dan instal fabric-cicd:

pip install fabric-cicd

2. Siapkan proyek PBIP Anda

Pastikan proyek PBIP Anda menyertakan file yang diperlukan. Struktur proyek PBIP yang khas:

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

Untuk informasi terperinci tentang file dan format yang diperlukan, lihat folder laporan proyek Power BI Desktop dan folder model semantik proyek Power BI Desktop.

Petunjuk / Saran

Untuk membuat proyek PBIP, buka file PBIX Anda di Power BI Desktop dan simpan menggunakan File > Simpan Sebagai > Proyek Power BI (.pbip). Lihat Proyek Power BI Desktop untuk detail selengkapnya.

3. Buat skrip penyebaran

Buat deploy.py file di direktori proyek Anda:

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

Jalankan skrip penyebaran dengan ID ruang kerja Anda:

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

Browser Anda terbuka untuk autentikasi. Setelah masuk, fabric-cicd menyebarkan file PBIP Anda ke ruang kerja target. Anda melihat pesan kemajuan seperti:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Penyebaran biasanya membutuhkan waktu 20-30 detik tergantung pada ukuran model semantik Anda.

Nota

Pertama kali Anda menyebarkan model semantik dengan sumber data, Anda perlu mengonfigurasi kredensial sumber data secara manual di portal Fabric. Pergi ke ruang kerja > model semantik > Pengaturan > kredensial sumber data. Penyebaran berikutnya menggunakan kembali kredensial yang disimpan.

Parameterisasi khusus lingkungan

Salah satu fitur fabric-cicd yang paling kuat adalah kemampuan untuk membuat parameter file PBIP Anda untuk lingkungan yang berbeda. Ini penting ketika model semantik Anda mereferensikan sumber daya khusus lingkungan seperti ID ruang kerja, ID lakehouse, atau string koneksi.

Contoh: Membuat parameter ID ruang kerja dan lakehouse

Buat parameter.yml file di akar proyek Anda untuk menentukan nilai khusus lingkungan:

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

Saat Anda menjalankan python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev, fabric-cicd akan bekerja secara otomatis.

Membaca file parameter.yml
Menemukan semua kemunculan find_value dalam berkas definisi PBIP Anda
Mengganti elemen-elemen tersebut dengan yang spesifik untuk lingkungan replace_value yang sesuai
Menyebarkan definisi yang dimodifikasi ke ruang kerja target

Mengotomatiskan penyebaran

Anda dapat mengotomatiskan penyebaran PBIP untuk dijalankan setiap kali kode digabungkan ke cabang tertentu di repositori Anda. Otomatisasi mengikuti logika ini:

Alur atau workflow akan terpicu ketika kode dikirimkan ke cabang yang sudah dikonfigurasi (misalnya, dev atau main)
Nama cabang menentukan lingkungan target dan ID ruang kerja
Skrip penyebaran berjalan secara otomatis dengan parameter yang sesuai
Artefak PBIP Anda disebarkan ke ruang kerja yang benar untuk lingkungan tersebut

Bagian ini mencakup langkah-langkah penyiapan yang umum untuk Azure DevOps dan GitHub Actions, diikuti dengan instruksi konfigurasi khusus platform.

Pengaturan

Sebelum mengonfigurasi platform CI/CD Anda, selesaikan langkah-langkah penyiapan umum ini:

1. Buat principal layanan

Buat service principal di Azure AD dengan peran Kontributor atau Admin di ruang kerja Fabric Anda.

2. Tambahkan prinsipal layanan ke ruang kerja Fabric

Buka portal Fabric dan navigasikan ke setiap ruang kerja target (dev, prod)
Pergi ke Pengaturan Ruang Kerja > Kelola akses
Menambahkan perwakilan layanan dengan peran Kontributor atau Admin

Nota

Prinsipal layanan harus diaktifkan di tingkat penyewa untuk menggunakan Fabric API. Untuk informasi selengkapnya, lihat Perwakilan layanan dapat memanggil API publik Fabric.

3. Mengonfigurasi cabang di repositori Anda

Buat cabang yang akan Anda gunakan untuk otomatisasi. Untuk contoh dalam artikel ini:

Membuat dev cabang untuk penyebaran lingkungan pengembangan
Buatlah main branch untuk penyebaran di lingkungan produksi

Anda dapat menyesuaikan nama cabang dan menambahkan lebih banyak lingkungan dengan memodifikasi pemetaan ruang kerja dalam file YAML.

Azure DevOps

Mengotomatiskan penyebaran PBIP dengan Azure Pipelines. Ketika kode didorong ke cabang yang dikonfigurasi, alur secara otomatis disebarkan ke ruang kerja yang sesuai.

Buat azure-pipelines.yml di akar repositori Anda:

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
                }

Mengonfigurasi Azure DevOps

Buat koneksi layanan Azure di pengaturan proyek Azure DevOps:
- Masuk ke Pengaturan Proyek > koneksi layanan
- Membuat koneksi layanan Azure Resource Manager baru menggunakan kredensial perwakilan layanan Anda
- Untuk instruksi mendetail, lihat Menyambungkan ke Microsoft Azure
- azureSubscription Perbarui nilai di YAML agar sesuai dengan nama koneksi layanan Anda
Perbarui ID ruang kerja di YAML:
- Edit variabel workspace_ids dalam azure-pipelines.yml
- Atur ID ruang kerja dev dan prod Anda
- Melakukan commit dan push perubahan ke repositori Anda
Buat alur:
- Buka Pipeline > Pipeline baru
- Pilih repositori Anda dan pilih "File YAML Alur Azure yang Ada"
- Pilih azure-pipelines.yml
- Untuk petunjuk terperinci, lihat Membuat alur pertama Anda
- Simpan dan jalankan alur untuk menyebarkan PBIP Anda ke Fabric

Tindakan GitHub

Mengotomatisasi penerapan PBIP dengan GitHub Actions. Ketika kode didorong ke cabang yang dikonfigurasi, alur kerja secara otomatis disebarkan ke ruang kerja yang sesuai.

Buat .github/workflows/deploy.yml di repositori Anda:

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
          }

Mengonfigurasi GitHub Actions

Buat rahasia kredensial Azure:
- Dapatkan kredensial perwakilan layanan Anda dalam format JSON:
```
{
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "subscriptionId": "<azure-subscription-id>",
  "tenantId": "<azure-tenant-id>"
}
```
- Buka Pengaturan repositori GitHub > Rahasia dan variabel > Tindakan
- Tambahkan AZURE_CREDENTIALS dengan JSON di atas
Perbarui ID ruang kerja dalam alur kerja:
- workspace_ids Edit hashtable di langkah "Atur variabel ruang kerja" di.github/workflows/deploy.yml
- Atur ID ruang kerja dev dan prod Anda
- Commit dan push berkas YAML alur kerja ke repositori Anda

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-01-23

Bagikan melalui

Menyebarkan proyek Power BI (PBIP) menggunakan fabric-cicd

Mengapa fabric-cicd untuk implementasi PBIP?

Prasyarat

Memulai dengan Cepat

1. Instal fabric-cicd

2. Siapkan proyek PBIP Anda

3. Buat skrip penyebaran

4. Terapkan

Parameterisasi khusus lingkungan

Contoh: Membuat parameter ID ruang kerja dan lakehouse

Mengotomatiskan penyebaran

Pengaturan

1. Buat principal layanan

2. Tambahkan prinsipal layanan ke ruang kerja Fabric

3. Mengonfigurasi cabang di repositori Anda

Azure DevOps

Mengonfigurasi Azure DevOps

Tindakan GitHub

Mengonfigurasi GitHub Actions

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: