Implementación de proyectos de Power BI (PBIP) mediante fabric-cicd

fabric-cicd es una biblioteca Python de código abierto respaldada oficialmente por Microsoft que proporciona un método de código primero para que los desarrolladores de Fabric implementen elementos de Fabric desde el control de código fuente en áreas de trabajo mediante su formato de definición de código, como modelos semánticos e informes mediante el formato de archivo PBIP. La herramienta se integra con Fabric Git Integration, las API REST de Fabric y la CLI de Fabric para permitir flujos de implementación coherentes entre áreas de trabajo.

En este artículo aprenderá a:

• Implementación manual de archivos PBIP desde la máquina local
• Parametrizar archivos PBIP para configuraciones específicas del entorno
• Automatiza las implementaciones utilizando direccionamiento de espacio de trabajo basadas en ramas con Azure DevOps o Acciones de GitHub

Obtenga más información sobre el formato PBIP en Power BI Desktop projects (PBIP) and Fabric Git integration overview.

¿Por qué fabric-cicd para la implementación de PBIP?

fabric-cicd está diseñado específicamente para implementar artefactos de Fabric controlados por código fuente y ofrece varias ventajas:

• APIs REST nativas de Fabric: se basa en las API oficiales de Microsoft Fabric, lo que garantiza la compatibilidad y el soporte a largo plazo
• Control automatizado de dependencias : determina el orden de implementación correcto y resuelve las dependencias entre elementos (como publicar modelos semánticos antes de informes), lo que reduce la secuenciación manual y minimiza los errores de implementación.
• Python nativo: integración sin problemas con flujos de trabajo modernos de DevOps basados en Python
• Parametrización: compatibilidad integrada con configuraciones específicas del entorno (identificadores de área de trabajo, orígenes de datos, cadenas de conexión)
• Fácil de desarrollar: scripts de Python simples que se pueden ejecutar localmente o en canalizaciones de CI/CD
• Control de implementación flexible: implemente solo tipos de elementos específicos (por ejemplo, modelos semánticos sin informes o modelos semánticos con o sin caché de datos) y garantice configuraciones coherentes como páginas predeterminadas o parámetros sin intervención manual.
• Eliminación de elementos huérfanos: Elimina automáticamente los elementos del entorno de trabajo que ya no existen en el control de código fuente.
• Autenticación confiable: usa Azure Identity SDK con varias opciones de autenticación

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

• Python (versión 3.9 a 3.12)
• Un proyecto de Power BI Desktop guardado en formato PBIP
• Acceso a un espacio de trabajo de Microsoft Fabric con el rol de Colaborador

Para las implementaciones automatizadas, también necesita lo siguiente:

• Un principal de servicio con al menos el rol de Colaborador en los espacios de trabajo de Fabric de destino
• Acceso a Azure DevOps o Acciones de GitHub
• Los archivos PBIP en el control de código fuente (Git, Azure DevOps o GitHub)

Inicio rápido

En este inicio rápido se muestra cómo implementar un proyecto PBIP desde la máquina local en un área de trabajo de Fabric.

1. Instalación de fabric-cicd

Abra el terminal e instale fabric-cicd:

pip install fabric-cicd

2. Preparar el proyecto PBIP

Asegúrese de que el proyecto PBIP incluye los archivos necesarios. Estructura típica del proyecto PBIP:

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

Para obtener información detallada sobre los formatos y archivos necesarios, vea Power BI Carpeta de informes del proyecto de escritorio y Power BI carpeta del modelo semántico del proyecto de escritorio.

3. Crear script de implementación

Cree un archivo en el directorio del proyecto:

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

Ejecute el script de implementación con el identificador del área de trabajo:

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

El explorador se abre para la autenticación. Después de iniciar sesión, fabric-cicd implementa los archivos PBIP en el área de trabajo de destino. Verá mensajes de progreso como:

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

[info] Publishing Report 'SalesAnalytics'
       Published

La implementación suele tardar entre 20 y 30 segundos en función del tamaño del modelo semántico.

Parametrización específica del entorno

Una de las características más eficaces de fabric-cicd es la capacidad de parametrizar los archivos PBIP para diferentes entornos. Esto es esencial cuando los modelos semánticos hacen referencia a recursos específicos del entorno, como identificadores de área de trabajo, identificadores de lakehouse o cadenas de conexión.

Ejemplo: Parametrizar identificadores de área de trabajo y lakehouse

