Развертывание проектов Power BI (PBIP) с помощью fabric-cicd

Это важно

Проекты Power BI Desktop в настоящее время находятся в предварительной версии.

fabric-cicd — это библиотека Python, разработанная компанией Microsoft, которая предоставляет разработчикам Fabric метод для развертывания элементов Fabric из системы контроля версий в рабочие пространства, используя их формат определения кода, такой как семантические модели и отчеты с форматом файла PBIP.

В этой статье вы узнаете, как:

Развертывание PBIP-файлов вручную с локального компьютера
Параметризация PBIP-файлов для конфигураций, относящихся к среде
Автоматизируйте развертывания с нацеливанием на рабочую область на основе ветки, используя Azure DevOps или GitHub Actions.

Дополнительные сведения о формате PBIP в проектах Power BI Desktop (PBIP) и обзоре интеграции Fabric Git.

Почему именно fabric-cicd для развертывания PBIP?

Fabric-cicd специально предназначен для развертывания артефактов Fabric, управляемых источником, и предлагает несколько преимуществ:

Использует собственные REST API Fabric — построенные на официальных API Microsoft Fabric, обеспечивая совместимость и долгосрочную поддержку
Python native — простая интеграция с современными рабочими процессами DevOps на основе Python
Параметризация: встроенная поддержка конфигураций для конкретной среды (идентификаторы рабочих областей, источники данных, строки подключения)
Понятно для разработчиков: простые скрипты Python, которые могут выполняться локально или в конвейерах CI/CD
Гибкий элемент управления развертыванием: развертывание только определенных типов элементов (например, семантических моделей без отчетов или семантических моделей с кэшем данных) и обеспечение согласованных конфигураций, таких как страницы по умолчанию или параметры без ручного вмешательства.
Удаление осиротевших элементов: автоматически удаляет элементы из рабочей области, которые больше не существуют в системе управления исходными текстами
Надежная проверка подлинности. Использование пакета SDK удостоверений Azure с несколькими параметрами проверки подлинности

Замечание

Полные сведения см. в документации по fabric-cicd.

Предпосылки

Прежде чем начать, убедитесь, что у вас есть следующее:

Python (версия 3.9 до 3.12)
Проект Power BI Desktop, сохраненный в формате PBIP
Доступ к рабочей области Microsoft Fabric с ролью участника

Для автоматизированных развертываний также требуется:

Субъект-служба с по крайней мере ролью участника в целевых рабочих областях Fabric
Доступ к Azure DevOps или GitHub Actions
Файлы PBIP в системе контроля версий (Git, Azure DevOps или GitHub)

Быстрый старт

В этом кратком руководстве показано, как развернуть проект PBIP с локального компьютера в рабочей области Fabric.

Установите fabric-cicd

Откройте терминал и установите fabric-cicd:

pip install fabric-cicd

Подготовьте проект 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, откройте файл PBIX в Power BI Desktop и сохраните его, используя Файл > Сохранить как > Проект 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. Развертывание

Запустите скрипт развертывания с идентификатором рабочей области:

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 секунд в зависимости от размера семантической модели.

Замечание

При первом развертывании семантической модели с источниками данных необходимо вручную настроить учетные данные источника данных на портале Fabric. Перейдите к рабочей области > настройки семантической модели > учетные данные источника данных >. Последующие развертывания повторно используют сохраненные учетные данные.

Параметризация для конкретной среды

Одна из самых мощных функций fabric-cicd — это возможность параметризации PBIP-файлов для разных сред. Это важно, когда семантические модели ссылаются на ресурсы, зависящие от среды, такие как идентификаторы рабочих пространств, идентификаторы lakehouse или строки подключения.

Пример. Параметризация рабочих областей и идентификаторов lakehouse

Создайте файл в корневом каталоге 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
Находит все вхождения find_value в ваших файлах определения PBIP
Заменяет их соответствующими средами для конкретной среды replace_value
Развертывает измененные определения в целевой рабочей области

Автоматизация развертывания

Развертывания PBIP можно автоматизировать, чтобы они запускались всякий раз, когда код сливается в определённые ветки вашего репозитория. Автоматизация следует этой логике:

