fabric-cicd를 사용하여 PBIP(Power BI 프로젝트) 배포

중요합니다

Power BI Desktop 프로젝트는 현재 미리 보기 중입니다.

fabric-cicd 는 Microsoft에서 개발한 Python 라이브러리로, 패브릭 개발자가 PBIP 파일 형식을 사용하는 의미 체계 모델 및 보고서와 같은 코드 정의 형식을 사용하여 패브릭 항목을 소스 제어에서 작업 영역으로 배포할 수 있는 코드 우선 메서드를 제공합니다.

이 문서에서는 다음 방법을 알아봅니다.

로컬 컴퓨터에서 수동으로 PBIP 파일 배포
환경별 구성에 대한 PBIP 파일 매개 변수화
Azure DevOps 또는 GitHub Actions를 사용하여 분기 기반 작업 영역을 대상으로 하는 배포 자동화

PBIP(Power BI Desktop 프로젝트) 및 Fabric Git 통합 개요의 PBIP 형식에 대해 자세히 알아봅니다.

PBIP 배포에 왜 fabric-cicd를 사용하나요?

fabric-cicd는 원본 제어 패브릭 아티팩트 배포를 위해 특별히 설계되었으며 다음과 같은 몇 가지 이점을 제공합니다.

패브릭 네이티브 REST API 사용 - 공식 Microsoft Fabric API를 기반으로 하여 호환성 및 장기 지원 보장
Python 네이티브 - 최신 Python 기반 DevOps 워크플로와 원활하게 통합
매개 변수화: 환경별 구성(작업 영역 ID, 데이터 원본, 연결 문자열)에 대한 기본 제공 지원
개발자 친화적: 로컬 또는 CI/CD 파이프라인에서 실행할 수 있는 간단한 Python 스크립트
유연한 배포 제어: 특정 항목 유형(예: 보고서 없는 의미 체계 모델 또는 데이터 캐시 유무에 관계없이 의미 체계 모델)만 배포하고 수동 개입 없이 기본 페이지 또는 매개 변수와 같은 일관된 구성을 보장합니다.
고아 항목 정리: 소스 제어에 더 이상 존재하지 않는 항목들을 작업 영역에서 자동으로 제거합니다.
신뢰할 수 있는 인증: 여러 인증 옵션과 함께 Azure Identity SDK 사용

비고

전체 문서는 fabric-cicd 문서를 참조하세요.

필수 조건

시작하기 전에 다음이 있는지 확인합니다.

Python (버전 3.9 ~ 3.12)
PBIP 형식으로 저장된 Power BI Desktop 프로젝트
기여자 역할을 사용하여 Microsoft Fabric 작업 영역에 액세스

자동화된 배포의 경우 다음이 필요합니다.

대상 패브릭 작업 영역에서 적어도 기여자 역할이 있는 서비스 주체
Azure DevOps 또는 GitHub Actions에 대한 액세스
소스 제어의 PBIP 파일(Git, Azure DevOps 또는 GitHub)

빠른 시작

이 빠른 시작에서는 로컬 컴퓨터에서 패브릭 작업 영역으로 PBIP 프로젝트를 배포하는 방법을 보여 줍니다.

1. fabric-cicd 설치

터미널을 열고 fabric-cicd를 설치합니다.

pip install fabric-cicd

2. PBIP 프로젝트 준비

PBIP 프로젝트에 필요한 파일이 포함되어 있는지 확인합니다. 일반적인 PBIP 프로젝트 구조:

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

필요한 파일 및 형식에 대한 자세한 내용은 Power BI Desktop 프로젝트 보고서 폴더 및 Power BI Desktop 프로젝트 의미 체계 모델 폴더를 참조하세요.

팁 (조언)

PBIP 프로젝트를 만들려면 Power BI Desktop에서 PBIX 파일을 열고 Power BI 프로젝트로 파일 > 저장(.pbip)을 >사용하여 저장합니다. 자세한 내용은 Power BI Desktop 프로젝트를 참조하세요.

3. 배포 스크립트 만들기

deploy.py 프로젝트 디렉터리에 파일을 만듭니다.

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. 배포

작업 영역 ID를 사용하여 배포 스크립트를 실행합니다.

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

인증을 위해 브라우저가 열립니다. 로그인한 후 fabric-cicd는 PBIP 파일을 대상 작업 영역에 배포합니다. 다음과 같은 진행률 메시지가 표시됩니다.

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

[info] Publishing Report 'SalesAnalytics'
       Published

배포는 일반적으로 의미 체계 모델의 크기에 따라 20~30초가 걸립니다.

비고

데이터 원본을 사용하여 의미 체계 모델을 처음 배포할 때 패브릭 포털에서 데이터 원본 자격 증명을 수동으로 구성해야 합니다. 작업 영역 > 의미 체계 모델 > 설정 > 데이터 원본 자격 증명으로 이동합니다. 이후 배포에서는 저장된 자격 증명을 다시 사용합니다.

환경별 매개 변수화

패브릭-cicd의 가장 강력한 기능 중 하나는 다양한 환경에 대해 PBIP 파일을 매개 변수화하는 기능입니다. 이는 의미 체계 모델이 작업 영역 ID, Lakehouse ID 또는 연결 문자열과 같은 환경별 리소스를 참조하는 경우에 필수적입니다.

