Tutorial - Fabric CI/CD con la API de Definiciones de Artículos de Importación Masiva

En este tutorial, usas un pipeline de Azure DevOps que utiliza la API de definición de elementos de importación masiva para implementar elementos desde una carpeta Git. La carpeta Git contiene definiciones de elementos de un área de trabajo de desarrollo que está conectada a Git y la canalización las implementa en un área de trabajo de prueba que no está conectada a Git.

Prerrequisitos

• Azure DevOps Proyecto de Azure y repositorio, además de permisos para configurar la canalización de Azure DevOps y crear grupos de variables.
• Nombre del área de trabajo de Fabric : bulk-tutorial-test área de trabajo de destino para la implementación
• Principal de servicio (SPN): un registro de aplicación de Entra ID (Azure AD) con un secreto de cliente, debe tener el identificador de cliente, el secreto de cliente y el identificador de locatario.
• La entidad de servicio tiene permiso de colaborador para el bulk-tutorial-test área de trabajo de Fabric.
• Configuración de Fabric Admin para la entidad de servicio: un administrador de Fabric debe habilitar "Las entidades de servicio pueden usar las API de Fabric" en el Portal de administración de Fabric en Configuración del inquilino

💡 Consejo: Para habilitar el acceso al Principal de servicio en Fabric, un administrador de Fabric debe habilitar "Los principales de servicio pueden usar las API de Fabric" en el Portal de administración de Fabric en Configuración del arrendatario.

Antecedentes

En la implementación basada en Git mediante un entorno de compilación, las implementaciones en áreas de trabajo de Microsoft Fabric se controlan desde un repositorio de Git central, donde las definiciones de elementos de Fabric se tratan como código y se promueven a través de un flujo de versión estructurado. Todos los entornos ( Desarrollo, Prueba y Prod) están alineados con la misma rama principal, mientras que cada fase se implementa de forma independiente mediante canalizaciones de compilación y versión dedicadas.

Normalmente, las canalizaciones comienzan exportando definiciones de elementos de Fabric desde un área de trabajo de desarrollo mediante Fabric Git Integration. Estas definiciones se pueden validar en un entorno de compilación mediante comprobaciones automatizadas, revisiones de solicitudes de incorporación de cambios y aplicación de directivas antes de la promoción. (No se trata en este tutorial).

Durante la implementación, el pipeline invoca la API Bulk Import para promover las definiciones de elementos aprobadas en el área de trabajo de destino. La API admite la creación de nuevos elementos y la actualización de los existentes, mientras se basa en el control de dependencias integrado de Fabric para asegurarse de que los elementos se implementan en el orden correcto. Esto permite implementaciones coherentes y repetibles en entornos de prueba y producción sin intervención manual.

Paso 1. Preparación de un repositorio de ejemplo

1. Descargue el archivo ZIP bulk-api-demo-zip en la máquina local.
2. El archivo ZIP de ejemplo contiene:
   • Archivo de canalización de Azure DevOps (deploy-using-bulk-api.yml)
   • Área de trabajo de ejemplo con pocos archivos de definiciones de elementos de Fabric (bulk-tutorial-dev)
3. Clone el repositorio de Azure DevOps en el equipo local y descomprima el archivo en esta carpeta.
4. Inserción del nuevo contenido en el repositorio de Azure DevOps

Paso 2. Ejecución de la canalización de Azure DevOps

2.1 Grupo de variables: bulkapi-group

Este grupo de variables almacena las credenciales de la entidad de servicio que utiliza la canalización de Azure para autenticarse.

Pasos para crear

1. Vaya a Pipelines → Library en el proyecto de ADO.
2. Seleccione + Grupo de variables.
3. Asígnelo un nombre: bulkapi-group
4. Agregue las siguientes variables:

2.2 Configuración de la canalización de Azure DevOps

Cree una canalización en Azure DevOps que haga referencia al archivo deploy-using-bulk-api.yml YAML en el repositorio.

Pasos