Конвейер или рабочий процесс активируется при отправке кода в настроенную ветвь (например, dev или main)
Имя ветви определяет целевую среду и идентификатор рабочей области
Скрипт развертывания выполняется автоматически с соответствующими параметрами
Артефакты PBIP развертываются в правильной рабочей области для этой среды.

В этом разделе рассматриваются действия по настройке, общие для Azure DevOps и GitHub Actions, а также инструкции по настройке для конкретной платформы.

Настройка

Перед настройкой платформы CI/CD выполните следующие распространенные действия по настройке:

1. Создание субъекта-службы

Создайте учетную запись службы в Azure AD с ролями "Участник" или "Администратор" в рабочих областях Fabric.

2. Добавить учетную запись службы в рабочие пространства Fabric

Откройте портал Fabric и перейдите к каждой целевой рабочей области (dev, prod)
Перейти к параметрам > рабочей области Управление доступом
Добавление субъекта-службы с ролью участника или администратора

Замечание

Субъекты-службы должны быть включены на уровне клиента для использования API Fabric. Дополнительные сведения см. в разделе Учетные записи службы могут вызывать общедоступные API Fabric.

3. Настройка ветвей в репозитории

Создайте ветви, которые будут использоваться для автоматизации. Примеры, приведенные в этой статье:

Создайте ветку для развертываний в среде разработки
Создайте ветвь для развертываний в продуктивной среде

Вы можете настроить имена ветвей и добавить дополнительные среды, изменив сопоставления рабочих областей в файлах YAML.

Azure DevOps

Автоматизация развертываний PBIP с помощью Azure Pipelines. При отправке кода в настроенные ветви конвейер автоматически развертывается в соответствующей рабочей области.

Создайте 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 в параметрах проекта Azure DevOps:
- Перейдите в "Параметры проекта" > Подключения службы.
- Создание подключения к службе Azure Resource Manager с помощью учетных данных субъекта-службы
- Подробные инструкции см. в статье "Подключение к Microsoft Azure"
- azureSubscription Обновите значение в YAML, чтобы оно соответствовало имени подключения службы.
Обновите идентификаторы рабочих областей в YAML:
- Изменение переменной workspace_ids в azure-pipelines.yml
- Укажите идентификаторы рабочих областей разработки и продакшена
- Фиксация и отправка изменений в репозиторий
Создайте конвейер:
- Перейти к разделу "Конвейеры" > Новый конвейер
- Выберите репозиторий и выберите "Существующий файл YAML Azure Pipelines"
- Выберите azure-pipelines.yml
- Подробные инструкции см. в статье "Создание первого конвейера"
- Сохранение и запуск конвейера для развертывания PBIP в Fabric

Действия GitHub

Автоматизация развертываний PBIP с помощью GitHub Actions. При отправке кода в настроенные ветви рабочий процесс автоматически развертывается в соответствующей рабочей области.

Создайте .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

Создайте секрет учетных данных Azure:
- Получите учетные данные принципала службы в формате JSON:
```
{
  "clientId": "<service-principal-client-id>",
  "clientSecret": "<service-principal-secret>",
  "subscriptionId": "<azure-subscription-id>",
  "tenantId": "<azure-tenant-id>"
}
```
- Перейдите в репозиторий GitHub Настройки > Секреты и переменные > Действия
- Добавление AZURE_CREDENTIALS с помощью приведенного выше JSON
Обновите идентификаторы рабочей области в рабочем процессе:
- workspace_ids Изменение хэш-таблицы на шаге "Задание переменных рабочей области".github/workflows/deploy.yml
- Укажите идентификаторы рабочих областей разработки и продакшена
- Фиксация и отправка YAML рабочего процесса в репозиторий

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-23

Поделиться через

Развертывание проектов Power BI (PBIP) с помощью fabric-cicd

Почему именно fabric-cicd для развертывания PBIP?

Предпосылки

Быстрый старт

Установите fabric-cicd

Подготовьте проект PBIP

3. Создание скрипта развертывания

4. Развертывание

Параметризация для конкретной среды

Пример. Параметризация рабочих областей и идентификаторов lakehouse

Автоматизация развертывания

Настройка

1. Создание субъекта-службы

2. Добавить учетную запись службы в рабочие пространства Fabric

3. Настройка ветвей в репозитории

Azure DevOps

Настройка Azure DevOps

Действия GitHub

Настройка действий GitHub

Связанный контент

Обратная связь

Дополнительные ресурсы