fabric-cicd を使用して Power BI プロジェクト (PBIP) をデプロイする

Important

Power BI デスクトッププロジェクトは現在、previewにあります。

fabric-cicd は、公式にサポートされている Microsoft がサポートするオープンソース Python ライブラリです。このライブラリは、PBIP ファイル形式を使用したセマンティックモデルやレポートなど、コード定義形式を使用して Fabric アイテムをソース管理からワークスペースにデプロイするためのコードファーストの方法を提供します。このツールは、Fabric Git Integration、Fabric REST API、および Fabric CLI と統合され、ワークスペース間で一貫したデプロイフローが可能になります。

この記事では、次の方法について説明します。

ローカルコンピューターから PBIP ファイルを手動でデプロイする
環境固有の構成用に PBIP ファイルをパラメーター化する
Azure DevOpsまたはGitHub Actionsを使用して、ブランチベースのワークスペースターゲットを使用してデプロイを自動化する

PBIP 形式の詳細については、Power BI デスクトッププロジェクト (PBIP) および Fabric Git 統合の概要で説明します。

PBIP のデプロイに fabric-cicd を使用する理由は何ですか?

fabric-cicd は、ソース管理された Fabric 成果物をデプロイするために特別に設計されており、いくつかの利点があります。

Fabric ネイティブ REST API の使用 - 公式のMicrosoft Fabric API を基に構築され、互換性と長期的なサポートを確保します
依存関係の自動処理 - 正しい配置順序を決定し、項目間の依存関係 (レポート前のセマンティックモデルの発行など) を解決し、手動のシーケンス処理を減らし、配置エラーを最小限に抑えます
Python ネイティブ - 最新のPythonベースの DevOps ワークフローとのシームレスな統合
パラメーター化 - 環境固有の構成 (ワークスペース ID、データソース、接続文字列) の組み込みサポート
Developer 対応 - ローカルまたは CI/CD パイプラインで実行できる単純なPython スクリプト
柔軟な展開制御 - 特定の項目の種類 (レポートのないセマンティックモデル、データキャッシュの有無に関係なくセマンティックモデルなど) のみをデプロイし、手動操作なしで既定のページやパラメーターなどの一貫性のある構成を確保します
孤児オブジェクトのクリーンアップ - ソース管理から消えたオブジェクトをワークスペースから自動的に削除する
実行可能な認証 - 複数の認証オプションを持つ Azure Identity SDK を使用します

注

完全なドキュメントについては、 fabric-cicd のドキュメントを参照してください。

[前提条件]

開始する前に、次のことを確認します。

Python (バージョン 3.9 から 3.12)
PBIP 形式で保存されたPower BI デスクトッププロジェクト
共同作成者ロールを持つMicrosoft Fabric ワークスペースへのアクセス

自動デプロイの場合は、次が必要です。

ターゲット Fabric ワークスペースにおいて少なくとも寄稿者ロールを持つサービスプリンシパル
Azure DevOpsまたはGitHub Actionsへのアクセス
ソース管理の PBIP ファイル (Git、Azure DevOps、またはGitHub)

簡単スタート

このクイックスタートでは、ローカルコンピューターから Fabric ワークスペースに 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 デスクトッププロジェクトレポートフォルダーおよび Power BI デスクトッププロジェクトセマンティックモデルフォルダーを参照してください。

ヒント

PBIP プロジェクトを作成するには、Power BI Desktop で PBIX ファイルを開き、File > Save As > Power BI Project (.pbip) を使用して保存します。詳細については、「Power BI デスクトッププロジェクト」を参照してください。

3. デプロイスクリプトを作成する

プロジェクトディレクトリにファイルを作成します。

import argparse
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_name", type=str, required=False, help="Target workspace name", default="PBIP Fabric CICD Dev")
parser.add_argument("--environment", type=str, default="dev", help="Environment name")
parser.add_argument("--spn-auth", action="store_true", help="Use SPN authentication via Azure CLI")
args = parser.parse_args()

# Use InteractiveBrowserCredential for local development, AzureCliCredential for CI/CD pipelines
if not args.spn_auth:
    credential = InteractiveBrowserCredential()
else:
    credential = AzureCliCredential()