Cree un archivo en la raíz del proyecto para definir valores específicos del entorno:

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

Al ejecutar , fabric-cicd realiza automáticamente las siguientes acciones:

1. Lee el archivo "parameter.yml"
2. Busca todas las instancias de en los archivos de definición de PBIP.
3. Los reemplaza con el específico del entorno correspondiente.
4. Implementa las definiciones modificadas en el área de trabajo de destino.

Automatizar la implementación

Puede automatizar las implementaciones de PBIP para que se ejecuten siempre que el código se combine en ramas específicas del repositorio. La automatización sigue esta lógica:

1. Una canalización o un flujo de trabajo se desencadena cuando el código se inserta en una rama configurada (por ejemplo, o )
2. El nombre de la rama determina el entorno de destino y el identificador del área de trabajo.
3. El script de implementación se ejecuta automáticamente con los parámetros adecuados.
4. Los artefactos de PBIP se implementan en el área de trabajo correcta para ese entorno.

En esta sección se describen los pasos de configuración comunes a Azure DevOps y Acciones de GitHub, seguidos de instrucciones de configuración específicas de la plataforma.

Configuración

Antes de configurar la plataforma de CI/CD, complete estos pasos comunes de configuración:

1. Crear un principal de servicio

Crea una entidad de servicio en Azure AD con un rol de Colaborador o Administrador en los espacios de trabajo de Fabric.

2. Agregar entidad de servicio a áreas de trabajo de Fabric

1. Abra el portal de Fabric y vaya a cada área de trabajo de destino (desarrollo, prod)
2. Vaya a Configuración del espacio de trabajo Administrar acceso.
3. Agrega la entidad de servicio con el rol de Colaborador o Administrador

3. Configurar ramas en el repositorio

Cree las ramas que usará para la automatización. Para ver los ejemplos de este artículo:

1. Creación de una rama para implementaciones de entornos de desarrollo
2. Creación de una rama para implementaciones de entornos de producción

Puede personalizar los nombres de rama y agregar más entornos modificando las asignaciones del área de trabajo en los archivos YAML.

Azure DevOps

Automatice las implementaciones de PBIP con Azure Pipelines. Cuando se inserta código en las ramas configuradas, el pipeline se implementa automáticamente en el área de trabajo correspondiente.

Cree en la raíz del repositorio:

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
                }

Configuración de Azure DevOps

1. Crear una conexión de servicio de Azure en la configuración del proyecto de Azure DevOps:
   • Vaya a Configuración del proyecto Conexiones del servicio.
   • Crea una nueva conexión de servicio de Azure Resource Manager utilizando las credenciales de tu entidad de servicio.
   • Para obtener instrucciones detalladas, consulte Connect to Microsoft Azure
   • Actualice el valor de YAML para que coincida con el nombre de la conexión de servicio.
2. Actualice los identificadores de área de trabajo en YAML:
   • Editar la variable en azure-pipelines.yml
   • Configura los identificadores de área de trabajo de desarrollo y producción
   • Confirmar e insertar los cambios en el repositorio
3. Cree la canalización:
   • Vaya a Canalizaciones nueva canalización.
   • Seleccione el repositorio y elija "Archivo YAML Azure Pipelines existente"
   • Seleccione azure-pipelines.yml
   • Para obtener instrucciones detalladas, consulte Creación de la primera canalización.
   • Guardar y ejecutar la canalización para implementar el PBIP en Fabric

Acciones de GitHub

Automatice las implementaciones de PBIP con Acciones de GitHub. Cuando se inserta código en ramas configuradas, el flujo de trabajo se implementa automáticamente en el área de trabajo correspondiente.

Cree en tu repositorio:

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
          }

Configuración de Acciones de GitHub

1. Crear el secreto de credenciales de Azure:

   • Obtén las credenciales del servicio en formato JSON:

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

   • Vaya a la configuración del repositorio de GitHub > Secretos y variables > Acciones
   • Agregar con el JSON anterior

2. Actualice los identificadores del área de trabajo en el flujo de trabajo:

   • Edite la tabla hash en el paso "Establecer variables del área de trabajo" en
   • Configura los identificadores de área de trabajo de desarrollo y producción
   • Confirmación e inserción del código YAML de flujo de trabajo en el repositorio

Contenido relacionado

• documentación de fabric-cicd
• repositorio de GitHub fabric-cicd
• Introducción a la integración de Git de Fabric
• Power BI planeamiento de implementación: Administración del ciclo de vida del contenido