Implantar projetos de Power BI (PBIP) usando fabric-cicd

fabric-cicd é uma biblioteca Python de código aberto com suporte oficial da Microsoft, que oferece uma abordagem de código como primeira opção para desenvolvedores do Fabric implantarem itens do Fabric a partir do controle de código-fonte para espaços de trabalho, utilizando seu formato de definição de código, como modelos semânticos e relatórios no formato de arquivo PBIP. A ferramenta se integra ao Fabric Git Integration, às APIs REST do Fabric e à CLI do Fabric para habilitar fluxos de implantação consistentes entre workspaces.

Neste artigo, você aprenderá a:

• Implantar arquivos PBIP manualmente do computador local
• Parametrizar arquivos PBIP para configurações específicas do ambiente
• Automatize implantações direcionando espaço de trabalho baseado em branch usando Azure DevOps ou ações do GitHub Actions

Saiba mais sobre o formato PBIP em Power BI Desktop Projects (PBIP) e visão geral da integração do Git do Fabric.

Por que fabric-cicd para implantação PBIP?

Fabric-cicd foi projetado especificamente para implantar artefatos do Fabric controlados pela origem e oferece várias vantagens:

• APIs REST nativas do Uses Fabric - Baseadas em APIs oficiais de Microsoft Fabric, garantindo compatibilidade e suporte a longo prazo
• Tratamento automatizado de dependência – Determina a ordem de implantação correta e resolve as dependências entre itens (como publicar modelos semânticos antes dos relatórios), reduzindo o sequenciamento manual e minimizando erros de implantação
• Python-native – integração perfeita com fluxos de trabalho de DevOps modernos baseados em Python
• Parametrização: suporte interno para configurações específicas do ambiente (IDs de workspace, fontes de dados, cadeias de conexão)
• Developer-friendly: scripts Python simples que podem ser executados localmente ou em pipelines de CI/CD
• Controle de implantação flexível: implantar apenas tipos de item específicos (por exemplo, modelos semânticos sem relatórios ou modelos semânticos com ou sem cache de dados) e garantir configurações consistentes como páginas ou parâmetros padrão sem intervenção manual
• Limpeza de itens órfãos: remove automaticamente itens do workspace que não existem mais no controle de versão
• Autenticação confiável: usa Azure SDK de Identidade com várias opções de autenticação

Pré-requisitos

Antes de começar, verifique se você tem:

• Python (versão 3.9 a 3.12)
• Um projeto do Power BI Desktop salvo no formato PBIP
• Acesso a um espaço de trabalho do Microsoft Fabric com a função Colaborador

Para implantações automatizadas, você também precisa:

• Uma entidade de serviço com pelo menos o papel de Colaborador em workspaces alvo do Fabric
• Acesso a Azure DevOps ou GitHub Actions
• Seus arquivos PBIP no controle do código-fonte (Git, Azure DevOps ou GitHub)

Início rápido

Este início rápido mostra como implantar um projeto PBIP do computador local em um workspace do Fabric.

1. Instalar fabric-cicd

Abra o terminal e instale o fabric-cicd:

pip install fabric-cicd

2. Preparar seu projeto PBIP

Verifique se o projeto PBIP inclui os arquivos necessários. Uma estrutura de projeto PBIP típica:

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

Para obter informações detalhadas sobre arquivos e formatos necessários, consulte a pasta de relatórios do projeto no Power BI Desktop e a pasta de modelo semântico do projeto no Power BI Desktop.

3. Criar script de implantação

Crie um arquivo no diretório do projeto:

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. Implantação

Execute o script de implantação com a ID da área de trabalho:

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

Seu navegador é aberto para autenticação. Depois de entrar, o fabric-cicd implanta seus arquivos PBIP no workspace de destino. Você vê mensagens de progresso como:

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

[info] Publishing Report 'SalesAnalytics'
       Published

A implantação normalmente leva de 20 a 30 segundos, dependendo do tamanho do modelo semântico.

Parametrização específica do ambiente

Um dos recursos mais poderosos do fabric-cicd é a capacidade de parametrizar seus arquivos PBIP para ambientes diferentes. Isso é essencial quando seus modelos semânticos fazem referência a recursos específicos do ambiente, como IDs de workspace, IDs do lakehouse ou cadeias de conexão.