workspace_params = {
    "workspace_name": args.workspace_name,
    "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. 展開

ワークスペース名を使用してデプロイスクリプトを実行します。

python deploy.py --workspace_name "PBIP Fabric CICD Dev"

注

スクリプトのディクショナリとコマンドライン引数の両方で、をに置き換えることで、ワークスペース ID (GUID) を使用することもできます。

認証用にブラウザーが開きます。サインイン後、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 秒かかります。

注

データソースを使用してセマンティックモデルを初めてデプロイするときは、Fabric ポータルでデータソースの資格情報を手動で構成する必要があります。ワークスペースセマンティックモデル設定データソース資格情報に移動します。後続のデプロイでは、保存された資格情報が再利用されます。

環境固有のパラメーター化

fabric-cicd の最も強力な機能の 1 つは、さまざまな環境で PBIP ファイルをパラメーター化する機能です。これは、セマンティックモデルがワークスペース ID、lakehouse ID、接続文字列などの環境固有のリソースを参照する場合に不可欠です。

例: ワークスペース ID と lakehouse ID をパラメーター化する

プロジェクトルートにファイルを作成して、環境固有の値を定義します。

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

を実行すると、fabric-cicd が自動的に次のようになります。

parameter.yml ファイルを読み取ります
PBIP 定義ファイル内ののすべてのインスタンスを検索します
それらを対応する環境固有に置き換えます
変更された定義をターゲットワークスペースにデプロイします

デプロイの自動化

PBIP デプロイを自動化して、コードがリポジトリ内の特定のブランチにマージされるたびに実行できます。自動化は、次のロジックに従います。

パイプラインまたはワークフローは、コードが構成されたブランチ ( やなど) にプッシュされたときにトリガーされます。
ブランチ名によって、ターゲット環境とワークスペース ID が決まります
デプロイスクリプトは、適切なパラメーターを使用して自動的に実行されます
PBIP アーティファクトは、その環境の適切なワークスペースにデプロイされます

このセクションでは、Azure DevOpsとGitHub Actionsの両方に共通するセットアップ手順と、プラットフォーム固有の構成手順について説明します。

セットアップ

CI/CD プラットフォームを構成する前に、次の一般的なセットアップ手順を完了してください。

1. サービスプリンシパルを作成する

Fabric ワークスペースの共同作成者または管理者ロールを使用して、Azure AD にサービスプリンシパルを作成します。

2. Fabric ワークスペースにサービスプリンシパルを追加する

Fabric ポータルを開き、各ターゲットワークスペース (dev、prod) に移動します
[ワークスペースの設定] [アクセスの管理] に移動する
共同作成者ロールまたは管理者ロールを持つサービスプリンシパルを追加する

注

Fabric API を使用するには、テナントレベルでサービスプリンシパルを有効にする必要があります。詳細については、「サービスプリンシパルが Fabric パブリック API を呼び出すことができる」を参照してください。

3. リポジトリ内のブランチを構成する

自動化に使用するブランチを作成します。この記事の例を次に示します。

開発環境のデプロイ用のブランチを作成する
運用環境のデプロイ用のブランチを作成する

YAML ファイル内のワークスペースマッピングを変更することで、ブランチ名をカスタマイズしたり、環境を追加したりできます。

Azure DevOps

Azure Pipelinesを使用して PBIP デプロイを自動化します。構成されたブランチにコードがプッシュされると、パイプラインは対応するワークスペースに自動的にデプロイされます。

リポジトリルートにを作成します。

trigger:
  branches:
    include:
      - dev
      - main

variables:
  - name: workspace_names
    value: |
      {
        "dev": "PBIP Fabric CICD Dev",
        "main": "PBIP Fabric CICD Prod"
      }
  - 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_names = '$(workspace_names)' | ConvertFrom-Json
                $environments = '$(environments)' | ConvertFrom-Json
                
                $workspace_name = $workspace_names.$branch_name
                $environment = $environments.$branch_name
                
                python -u deploy.py --spn-auth --workspace_name "$workspace_name" --environment "$environment"
                
                if ($LASTEXITCODE -ne 0) {
                    Write-Error "Deployment failed with exit code: $LASTEXITCODE"
                    exit $LASTEXITCODE
                }

Azure DevOpsの構成

Azure DevOpsのプロジェクト設定でAzureサービス接続を作成します。
- [プロジェクトの設定] サービス接続に移動する
- サービスプリンシパルの資格情報を使用して新しいAzure Resource Manager サービス接続を作成する
- 詳細な手順については、「Connect to Microsoft Azure
- サービス接続名と一致するように YAML の値を更新します
YAML 内のワークスペース名を更新します。
- azure-pipelines.ymlで変数を編集する
- 開発ワークスペースと prod ワークスペースの名前を設定する
- 変更をコミットしてリポジトリにプッシュする
パイプラインを作成します。
- [パイプライン] [新しいパイプライン] に移動する
- リポジトリを選択し、[既存のAzure Pipelines YAML ファイル] を選択します
- azure-pipelines.ymlを選択する
- 詳細な手順については、最初のパイプラインの作成に関するページを参照してください。
- パイプラインを保存して実行して PBIP を Fabric にデプロイする

GitHub Actions

GitHub Actionsを使用して PBIP デプロイを自動化します。構成されたブランチにコードがプッシュされると、ワークフローは対応するワークスペースに自動的にデプロイされます。

リポジトリにを作成します。

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_names = @{
            "dev" = "PBIP Fabric CICD Dev"
            "main" = "PBIP Fabric CICD Prod"
          }
          
          $environments = @{
            "dev" = "dev"
            "main" = "prod"
          }
          
          $workspace_name = $workspace_names[$branch_name]
          $environment = $environments[$branch_name]
          
          echo "workspace_name=$workspace_name" >> $env:GITHUB_OUTPUT
          echo "environment=$environment" >> $env:GITHUB_OUTPUT
      
      - name: Azure Login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
          allow-no-subscriptions: true
      
      - name: Deploy PBIP to Fabric
        shell: pwsh
        run: |
          pip install fabric-cicd
          
          python -u deploy.py --spn-auth --workspace_name "${{ steps.workspace.outputs.workspace_name }}" --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>",
  "tenantId": "<azure-tenant-id>"
}
```
- GitHub リポジトリの [設定] > シークレットと変数 > Actions に移動します
- 上記の JSON でを追加する
ワークフロー内のワークスペース名を更新します。
- の [ワークスペース変数の設定] ステップで、ハッシュテーブルを編集します
- 開発ワークスペースと prod ワークスペースの名前を設定する
- ワークフロー YAML をコミットしてリポジトリにプッシュする

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-06