Wdrażanie projektów Power BI (PBIP) przy użyciu fabric-cicd

Ważne

Projekty Power BI Desktop są obecnie w fazie podglądu.

fabric-cicd to biblioteka Pythona opracowana przez firmę Microsoft, która zapewnia deweloperom Fabric metodykę "code-first" umożliwiającą wdrażanie elementów Fabric z systemu kontroli wersji do obszarów roboczych przy użyciu takich formatów definicji kodu, jak modele semantyczne i raporty w formacie PBIP.

W tym artykule dowiesz się, jak:

• Ręczne wdrażanie plików PBIP z komputera lokalnego
• Parametryzowanie plików PBIP dla konfiguracji specyficznych dla środowiska
• Automatyzacja wdrożeń z wykorzystaniem docelowych obszarów roboczych opartych na gałęziach przy użyciu Azure DevOps lub GitHub Actions

Dowiedz się więcej o formacie PBIP w projektach programu Power BI Desktop (PBIP) i omówieniu integracji Git z platformą Fabric.

Dlaczego używać fabric-cicd do wdrażania PBIP?

"Fabric-cicd jest specjalnie zaprojektowany do wdrażania artefaktów Fabric kontrolowanych przez system zarządzania wersjami i oferuje kilka zalet:"

• Korzysta z natywnych interfejsów API REST usługi Fabric — oparta na oficjalnych interfejsach API usługi Microsoft Fabric, zapewniając zgodność i długoterminową pomoc techniczną
• Natywny dla języka Python — bezproblemowa integracja z nowoczesnymi przepływami pracy DevOps opartymi na języku Python
• Parametryzacja: wbudowana obsługa konfiguracji specyficznych dla środowiska (identyfikatory obszarów roboczych, źródła danych, parametry połączenia)
• Przyjazne dla deweloperów: proste skrypty Pythona, które można uruchamiać lokalnie lub w potokach CI/CD
• Elastyczna kontrola wdrażania: Wdrażanie tylko określonych typów elementów (np. modeli semantycznych bez raportów lub semantycznych modeli z pamięcią podręczną danych lub bez ich użycia) i zapewnienie spójnych konfiguracji, takich jak strony domyślne lub parametry bez interwencji ręcznej
• Oczyszczanie oddzielone: automatycznie usuwa elementy z obszaru roboczego, które nie istnieją już w kontroli źródła
• Niezawodne uwierzytelnianie: używa zestawu Azure Identity SDK z wieloma opcjami uwierzytelniania

Uwaga / Notatka

Aby uzyskać pełną dokumentację, zobacz dokumentację fabric-cicd.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz:

• Python (wersja 3.9 do 3.12)
• Projekt programu Power BI Desktop zapisany w formacie PBIP
• Dostęp do obszaru roboczego usługi Microsoft Fabric z rolą współautora

W przypadku wdrożeń automatycznych potrzebne są również następujące elementy:

• Jednostka usługi z co najmniej rolą Współautor w docelowych obszarach roboczych sieci szkieletowej
• Dostęp do usługi Azure DevOps lub GitHub Actions
• Twoje pliki PBIP w kontroli źródła (Git, Azure DevOps lub GitHub)

Szybki start

W tym przewodniku Szybki start pokazano, jak wdrożyć projekt PBIP z komputera lokalnego do obszaru roboczego usługi Fabric.

1. Zainstaluj fabric-cicd

Otwórz terminal i zainstaluj plik fabric-cicd:

pip install fabric-cicd

2. Przygotowanie projektu PBIP

Upewnij się, że projekt PBIP zawiera wymagane pliki. Typowa struktura projektu PBIP:

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

Aby uzyskać szczegółowe informacje na temat wymaganych plików i formatów, zobacz folder raportu projektu programu Power BI Desktop i folder semantyczny modelu projektu programu Power BI Desktop.

Wskazówka

Aby utworzyć projekt PBIP, otwórz plik PBIX w programie Power BI Desktop i zapisz go przy użyciu polecenia Zapisz > jako > Power BI Project (.pbip). Aby uzyskać więcej informacji, zobacz Projekty programu Power BI Desktop .

3. Tworzenie skryptu wdrażania

deploy.py Utwórz plik w katalogu projektu:

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. Wdrażanie

Uruchom skrypt wdrożenia przy użyciu identyfikatora obszaru roboczego:

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

Zostanie otwarta przeglądarka na potrzeby uwierzytelniania. Po zalogowaniu, narzędzie fabric-cicd wdraża pliki PBIP do docelowej przestrzeni roboczej. Zobaczysz komunikaty o postępie, takie jak:

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

[info] Publishing Report 'SalesAnalytics'
       Published

Wdrożenie zwykle trwa 20–30 sekund w zależności od rozmiaru modelu semantycznego.

Uwaga / Notatka

Przy pierwszym wdrożeniu modelu semantycznego ze źródłami danych należy ręcznie skonfigurować poświadczenia źródła danych w portalu sieci szkieletowej. Przejdź do obszaru roboczego >, modelu semantycznego >, Ustawienia > Poświadczenia źródła danych. Kolejne wdrożenia ponownie wykorzystają zapisane poświadczenia.

Parametryzacja specyficzna dla środowiska

Jedną z najbardziej wydajnych funkcjonalności fabric-cicd jest możliwość sparametryzowania plików PBIP dla różnych środowisk. Jest to niezbędne, gdy modele semantyczne odwołują się do zasobów specyficznych dla środowiska, takich jak identyfikatory obszarów roboczych, identyfikatory usługi Lakehouse lub parametry połączenia.

Przykład: Parametryzowanie środowisk roboczych i identyfikatorów lakehouse

parameter.yml Utwórz plik w katalogu głównym projektu, aby zdefiniować wartości specyficzne dla środowiska:

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

