Partekatu bidez

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

Importante

Los proyectos de Power BI Desktop se encuentran actualmente en versión preliminar.

fabric-cicd es una biblioteca de Python desarrollada 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 a las áreas de trabajo mediante su formato de definición de código, como modelos semánticos e informes mediante el formato de archivo PBIP.

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
  • Automatice implementaciones con espacios de trabajo basados en ramas utilizando Azure DevOps o GitHub Actions

Obtenga más información sobre el formato PBIP en proyectos de Power BI Desktop (PBIP) y Información general sobre la integración de Git de Fabric.

¿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:

  • Uso de las API rest nativas de Fabric : se basa en las API oficiales de Microsoft Fabric, lo que garantiza la compatibilidad y la compatibilidad a largo plazo.
  • Nativo de Python : integración directa 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 desarrolladores: scripts sencillos de Python 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 el SDK de identidad de Azure con varias opciones de autenticación

Nota:

Para obtener documentación completa, consulte la documentación de fabric-cicd.

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 área 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 archivos y formatos necesarios, consulte Carpeta de informes del proyecto de Power BI Desktop y carpeta del modelo semántico del proyecto de Power BI Desktop.

Sugerencia

Para crear un proyecto de PBIP, abra su archivo PBIX en Power BI Desktop y guárdelo usando Archivo > Guardar como > Proyecto de Power BI (.pbip). Para más información, consulte Proyectos de Power BI Desktop .

3. Crear script de implementación

Cree un deploy.py 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.

Nota:

La primera vez que implemente un modelo semántico con orígenes de datos, debe configurar manualmente las credenciales del origen de datos en el portal de Fabric. Vaya a > modelo semántico del área de trabajo > Configuración > Credenciales del origen de datos. Las implementaciones posteriores reutilizan las credenciales guardadas.

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 parameter.yml 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 python deploy.py --workspace_id "11111111-1111-1111-1111-111111111111" --environment dev, fabric-cicd realiza automáticamente las siguientes acciones:

  1. Lee el archivo "parameter.yml"
  2. Busca todas las instancias de find_value en los archivos de definición de PBIP.
  3. Los reemplaza con el replace_value 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, dev o main)
  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, seguido 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

Cree un principio de servicio en Azure AD con el 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

Nota:

Las entidades de servicio deben estar habilitadas en el nivel de inquilino para usar las API de Fabric. Para obtener más información, consulte Las entidades de servicio pueden llamar a las API públicas de Fabric.

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 dev rama para implementaciones de entornos de desarrollo
  2. Creación de una main 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 azure-pipelines.yml 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. Cree 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.
    • Creación de una nueva conexión de servicio de Azure Resource Manager mediante las credenciales de la entidad de servicio
    • Para obtener instrucciones detalladas, consulte Conexión a Microsoft Azure.
    • Actualice el azureSubscription 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 workspace_ids 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 de 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

GitHub Actions

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 .github/workflows/deploy.yml 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. Cree 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 Configuración > Secretos y variables > Acciones del repositorio de GitHub
    • Agregar AZURE_CREDENTIALS con el JSON anterior

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

    • Edite la workspace_ids tabla hash en el paso "Establecer variables del área de trabajo" en .github/workflows/deploy.yml
    • 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

  • Last updated on