Esercitazione - Infrastruttura CI/CD con l'API per l'importazione in blocco delle definizioni degli elementi

In questa esercitazione si usa una pipeline di Azure DevOps che usa l'API di definizione dell'elemento di importazione bulk per distribuire elementi da una cartella Git. La cartella Git contiene definizioni di elementi da un'area di lavoro di sviluppo connessa a Git e la pipeline le distribuisce in un'area di lavoro di test non connessa a Git.

Prerequisiti

Azure DevOps Azure Project e repository + autorizzazioni per configurare la pipeline di Azure DevOps e creare gruppi di variabili.
Nome del workspace Fabric: bulk-tutorial-test - Workspace di destinazione per il deployment
Service Principal (SPN) - Una registrazione dell'app Entra ID (Azure AD) con un client secret, richiede l'ID client, il client secret e l'ID tenant.
L'entità servizio dispone dell'autorizzazione Collaboratore per bulk-tutorial-test l'area di lavoro Infrastruttura
Impostazione di amministrazione di Fabric per il principale servizio: un amministratore di Fabric deve abilitare "I principali servizio possono usare le API di Fabric" nel portale di amministrazione di Fabric in Impostazioni tenant

💡 Suggerimento: Per abilitare l'accesso al principal del servizio in Fabric, un Amministratore di Fabric deve abilitare "I principal del servizio possono usare le API di Fabric" nel portale di amministrazione di Fabric in Tenant Settings.

Sfondo

Nella distribuzione basata su Git usando un ambiente di compilazione, le distribuzioni nelle aree di lavoro di Microsoft Fabric vengono guidate da un repository Git centrale, in cui le definizioni degli elementi di Fabric vengono considerate come codice e promosse tramite un flusso di rilascio strutturato. Tutti gli ambienti, ovvero Sviluppo, Test e Prod, sono allineati allo stesso ramo principale, mentre ogni fase viene distribuita in modo indipendente usando pipeline di compilazione e rilascio dedicate.

Le pipeline iniziano in genere esportando definizioni di elementi di Fabric da un'area di lavoro di sviluppo usando l'integrazione Git di Fabric. Queste definizioni possono quindi essere convalidate in un ambiente di compilazione tramite controlli automatizzati, revisioni delle richieste pull e imposizione dei criteri prima della promozione. (Non trattato in questa esercitazione).

Durante la distribuzione, la pipeline richiama l'API Bulk Import per promuovere le definizioni di elementi approvate nell'area di lavoro di destinazione. L'API supporta sia la creazione di nuovi elementi che l'aggiornamento di quelli esistenti, mentre si basa sulla gestione delle dipendenze predefinita di Fabric per assicurarsi che gli elementi vengano distribuiti nell'ordine corretto. Ciò consente distribuzioni coerenti e ripetibili in ambienti di test e produzione senza intervento manuale.

Pipeline suggerite per la compilazione e il rilascio utilizzando l'API delle definizioni di elementi di importazione in blocco.

Passaggio 1: Preparare un repository di esempio

Scaricare il file ZIP bulk-api-demo-zip nel computer locale
Il file ZIP di esempio contiene:

File della pipeline di Azure DevOps (deploy-using-bulk-api.yml)
Area di lavoro di esempio con pochi file di definizioni di elementi di Fabric (bulk-tutorial-dev)

Clonare il repository Azure DevOps nel computer locale e decomprimere il file in questa cartella.
Eseguire il push del nuovo contenuto nel repository Di Azure DevOps

Passaggio 2. - Eseguire la pipeline di Azure DevOps

2.1 Gruppo di variabili: `bulkapi-group`

Questo gruppo di variabili archivia i dettagli del principale del servizio con cui Azure Pipeline autentica.

Passaggi per la creazione

Passare a Pipeline → Library nel progetto ADO.
Fare clic su + Gruppo di variabili.
Denominarlo: bulkapi-group
Aggiungere le variabili seguenti:

Nome variabile	Descrizione
`AZURE_TENANT_ID`	Service Principal - ID tenant
`AZURE_CLIENT_ID`	Principale del servizio - ID cliente
`AZURE_CLIENT_SECRET`	Entità servizio - Segreto client (contrassegna come segreto)

2.2 Configurazione della pipeline di Azure DevOps

Creare una pipeline in Azure DevOps che fa riferimento al deploy-using-bulk-api.yml file YAML nel repository.

Gradi

Passare a Pipeline → Pipeline → Nuova pipeline.
Scegliere Azure Repos Git e selezionare il repository.
Scegliere File YAML di Azure Pipelines esistente.
Modificare il pool in base al pool di agenti esistente, ad esempio per usare Microsoft-Hosted agente (basato su Linux): vmImage: ubuntu-latest
Esegui
Al termine della pipeline, l'area di lavoro bulk-tutorial-test Fabric contiene gli elementi distribuiti.

⚠️ Suggerimento per l'autorizzazione: la prima volta che viene eseguita la pipeline, ADO potrebbe richiedere di autorizzare l'accesso ai gruppi di variabili e agli ambienti. Un amministratore ADO può pre-autorizzare questi elementi in Impostazioni → pipeline.

⚠️ Suggerimento per la produzione: questa pipeline illustra la distribuzione in un ambiente di test. La distribuzione di produzione può seguire un flusso simile, con un gate di approvazione aggiunto dopo la corretta convalida nell'ambiente di test.

3. Approfondimento del codice: YAML della pipeline ADO

File:deploy-using-bulk-api.yml: disponibile nel repository Di Azure DevOps.

Di seguito è presentata la pipeline completa con annotazioni riga per riga.

# ──────────────────────────────────────────────────────────────
# TRIGGER: pipeline start on every push to main branch
# ──────────────────────────────────────────────────────────────
trigger:
  branches:
    include:
    - main


# ─────────────────────────────────────────────────────────────────────────────────────────
# Define the Azure DevOps agent, use of the variable group, and parameters initialization
# ─────────────────────────────────────────────────────────────────────────────────────────
pool:
  vmImage: ubuntu-latest

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


# ────────────────────────────────────────────────────────────────
# Step 1: Checkout & Get Fabric API token using service principal
# ────────────────────────────────────────────────────────────────
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 using service principal'


# ────────────────────────────────────────────────────────────────────
# Step 2: Build REQUEST_BODY and call Bulk Import Item Definitions API 
# ────────────────────────────────────────────────────────────────────
        - script: |
            ## Get workspace ID from workspace name to deploy
            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"

            ## Iterate through each file in the specified folder, read its contents, and encode them in Base64.
            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)

            ## Prepare the request body with base64 encoded items
            REQUEST_BODY=$(jq -n \
              --argjson parts "$PARTS_JSON" \
              '{
                definitionParts: $parts,
                options: {
                  allowPairingByName: false
                }
              }')

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

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

            # Call the Bulk Import API and capture response headers
            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"

            # Extract operation ID from response headers
            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"

            # Set as variable for the next step
            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
          displayName: 'Deploy to $(test_workspace_to_deploy)'


# ────────────────────────────────────────
# Step 3: Wait for Deployment to complete 
# ────────────────────────────────────────
        - 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")

              # Check if importItemDefinitionsDetails exists and is not null
              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'

4. Riepilogo

Questa esercitazione ha illustrato come usare l'API Bulk Import Item Definition come meccanismo di distribuzione. Ha illustrato come distribuire elementi da un'area di lavoro di sviluppo connessa a un repository Git estraendo il contenuto del repository, trasformandolo nell'input API richiesto e distribuendolo in un'area di lavoro di Test Fabric non connessa a Git.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-18