Exemplo: Parametrizar IDs de workspace e lakehouse

Crie um arquivo na raiz do projeto para definir valores específicos do ambiente:

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

Quando você executa , o fabric-cicd executa automaticamente:

1. Lê o arquivo parameter.yml
2. Localiza todas as instâncias de nos seus arquivos de definição PBIP
3. Substitui-os pelo específico do ambiente
4. Implanta as definições modificadas no workspace de destino

Automatizar a implantação

Você pode automatizar as implantações PBIP para serem executadas sempre que o código for mesclado em branches específicas do seu repositório. A automação segue essa lógica:

1. Um pipeline ou fluxo de trabalho é acionado quando o código é feito push para um branch configurado (por exemplo, ou )
2. O nome do branch determina o ambiente de destino e o ID do espaço de trabalho
3. O script de implantação é executado automaticamente com os parâmetros apropriados
4. Seus artefatos PBIP são implantados no workspace correto para esse ambiente

Esta seção aborda as etapas de instalação comuns a Azure DevOps e GitHub Actions, seguidas por instruções de configuração específicas da plataforma.

Configuração

Antes de configurar sua plataforma de CI/CD, conclua estas etapas comuns de instalação:

1. Criar um principal de serviço

Crie um principal de serviço no Azure AD com a função de Colaborador ou Administrador em seus workspaces do Fabric.

2. Adicionar entidade de serviço aos workspaces do Fabric

1. Abra o portal do Fabric e navegue até cada espaço de trabalho de destino (desenvolvimento, produção)
2. Ir para Configurações do Workspace Gerenciar acesso
3. Adicionar a entidade de serviço com a função Colaborador ou Administrador

3. Configurar branches em seu repositório

Crie as ramificações que você usará para automação. Para os exemplos deste artigo:

1. Criar uma ramificação para implantações de ambiente de desenvolvimento
2. Criar uma ramificação para implantações de ambiente de produção

Você pode personalizar nomes de ramificação e adicionar mais ambientes modificando os mapeamentos do workspace nos arquivos YAML.

Azure DevOps

Automatize implantações PBIP com Azure Pipelines. Quando o código é enviado por push para branches configurados, o pipeline é implantado automaticamente no workspace correspondente.

Crie na raiz do repositório:

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
                }

Configurar Azure DevOps

1. Crie uma conexão de serviço Azure nas configurações do projeto Azure DevOps:
   • Ir para Configurações do Projeto conexões de serviço
   • Criar uma nova conexão de serviço do Azure Resource Manager usando suas credenciais de entidade de serviço
   • Para obter instruções detalhadas, consulte Conectar para Microsoft Azure
   • Atualize o valor no YAML para corresponder ao nome da conexão do serviço
2. Atualize os IDs do workspace no YAML:
   • Editar a variável no azure-pipelines.yml
   • Defina suas IDs de workspace de desenvolvimento e produção
   • Confirmar e enviar por push as alterações para o repositório
3. Crie o pipeline:
   • Ir para Pipelines Novo pipeline
   • Selecione seu repositório e escolha "Arquivo YAML existente do Azure Pipelines"
   • Selecione azure-pipelines.yml
   • Para obter instruções detalhadas, consulte Criar seu primeiro pipeline
   • Salve e execute o pipeline para implantar o PBIP no Fabric

GitHub Actions

Automatize implantações PBIP com GitHub Actions. Quando o código é enviado por push para branches configurados, o fluxo de trabalho é implantado automaticamente no workspace correspondente.

Crie em seu repositório:

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
          }

Configurar GitHub Actions

1. Crie o segredo das credenciais Azure:

   • Obtenha as credenciais de sua entidade de serviço no formato JSON:

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

   • Vá para as configurações do repositório no GitHub > Segredos e variáveis > Actions
   • Adicionar com o JSON acima

2. Atualize os IDs do espaço de trabalho no workflow:

   • Editar o hashtable na etapa "Definir variáveis da área de trabalho" em
   • Defina suas IDs de workspace de desenvolvimento e produção
   • Confirmar e enviar por push o YAML do fluxo de trabalho para o repositório

Conteúdo relacionado

• Documentação fabric-cicd
• repositório do GitHub fabric-cicd
• Visão geral da integração do Git do Fabric
• Power BI planejamento de implementação: gerenciamento do ciclo de vida do conteúdo