Implementar projetos Power BI (PBIP) usando fabric-cicd

fabric-cicd é uma biblioteca Python open-source apoiada oficialmente pela Microsoft, que fornece um método code-first, permitindo aos programadores de Fabric implementar itens do Fabric desde o controlo de código-fonte para os espaços de trabalho usando o seu formato de definição de código, como modelos semânticos e relatórios usando o formato de ficheiro PBIP. A ferramenta integra-se com Fabric Git Integration, APIs Fabric REST e Fabric CLI para permitir fluxos de implementação consistentes entre espaços de trabalho.

Neste artigo, você aprenderá a:

• Implemente manualmente os ficheiros PBIP a partir da sua máquina local
• Parametrize ficheiros PBIP para configurações específicas do ambiente
• Automatizar implementações com direcionamento de espaços de trabalho baseados em ramificações usando Azure DevOps ou GitHub Actions

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

Porquê fabric-cicd para implementação de PBIP?

o fabric-cicd foi especificamente concebido para implementar artefactos Fabric controlados por fonte e oferece várias vantagens:

• Usa APIs REST nativas do Fabric - Construído sobre APIs oficiais Microsoft Fabric, garantindo compatibilidade e suporte a longo prazo
• Tratamento automatizado de dependências - Determina a ordem correta de implementação e resolve dependências entre itens (como publicar modelos semânticos antes dos relatórios), reduzindo a sequenciação manual e minimizando erros de implementação
• Python-native - Integração perfeita com fluxos de trabalho DevOps modernos baseados em Python
• Parametrização - Suporte incorporado para configurações específicas do ambiente (IDs de espaços de trabalho, fontes de dados, cadeias de ligação)
• Developer-friendly - Scripts simples de Python que podem correr localmente ou em pipelines CI/CD
• Controlo de implementação flexível - Implementar apenas tipos específicos de itens (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 órfãos - Remove automaticamente itens do workspace que já não existem no controlo de origem
• Autenticação fiável - Utiliza Azure SDK de Identidade com múltiplas opções de autenticação

Pré-requisitos

Antes de começar, certifique-se de que tem:

• Python (versões 3.9 a 3.12)
• Um projeto Power BI Desktop guardado em formato PBIP
• Acesso a um espaço de trabalho Microsoft Fabric com função de Contribuinte

Para implementações automatizadas, também precisa de:

• Um principal de serviço com pelo menos o papel de Contribuidor nos espaços de trabalho Fabric alvo
• Acesso ao Azure DevOps ou GitHub Actions
• Os seus ficheiros PBIP no sistema de controlo de versão (Git, Azure DevOps ou GitHub)

Início rápido

Este início rápido mostra-lhe como implementar um projeto PBIP da sua máquina local para um espaço de trabalho Fabric.

1. Instalar fabric-cicd

Abra o seu terminal e instale o fabric-cicd:

pip install fabric-cicd

2. Prepare o seu projeto PBIP

Assegure que o seu projeto PBIP inclui os ficheiros necessários. Uma estrutura típica de projeto PBIP:

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

Para informações detalhadas sobre ficheiros e formatos necessários, consulte Power BI Pasta de relatórios do projeto no ambiente de trabalho e Power BI Pasta do modelo semântico do projeto no ambiente de trabalho.

3. Criar script de implementação

Crie um arquivo no diretório do projeto:

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. Desdobramento

Executa o script de deployment com o nome do teu espaço de trabalho:

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

O seu navegador abre para autenticação. Após iniciar sessão, o fabric-cicd implanta os seus ficheiros PBIP no espaço de trabalho alvo. 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 implementação normalmente demora entre 20 a 30 segundos, dependendo do tamanho do seu modelo semântico.

Parametrização específica do ambiente

Uma das funcionalidades mais poderosas do fabric-cicd é a capacidade de parametrizar os seus ficheiros PBIP para diferentes ambientes. Isto é essencial quando os seus modelos semânticos referenciam recursos específicos do ambiente, como IDs de workspace, IDs de lakehouse ou cadeias de ligação.

Exemplo: Parametrizar IDs de espaços de trabalho e de casa do lago

Crie um ficheiro na raiz do seu 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 executa , fabric-cicd automaticamente:

1. Lê o ficheiro "parameter.yml"
2. Encontra todas as instâncias de nos teus ficheiros de definição PBIP
3. Substitui-os pelo correspondente específico do ambiente
4. Implementa as definições modificadas para o espaço de trabalho alvo

Automatize a implantação

Pode automatizar as implementações de PBIP para serem executadas automaticamente sempre que o código for mesclado em ramos específicos no seu repositório. A automação segue esta lógica:

1. Um pipeline ou fluxo de trabalho é ativado quando o código é enviado para um branch configurado (por exemplo, ou )
2. O nome do ramo determina o ambiente-alvo e o ID do espaço de trabalho
3. O script de implementação corre automaticamente com os parâmetros apropriados
4. Os artefactos do teu PBIP são implementados no espaço de trabalho correto para esse ambiente

Esta secção aborda os passos de configuração comuns tanto ao Azure DevOps como ao GitHub Actions, seguidos de instruções de configuração específicas para cada plataforma.

Configurar

Antes de configurar a sua plataforma CI/CD, complete estes passos comuns de configuração:

1. Criar um principal de serviço

Crie um principal de serviço no Azure AD com o papel de Contribuidor ou Administrador nos seus espaços de trabalho do Fabric.

2. Adicionar o service principal às áreas de trabalho do Fabric

1. Abre o portal do Fabric e navega até cada espaço de trabalho alvo (dev, prod)
2. Ir a Definições do Espaço de Trabalho Gerir acesso
3. Adicione o principal de serviço com o papel de Contribuinte ou Administrador

3. Configurar ramificações no seu repositório

Cria os ramos que vais usar para automação. Para os exemplos deste artigo:

1. Criar um ramo para implementações em ambientes de desenvolvimento
2. Criar um ramo para implementações em ambiente de produção

Pode personalizar os nomes das ramificações e adicionar mais ambientes modificando os mapeamentos do espaço de trabalho nos ficheiros YAML.

Azure DevOps

Automatizar implementações PBIP com Azure Pipelines. Quando o código é enviado para ramificações configuradas, o pipeline é automaticamente implementado para o espaço de trabalho correspondente.

Crie na raiz do teu repositório:

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
                }