Po uruchomieniu python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev, fabric-cicd automatycznie:

1. Odczytuje plik parameter.yml
2. Znajduje wszystkie wystąpienia find_value w plikach definicji PBIP
3. Zamienia je na odpowiednie elementy specyficzne dla danego środowiska replace_value
4. Wdraża zmodyfikowane definicje w docelowym obszarze roboczym

Automatyzowanie wdrażania

Wdrożenia usługi PBIP można zautomatyzować w celu uruchamiania za każdym razem, gdy kod jest scalony z określonymi gałęziami w repozytorium. Automatyzacja jest zgodna z tą logiką:

1. Potok danych lub przepływ pracy jest uruchamiany, gdy kod jest wypychany do skonfigurowanej gałęzi (np. dev lub main)
2. Nazwa gałęzi określa środowisko docelowe i identyfikator obszaru roboczego
3. Skrypt wdrażania jest uruchamiany automatycznie z odpowiednimi parametrami
4. Artefakty usługi PBIP są wdrażane w odpowiednim obszarze roboczym dla tego środowiska

W tej sekcji opisano kroki konfiguracji typowe dla usług Azure DevOps i GitHub Actions, a następnie instrukcje dotyczące konfiguracji specyficzne dla platformy.

Ustawienia

Przed skonfigurowaniem platformy ciągłej integracji/ciągłego wdrażania wykonaj następujące typowe kroki konfiguracji:

1. Utwórz zasadę usługi

Utwórz jednostkę usługi w ramach Azure AD z rolą Współpracownik lub Administrator w obszarach roboczych Fabric.

2. Dodawanie głównego użytkownika usługi do obszarów roboczych Fabric

1. Otwórz portal Fabric i przejdź do każdego docelowego obszaru roboczego (dev, prod)
2. Przejdź do pozycji Ustawienia obszaru roboczego > Zarządzaj dostępem
3. Dodaj jednostkę usługi z rolą Współautora lub Administratora

Uwaga / Notatka

Jednostki usługi muszą być włączone na poziomie dzierżawy, aby korzystać z interfejsów API sieci szkieletowej. Aby uzyskać więcej informacji, zobacz Pełnomocnicy usługi mogą wywoływać publiczne interfejsy API usługi Fabric.

3. Konfigurowanie gałęzi w repozytorium

Utwórz gałęzie, których będziesz używać do automatyzacji. Przykłady w tym artykule:

1. Utwórz dev gałąź dla wdrożeń w środowisku deweloperskim
2. Utwórz main gałąź dla wdrożeń środowiska produkcyjnego

Możesz dostosować nazwy gałęzi i dodać więcej środowisk, modyfikując mapowania obszarów roboczych w plikach YAML.

Azure DevOps

Automatyzowanie wdrożeń usługi PBIP za pomocą usługi Azure Pipelines. Gdy kod jest przesyłany do skonfigurowanych gałęzi, pipeline jest automatycznie wdrażany w odpowiednim obszarze roboczym.

Utwórz azure-pipelines.yml w katalogu głównym repozytorium:

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
                }

Skonfiguruj Azure DevOps

1. Utwórz połączenie usługi platformy Azure w ustawieniach projektu usługi Azure DevOps:
   • Przejdź do Ustawień projektu > Połączenia usługi
   • Tworzenie nowego połączenia usługi Azure Resource Manager przy użyciu poświadczeń jednostki usługi
   • Aby uzyskać szczegółowe instrukcje, zobacz Nawiązywanie połączenia z platformą Microsoft Azure
   • azureSubscription Zaktualizuj wartość w yaML, aby odpowiadała nazwie połączenia usługi
2. Zaktualizuj identyfikatory obszarów roboczych w języku YAML:
   • Edytowanie zmiennej workspace_ids w azure-pipelines.yml
   • Ustawianie identyfikatorów obszarów roboczych deweloperskich i prod
   • Zatwierdź i wypchnij zmiany do swojego repozytorium
3. Utwórz potok:
   • Przejdź do obszaru Potoki > Nowy potok
   • Wybierz repozytorium i zaznacz pozycję "Istniejący plik YAML usługi Azure Pipelines"
   • Wybierz azure-pipelines.yml
   • Aby uzyskać szczegółowe instrukcje, zobacz Tworzenie pierwszego potoku
   • Zapisz i uruchom potok, aby wdrożyć usługę PBIP w Fabric

GitHub Actions

Automatyzowanie wdrożeń usługi PBIP za pomocą funkcji GitHub Actions. Gdy kod jest wypychany do skonfigurowanych gałęzi, przepływ pracy jest automatycznie wdrażany w odpowiednim obszarze roboczym.

Utwórz .github/workflows/deploy.yml w repozytorium:

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
          }

Konfigurowanie funkcji GitHub Actions

1. Utwórz sekret poświadczeń Azure:

   • Pobierz poświadczenia obiektu usługi w formacie JSON:

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

   • Przejdź do Ustawienia repozytorium GitHub > Sekrety i zmienne > Akcje
   • Dodaj AZURE_CREDENTIALS wraz z powyższym JSON-em

2. Zaktualizuj identyfikatory obszarów roboczych w przepływie pracy:

   • Edytuj tabelę skrótu workspace_ids w kroku "Ustawianie zmiennych obszaru roboczego" w .github/workflows/deploy.yml
   • Ustawianie identyfikatorów obszarów roboczych deweloperskich i prod
   • Zatwierdź i wypchnij plik YAML z przepływem pracy do swojego repozytorium

Treści powiązane

• dokumentacja fabric-cicd
• repozytorium GitHub o nazwie fabric-cicd
• Omówienie integracji z Git w Fabric
• Planowanie implementacji usługi Power BI: Zarządzanie cyklem życia zawartości