1. Vaya a Canalizaciones → Canalizaciones → Nueva canalización.
2. Elija Git de Azure Repos y seleccione el repositorio.
3. Elija El archivo YAML de Azure Pipelines existente.
4. Cambie el pool según el grupo de agentes existente, por ejemplo, para usar el agente de Microsoft-Hosted (basado en Linux): vmImage: ubuntu-latest
5. Ejecutar
6. Una vez finalizada la canalización, el área de trabajo de bulk-tutorial-test Fabric contiene los elementos implementados.

3. Análisis en profundidad del código: YAML de la canalización de ADO

File:deploy-using-bulk-api.yml, ubicado en el repositorio de Azure DevOps.

La canalización consta de tres pasos, cada uno de los cuales realiza una operación distinta. A continuación se muestra cada paso con anotaciones.

3.1 Activador y configuración de la canalización

Defina cuándo se ejecuta la canalización y configure el grupo de agentes y las variables.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

variables:
  - group: bulkapi-group
  - name: test_workspace_to_deploy
    value: "bulk-tutorial-test"

3.2 Paso 1: Autenticación con Fabric API

Adquiera un token de portador de Microsoft Entra ID mediante credenciales de entidad de servicio.

stages:
  - stage: Deploy_Test
    jobs:
      - job: Deploy
        displayName: 'Deploy using Bulk-API'
        steps:
        - checkout: self
        - script: |
            TOKEN=$(curl -s -X POST \
              "https://login.microsoftonline.com/$(AZURE_TENANT_ID)/oauth2/v2.0/token" \
              -H "Content-Type: application/x-www-form-urlencoded" \
              -d "client_id=$(AZURE_CLIENT_ID)&client_secret=$(AZURE_CLIENT_SECRET)&scope=https://api.fabric.microsoft.com/.default&grant_type=client_credentials" \
              | jq -r '.access_token')
            echo "##vso[task.setvariable variable=FABRIC_TOKEN;issecret=true]$TOKEN"
          displayName: 'Get Fabric API token'

Entrada: Credenciales de SPN del grupo de variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Salida:FABRIC_TOKEN : un token de portador almacenado como una variable de canalización secreta, que se usa en pasos posteriores.

API llamada:POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

3.3 Paso 2: compilación de la carga útil y llamada a la API de importación masiva

Este paso realiza tres operaciones: resolver el identificador del área de trabajo, compilar la carga de la solicitud a partir de archivos locales y llamar a la API de importación masiva.

3.3.1 Resolver el identificador del área de trabajo

Busque el identificador del área de trabajo de destino por nombre para mostrar mediante la API REST de Fabric.

WORKSPACE_ID=$(curl -s -H "Authorization: Bearer $(FABRIC_TOKEN)" \
  "https://api.fabric.microsoft.com/v1/workspaces" \
  | jq -r '.value[] | select(.displayName=="'"$(test_workspace_to_deploy)"'") | .id')

if [ -z "$WORKSPACE_ID" ] || [ "$WORKSPACE_ID" = "null" ]; then
  echo "##vso[task.logissue type=error]Workspace '$(test_workspace_to_deploy)' not found"
  exit 1
fi
echo "Workspace ID: $WORKSPACE_ID"

Input:FABRIC_TOKEN, test_workspace_to_deploy (nombre del área de trabajo)

Salida:WORKSPACE_ID — el GUID del área de trabajo de destino

API llamada:GET https://api.fabric.microsoft.com/v1/workspaces

3.3.2 Compilar cuerpo de solicitud codificado en base64

Recorrer en iteración cada archivo de la carpeta de origen, codificar el contenido en Base64 y ensamblar el cuerpo de la solicitud JSON.

BASE_DIR="$(Build.SourcesDirectory)/bulk-tutorial-dev"

PARTS_JSON="[]"
while IFS= read -r -d '' FILE; do
  REL_PATH="/${FILE#$BASE_DIR/}"
  PAYLOAD=$(base64 -w 0 "$FILE" 2>/dev/null || base64 "$FILE")
  PARTS_JSON=$(echo "$PARTS_JSON" | jq \
    --arg path "$REL_PATH" \
    --arg payload "$PAYLOAD" \
    '. + [{path: $path, payload: $payload, payloadType: "InlineBase64"}]')
done < <(find "$BASE_DIR" -type f -print0)

REQUEST_BODY=$(jq -n \
  --argjson parts "$PARTS_JSON" \
  '{
    definitionParts: $parts,
    options: {
      allowPairingByName: false
    }
  }')

