Fabric-cicd kullanarak Power BI projelerini (PBIP) dağıtma

Önemli

Power BI Desktop projeleri şu anda önizleme aşamasındadır.

fabric-cicd , Microsoft tarafından geliştirilen ve Doku geliştiricilerine, PBIP dosya biçimini kullanan anlamsal modeller ve raporlar gibi kod tanım biçimlerini kullanarak Doku öğelerini kaynak denetimden çalışma alanlarına dağıtmak için kod öncelikli bir yöntem sağlayan bir Python kitaplığıdır.

Bu makalede şunları öğreneceksiniz:

• PBIP dosyalarını yerel makinenizden el ile dağıtma
• Ortama özgü yapılandırmalar için PBIP dosyalarını parametreleştirme
• Azure DevOps veya GitHub Actions kullanarak dal tabanlı çalışma alanı hedeflemesi ile dağıtımları otomatikleştirme

Power BI Desktop projelerinde PBIP biçimi hakkında ve Fabric Git tümleştirmeye genel bakış hakkında daha fazla bilgi edinin.

PBIP dağıtımı için neden fabric-cicd?

fabric-cicd, kaynak kontrolünde Fabric bileşenlerini dağıtmak için özel olarak tasarlandı ve çeşitli avantajlar sunar:

• Fabric yerel REST API'lerini kullanır - Uyumluluğu ve uzun vadeli desteği sağlamak için resmi Microsoft Fabric API'leri üzerine kurulmuştur
• Python'a özel - Modern Python tabanlı DevOps iş akışlarıyla sorunsuz tümleştirme
• Parametreleştirme: Ortama özgü yapılandırmalar (çalışma alanı kimlikleri, veri kaynakları, bağlantı dizeleri) için yerleşik destek
• Geliştirici dostu: Yerel olarak veya CI/CD işlem hatlarında çalışabilen basit Python betikleri
• Esnek dağıtım denetimi: Yalnızca belirli öğe türlerini (örneğin, rapor içermeyen anlamsal modeller veya veri önbelleği olan veya olmayan anlamsal modeller) dağıtın ve el ile müdahale olmadan varsayılan sayfalar veya parametreler gibi tutarlı yapılandırmalar sağlayın
• Yetim temizleme: Artık kaynak denetiminde bulunmayan öğeleri çalışma alanından otomatik olarak kaldırır
• Güvenilir kimlik doğrulaması: Birden çok kimlik doğrulama seçeneğiyle Azure Kimlik SDK'sı kullanır

Uyarı

Tam belgeler için fabric-cicd belgelerine bakın.

Önkoşullar

Başlamadan önce şunların olduğundan emin olun:

• Python (sürüm 3.9 - 3.12)
• PBIP biçiminde kaydedilmiş bir Power BI Desktop projesi
• Katılımcı rolüne sahip bir Microsoft Fabric çalışma alanına erişim

Otomatik dağıtımlar için şunları da yapmanız gerekir:

• Hedef Doku çalışma alanlarında en az Katkıda Bulunan rolüne sahip bir hizmet sorumlusu
• Azure DevOps veya GitHub Actions'a erişim
• Kaynak denetimindeki PBIP dosyalarınız (Git, Azure DevOps veya GitHub)

Hızlı başlangıç

Bu hızlı başlangıç, yerel makinenizden bir Fabric çalışma alanına PBIP projesi dağıtımının nasıl yapılacağını gösterir.

1. Fabric-cicd yükleme

Terminalinizi açın ve fabric-cicd'i yükleyin:

pip install fabric-cicd

2. PBIP projenizi hazırlama

PBIP projenizin gerekli dosyaları içerdiğinden emin olun. Tipik bir PBIP proje yapısı:

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

Gerekli dosyalar ve biçimler hakkında ayrıntılı bilgi için bkz. Power BI Desktop proje raporu klasörü ve Power BI Desktop proje anlam modeli klasörü.

Tip

PBIP projesi oluşturmak için PBIX dosyanızı Power BI Desktop'ta açın ve Dosya > Farklı Kaydet > Power BI Projesi (.pbip) kullanarak kaydedin. Diğer ayrıntılar için bkz. Power BI Desktop projeleri .

3. Dağıtım betiği oluşturun

Proje dizininizde bir deploy.py dosya oluşturun:

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. Dağıtım

Dağıtım betiğini çalışma alanı kimliğiniz ile çalıştırın:

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

Tarayıcınız kimlik doğrulaması için açılır. Fabric-cicd, oturum açtıktan sonra PBIP dosyalarınızı hedef çalışma alanına dağıtır. Aşağıdaki gibi ilerleme iletileri görürsünüz:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Dağıtım genellikle anlam modelinizin boyutuna bağlı olarak 20-30 saniye sürer.

Uyarı

Veri kaynaklarıyla semantik modeli ilk kez dağıttığınızda, Doku portalında veri kaynağı kimlik bilgilerini el ile yapılandırmanız gerekir. Çalışma alanı > anlam modeli > Ayarları > Veri kaynağı kimlik bilgileri'ne gidin. Sonraki dağıtımlarda kaydedilen kimlik bilgileri yeniden kullanılır.

Ortama özgü parametreleştirme

Fabric-cicd'in en güçlü özelliklerinden biri, PBIP dosyalarınızı farklı ortamlar için parametreleştirebilme özelliğidir. Anlam modelleriniz çalışma alanı kimlikleri, lakehouse kimlikleri veya bağlantı dizeleri gibi ortama özgü kaynaklara başvurduğunda bu önemlidir.

Örnek: Çalışma alanı ve lakehouse kimliklerini parametreleştirme