예: 작업 영역 및 레이크하우스 ID 매개 변수화

parameter.yml 프로젝트 루트에 파일을 만들어 환경별 값을 정의합니다.

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을 실행할 때 fabric-cicd는 자동으로 다음을 수행합니다.

parameter.yml 파일을 읽습니다.
PBIP 정의 파일에서 find_value 모든 인스턴스를 찾습니다.
환경별로 해당하는 replace_value로 바꿉니다.
수정된 정의를 대상 작업 영역에 배포합니다.

배포 자동화

코드가 리포지토리의 특정 분기에 병합될 때마다 실행되도록 PBIP 배포를 자동화할 수 있습니다. 자동화는 다음 논리를 따릅니다.

코드가 구성된 브랜치(예: dev 또는 main)로 푸시될 때 파이프라인 또는 워크플로우가 트리거됩니다.
분기 이름은 대상 환경 및 작업 영역 ID를 결정합니다.
배포 스크립트는 적절한 매개 변수를 사용하여 자동으로 실행됩니다.
PBIP 아티팩트가 해당 환경의 올바른 작업 영역에 배포됩니다.

이 섹션에서는 Azure DevOps 및 GitHub Actions에 공통적인 설정 단계와 플랫폼별 구성 지침을 설명합니다.

설정

CI/CD 플랫폼을 구성하기 전에 다음 일반적인 설정 단계를 완료합니다.

1. 서비스 주체 만들기

패브릭 작업 영역에서 기여자 또는 관리자 역할을 사용하여 Azure AD에서 서비스 주체를 만듭니다.

2. 패브릭 작업 영역에 서비스 주체 추가

패브릭 포털을 열고 각 대상 작업 영역(dev, prod)으로 이동합니다.
작업 영역 설정 > 으로 이동 액세스 관리
기여자 또는 관리자 역할을 사용하여 서비스 주체 추가

비고

패브릭 API를 사용하려면 테넌트 수준에서 서비스 주체를 사용하도록 설정해야 합니다. 자세한 내용은 서비스 주체가 Fabric 공용 API를 호출할 수 있는지를 참조하세요.

3. 리포지토리에서 분기 설정

자동화에 사용할 브랜치를 만듭니다. 이 문서의 예제는 다음과 같습니다.

dev 개발 환경 배포를 위한 분기 만들기
main 프로덕션 환경 배포를 위한 분기 만들기

YAML 파일에서 작업 영역 매핑을 수정하여 분기 이름을 사용자 지정하고 환경을 더 추가할 수 있습니다.

Azure DevOps

Azure Pipelines를 사용하여 PBIP 배포를 자동화합니다. 코드가 구성된 분기에 푸시되면 파이프라인이 해당 작업 영역에 자동으로 배포됩니다.

리포지토리 루트에서 azure-pipelines.yml을(를) 만듭니다.

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 구성

Azure DevOps 프로젝트 설정에서 Azure 서비스 연결을 만듭니다.
- 프로젝트 설정 > 서비스 연결로 이동
- 서비스 주체 자격 증명을 사용하여 새 Azure Resource Manager 서비스 연결 만들기
- 자세한 지침은 Microsoft Azure에 연결을 참조하세요.
- azureSubscription 서비스 연결 이름과 일치하도록 YAML의 값을 업데이트합니다.
YAML에서 작업 영역 ID를 업데이트합니다.
- workspace_ids azure-pipelines.yml 변수 편집
- 개발 및 prod 작업 영역 ID 설정
- 리포지토리에 변경 내용 커밋 및 푸시
파이프라인을 만듭니다.
- 파이프라인으로 이동 > 새 파이프라인
- 리포지토리를 선택하고 "기존 Azure Pipelines YAML 파일"을 선택합니다.
- azure-pipelines.yml을 선택하세요.
- 자세한 지침은 첫 번째 파이프라인 만들기를 참조하세요.
- 파이프라인을 저장하고 실행하여 PBIP를 Fabric에 배포합니다.

GitHub Actions (GitHub 액션)

GitHub Actions를 사용하여 PBIP 배포를 자동화합니다. 코드가 구성된 분기에 푸시되면 워크플로가 해당 작업 영역에 자동으로 배포됩니다.

리포지토리에서 .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 구성

Azure 자격 증명 비밀을 만듭니다.
- JSON 형식으로 서비스 주체 자격 증명을 가져옵니다.
```
{
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "subscriptionId": "<azure-subscription-id>",
  "tenantId": "<azure-tenant-id>"
}
```
- GitHub 리포지토리 설정 > 보안 및 변수 > 액션으로 이동하십시오
- JSON 위에 AZURE_CREDENTIALS를 추가하세요.
워크플로에서 작업 영역 ID를 업데이트합니다.
- 해시 테이블 workspace_ids를 다음의 "작업 영역 변수 설정" 단계에서 편집합니다. .github/workflows/deploy.yml
- 개발 및 prod 작업 영역 ID 설정
- 워크플로 YAML을 커밋하고 리포지토리에 푸시

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-23