echo "Request body built with $(echo "$PARTS_JSON" | jq length) parts"

Entrada: Archivos locales de la carpeta bulk-tutorial-dev

Salida:REQUEST_BODY : carga JSON que contiene todas las partes de definición de elementos, codificadas en base64

Opción clave:allowPairingByName: false — los elementos se emparejan según el identificador lógico (de los archivos .platform), no por el nombre para mostrar.

3.3.3 Llamada a la API de importación masiva

Envíe la carga a la API de importación masiva y capture el identificador de operación para el sondeo.

API_URL="https://api.fabric.microsoft.com/v1/workspaces/$WORKSPACE_ID/items/bulkImportDefinitions?beta=true"
echo "Calling Bulk Import Item definition API: $API_URL"

HEADER_FILE=$(mktemp)
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
  "$API_URL" \
  -H "Authorization: Bearer $(FABRIC_TOKEN)" \
  -H "Content-Type: application/json" \
  -D "$HEADER_FILE" \
  -d "$REQUEST_BODY")

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')

echo "HTTP Status: $HTTP_CODE"
echo "$BODY" | jq . 2>/dev/null || echo "$BODY"

OPERATION_ID=$(grep -i '^x-ms-operation-id:' "$HEADER_FILE" | awk '{print $2}' | tr -d '\r\n ')
echo "Operation ID: $OPERATION_ID"
rm -f "$HEADER_FILE"

echo "##vso[task.setvariable variable=OPERATION_ID]$OPERATION_ID"

if [ "$HTTP_CODE" -ge 400 ]; then
  echo "##vso[task.logissue type=error]Bulk import failed with HTTP $HTTP_CODE"
  exit 1
fi

Input:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

Salida:OPERATION_ID : identificador de operación de ejecución prolongada, almacenado como una variable de canalización.

API llamada:POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/bulkImportDefinitions?beta=true

Control de respuestas:

• 200 OK : implementación completada sincrónicamente (resultado en el cuerpo)
• 202 Accepted — la implementación es asincrónica; sondeo mediante OPERATION_ID
• 4xx — error de implementación; detalles del error en el cuerpo de la respuesta

3.4 Paso 3 — Comprobar la finalización del despliegue

Sondee el punto de conexión de operación de ejecución prolongada hasta que se complete la implementación y el resultado esté disponible.

        - script: |
            echo "Polling operation: $(OPERATION_ID)"

            while true; do
              RESULT=$(curl -s -H "Authorization: Bearer $(FABRIC_TOKEN)" \
                "https://api.fabric.microsoft.com/v1/operations/$(OPERATION_ID)/result")

              HAS_DETAILS=$(echo "$RESULT" | jq \
                'has("importItemDefinitionsDetails") and (.importItemDefinitionsDetails != null)')

              if [ "$HAS_DETAILS" = "true" ]; then
                echo "Operation complete. Result:"
                echo "$RESULT" | jq .
                break
              fi

              echo "Operation not yet completed. Waiting 10 seconds..."
              sleep 10
            done
          displayName: 'Poll LRO until complete'

Input:FABRIC_TOKEN, OPERATION_ID

Salida: JSON del resultado del despliegue con el estado de cada elemento

API llamada:GET https://api.fabric.microsoft.com/v1/operations/{operationId}/result

Estructura de resultados: La respuesta contiene importItemDefinitionsDetails : una matriz con resultados por elemento:

{
  "importItemDefinitionsDetails": [
    {
      "itemId": "c4dd0eac-...",
      "itemDisplayName": "MyReport",
      "itemType": "Report",
      "itemLogicalId": "88436e65-...",
      "operationType": "Create",
      "operationStatus": "Succeeded"
    }
  ]
}

4. Resumen

En este tutorial se muestra cómo usar bulk Import Item Definition API como mecanismo de implementación. Mostró cómo implementar elementos desde un área de trabajo de desarrollo conectada a un repositorio de Git mediante la extracción del contenido del repositorio, su transformación en la entrada de API necesaria e la implementación en un área de trabajo de prueba Fabric que no está conectada a Git.

Operaciones de API usadas