Configure Azure DevOps

1. Criar uma ligação de serviço Azure nas definições do projeto Azure DevOps:
   • Ir para Definições do Projeto Conexões de Serviço
   • Crie uma nova ligação de serviço Azure Resource Manager usando as suas credenciais principal de serviço
   • Para instruções detalhadas, veja Conectar a Microsoft Azure
   • Atualize o valor no YAML para corresponder ao nome da sua ligação de serviço
2. Atualize os nomes dos espaços de trabalho no YAML:
   • Editar a variável em azure-pipelines.yml
   • Defina os nomes dos seus espaços de trabalho de desenvolvimento e produção
   • Faz commit e envia as alterações para o teu repositório
3. Crie o pipeline:
   • Ir a Pipelines Novo pipeline
   • Selecione o seu repositório e escolha "Existing Azure Pipelines YAML file"
   • Selecionar azure-pipelines.yml
   • Para instruções detalhadas, consulte Criar o seu primeiro pipeline
   • Guarde e execute o pipeline para implementar o seu PBIP no Fabric

GitHub Actions

Automatize implementações de PBIP com GitHub Actions. Quando o código é enviado para os ramos configurados, o fluxo de trabalho é automaticamente implementado para o espaço de trabalho correspondente.

Crie no 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_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
          }

Configurar GitHub Actions

1. Criar o segredo das credenciais Azure:

   • Obtenha as suas credenciais de principal de serviço em formato JSON:

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

   • Vá a GitHub repositório Definições > Segredos e variáveis > Ações
   • Adicione ao JSON acima

2. Atualize os nomes dos espaços de trabalho no fluxo de trabalho:

   • Editar a tabela de hash na etapa "Definir variáveis do espaço de trabalho" em
   • Defina os nomes dos seus espaços de trabalho de desenvolvimento e produção
   • Faça commit e envie o YAML do workflow para o seu repositório

Conteúdo relacionado

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