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

Importante

Os projetos do Power BI Desktop estão atualmente em versão prévia.

Fabric-cicd é uma biblioteca python desenvolvida pela Microsoft que fornece um método de primeiro código para os desenvolvedores do Fabric implantarem itens do Fabric do controle do código-fonte em workspaces usando seu formato de definição de código, como modelos semânticos e relatórios usando o formato de arquivo PBIP.

Neste artigo, você aprenderá a:

• Implantar arquivos PBIP manualmente do computador local
• Parametrizar arquivos PBIP para configurações específicas do ambiente
• Automatizar implantações com o direcionamento de workspace baseado em branch usando o Azure DevOps ou o GitHub Actions

Saiba mais sobre o formato PBIP em projetos do Power BI Desktop (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:

• Usa APIs REST nativas do Fabric – Criadas em APIs oficiais do Microsoft Fabric, garantindo compatibilidade e suporte a longo prazo
• Python-native – Integração perfeita com fluxos de trabalho modernos do DevOps baseados em Python
• Parametrização: suporte interno para configurações específicas do ambiente (IDs de workspace, fontes de dados, cadeias de conexão)
• Amigável para o desenvolvedor: 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 o SDK de Identidade do Azure com várias opções de autenticação

Observação

Para obter a documentação completa, consulte a documentação do fabric-cicd.

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 workspace do Microsoft Fabric com função de 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 ao 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ório do projeto do Power BI Desktop e a pasta de modelo semântico do projeto do Power BI Desktop.

Dica

Para criar um projeto PBIP, abra o arquivo PBIX no Power BI Desktop e salve-o usando Arquivo > Salvar Como > Projeto do Power BI (.pbip). Consulte projetos do Power BI Desktop para obter mais detalhes.

3. Criar script de implantação

Crie um deploy.py 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.

Observação

Na primeira vez que implantar um modelo semântico com fontes de dados, você precisará configurar manualmente as credenciais da fonte de dados no portal do Fabric. Acesse Configurações > do modelo semântico > do workspace > credenciais de fonte de dados. As implantações subsequentes reutilizam as credenciais salvas.

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 parameter.yml 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 python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev, o fabric-cicd executa automaticamente:

1. Lê o arquivo parameter.yml
2. Localiza todas as instâncias de find_value nos seus arquivos de definição PBIP
3. Substitui-os pelo específico do ambiente replace_value
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, dev ou main)
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 configuração comuns ao Azure DevOps e ao 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

Observação

Os principais de serviço devem estar habilitados no nível do locatário para usar APIs do Fabric. Para obter mais informações, consulte As entidades de serviço podem chamar APIs públicas do Fabric.

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 dev ramificação para implantações de ambiente de desenvolvimento
2. Criar uma ramificação main 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 o Azure Pipelines. Quando o código é enviado por push para branches configurados, o pipeline é implantado automaticamente no workspace correspondente.

Crie azure-pipelines.yml 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. Criar uma conexão de serviço do Azure nas configurações de projeto do Azure DevOps:
   • Ir para Configurações do Projeto > conexões de serviço
   • Criar uma nova conexão de serviço de gerenciamento de recursos do Azure usando suas credenciais da entidade de serviço
   • Para obter instruções detalhadas, consulte Conectar-se ao Microsoft Azure
   • Atualize o valor azureSubscription no YAML para corresponder ao nome da conexão do serviço
2. Atualize os IDs do workspace no YAML:
   • Editar a workspace_ids 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 do Azure Pipelines existente"
   • 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 o GitHub Actions. Quando o código é enviado por push para branches configurados, o fluxo de trabalho é implantado automaticamente no workspace correspondente.

Crie .github/workflows/deploy.yml 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
          }

Configurando GitHub Actions

1. Crie o segredo das credenciais do 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>"
     }
     

   • Ir para o repositório GitHub Configurações > Segredos e variáveis > Ações
   • Adicionar AZURE_CREDENTIALS com o JSON acima

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

   • Editar o workspace_ids hashtable na etapa "Definir variáveis da área de trabalho" em .github/workflows/deploy.yml
   • 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 GitHub fabric-cicd
• Visão geral da integração do Git do Fabric
• Planejamento de implementação do Power BI: gerenciamento do ciclo de vida do conteúdo