Ortama özgü değerleri tanımlamak için proje kökünde bir parameter.yml dosya oluşturun:

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

python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev çalıştırdığınızda, fabric-cicd otomatik olarak:

1. parameter.yml dosyasını okur
2. PBIP tanım dosyalarınızda find_value'nin tüm yerlerini bulur
3. Bunları ilgili ortama özgü değerle değiştirir replace_value
4. Değiştirilen tanımları hedef çalışma alanına dağıtır

Dağıtımı otomatikleştirme

PbIP dağıtımlarını, kod deponuzdaki belirli dallarla birleştirildiğinde çalışacak şekilde otomatikleştirebilirsiniz. Otomasyon şu mantığı izler:

1. İşlem hattı veya iş akışı, kod yapılandırılmış bir dala gönderildiğinde tetikleniyor (örneğin, dev veya main)
2. Dal adı hedef ortamı ve çalışma alanı kimliğini belirler
3. Dağıtım betiği uygun parametrelerle otomatik olarak çalışır
4. PBIP yapıtlarınız bu ortam için doğru çalışma alanına dağıtılır

Bu bölüm hem Azure DevOps hem de GitHub Actions için ortak olan kurulum adımlarını ve ardından platforma özgü yapılandırma yönergelerini kapsar.

Kurulum

CI/CD platformunuzu yapılandırmadan önce şu yaygın kurulum adımlarını tamamlayın:

1. Hizmet sorumlusu oluşturma

Azure AD'de, Fabric çalışma alanlarınızda Katkıda Bulunucu veya Yönetici rolüyle bir hizmet sorumlusu nesnesi oluşturun.

2. Fabric çalışma alanlarına hizmet ilkesi ekleme

1. Açık Fabric portalını açın ve her hedef çalışma alanına (geliştirme, üretim) gidin.
2. Çalışma Alanı Ayarları > Erişimi yönet'e gidin
3. Hizmet sorumlusunu Katkıda Bulunan veya Yönetici rolüyle ekleme

Uyarı

Doku API'lerini kullanmak için hizmet sorumlularının kiracı düzeyinde etkinleştirilmesi gerekir. Daha fazla bilgi için bkz. Hizmet sorumluları Doku genel API'lerini çağırabilir.

3. Deponuzda dalları yapılandırma

Otomasyon için kullanacağınız dalları oluşturun. Bu makaledeki örnekler için:

1. Geliştirme ortamı dağıtımları için bir dal dev oluşturun
2. Üretim ortamı dağıtımları için bir main dalı oluştur.

YAML dosyalarındaki çalışma alanı eşlemelerini değiştirerek dal adlarını özelleştirebilir ve daha fazla ortam ekleyebilirsiniz.

Azure DevOps

Azure Pipelines ile PBIP dağıtımlarını otomatikleştirme. Kod yapılandırılan dallara gönderildiğinde işlem hattı otomatik olarak ilgili çalışma alanına dağıtılır.

Depo kökünüzde azure-pipelines.yml oluşturun.

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
                }

Azure DevOps'yi yapılandırma

1. Azure DevOps proje ayarlarında Azure hizmet bağlantısı oluşturma:
   • Proje Ayarları > Hizmet bağlantıları'na gidin
   • Hizmet sorumlusu kimlik bilgilerinizi kullanarak yeni bir Azure Resource Manager hizmet bağlantısı oluşturma
   • Ayrıntılı yönergeler için bkz. Microsoft Azure'a bağlanma
   • azureSubscription YAML'deki değeri hizmet bağlantınızın adıyla eşleşecek şekilde güncelleştirin
2. YAML'de çalışma alanı kimliklerini güncelleştirin:
   • azure-pipelines.yml değişkenini workspace_ids düzenleme
   • Geliştirme ve üretim çalışma alanı kimliklerinizi ayarlayın
   • Değişiklikleri işleme ve deponuza gönderme
3. İşlem hattını oluşturun:
   • İşlem Hatları > Yeni işlem hattı'na gidin
   • Deponuzu seçin ve "Mevcut Azure Pipelines YAML dosyası" seçeneğini belirleyin
   • azure-pipelines.yml seçin
   • Ayrıntılı yönergeler için bkz. İlk işlem hattınızı oluşturma
   • PBIP'nizi Fabric'e dağıtmak için pipeline'i kaydedin ve çalıştırın.

GitHub İşlemleri

GitHub Actions ile PBIP dağıtımlarını otomatikleştirin. Kod yapılandırılan dallara gönderildiğinde, iş akışı otomatik olarak ilgili çalışma alanına dağıtılır.

Deponuzda oluşturun .github/workflows/deploy.yml :

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'ı yapılandırma

1. Azure kimlik bilgileri gizlisini oluşturun:

   • Hizmet sorumlusu kimlik bilgilerinizi JSON biçiminde alın:

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

   • GitHub deposu Ayarları > Gizli Diziler ve Değişkenler > altında Eylemler'e gidin
   • Yukarıdaki JSON ile ekleyin AZURE_CREDENTIALS

2. İş akışındaki çalışma alanı kimliklerini güncelleştirin:

   • workspace_ids"Çalışma alanı değişkenlerini ayarla" adımında karma tablo düzenleme.github/workflows/deploy.yml
   • Geliştirme ve üretim çalışma alanı kimliklerinizi ayarlayın
   • İş akışı YAML'sini işleme ve deponuza gönderme

İlgili içerik

• fabric-cicd dokümantasyonu
• fabric-cicd GitHub depo'su
• Fabric Git entegrasyonuna genel bakış
• Power BI uygulama planlaması: İçerik yaşam döngüsü yönetimi