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.

Passaggio 1: Preparare un repository di esempio

1. Scaricare il file ZIP bulk-api-demo-zip nel computer locale
2. 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)
3. Clonare il repository Azure DevOps nel computer locale e decomprimere il file in questa cartella.
4. Eseguire il push del nuovo contenuto nel repository Di Azure DevOps

Passaggio 2. Esegui pipeline di Azure DevOps

2.1 Gruppo di variabili: bulkapi-group

Questo gruppo di variabili archivia i dettagli dell'entità di servizio con cui la pipeline di Azure si autentica.

Passaggi per la creazione

1. Passare a Pipeline → Library nel progetto ADO.
2. Selezionare + Gruppo di variabili.
3. Denominarlo: bulkapi-group
4. Aggiungere le variabili seguenti:

2.2 Configurazione della pipeline di Azure DevOps

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

Gradi

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

3. Approfondimento del codice: YAML della pipeline ADO

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

La pipeline è costituita da tre passaggi, ognuno dei quali esegue un'operazione distinta. Di seguito è riportato ogni passaggio con annotazioni.

3.1 Attivazione e configurazione della pipeline

Definire quando la pipeline viene eseguita e configurare il pool di agenti e le variabili.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Passaggio 1 - Eseguire l'autenticazione con l'API Fabric

Acquisisci un token bearer da Microsoft Entra ID tramite le credenziali del 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'

Input: Credenziali SPN dal gruppo di variabili (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Output:FABRIC_TOKEN — un token bearer archiviato come variabile segreta della pipeline, utilizzato dai passaggi successivi.

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

3.3 Passaggio 2 - Compilare il payload e chiamare l'API di importazione bulk

Questo passaggio esegue tre operazioni: risolvere l'ID dell'area di lavoro, compilare il payload della richiesta dai file locali e chiamare l'API di importazione bulk.

3.3.1 Risolvere l'ID dell'area di lavoro

Cercare l'ID dell'area di lavoro di destinazione in base al nome visualizzato usando l'API REST 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 (nome dell'area di lavoro)

Output:WORKSPACE_ID — GUID dell'area di lavoro di destinazione

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

3.3.2 Creare il corpo della richiesta codificato in Base64

Scorrere ogni file nella cartella di origine, codificare il contenuto in Base64 e assemblare il corpo della richiesta 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"

Input: File locali nella bulk-tutorial-dev cartella

Output:REQUEST_BODY — Payload JSON contenente tutte le parti di definizione dell'elemento, con codifica base64

Opzione chiave:allowPairingByName: false — gli elementi corrispondono in base all'ID logico (da .platform file), non in base al nome visualizzato.

3.3.3 Richiamare l'API di importazione in blocco

Invia il payload all'API di importazione in blocco e recupera l'ID dell'operazione per l'interrogazione periodica.

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

Output:OPERATION_ID — identificatore dell'operazione a esecuzione prolungata, archiviato come variabile della pipeline

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

Gestione delle risposte:

• 200 OK — distribuzione completata sincronamente (risultato nel corpo della risposta)
• 202 Accepted — la distribuzione è asincrona; eseguire il polling utilizzando OPERATION_ID
• 4xx — distribuzione non riuscita; dettagli dell'errore nel corpo della risposta

3.4 Passaggio 3 — Verificare periodicamente il completamento della distribuzione

Interroga ripetutamente l'endpoint dell'operazione di lunga durata finché la distribuzione non è completata e il risultato non è disponibile.

        - 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

Output: JSON del risultato della distribuzione contenente lo stato per elemento

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

Struttura dei risultati: La risposta contiene importItemDefinitionsDetails una matrice con risultati per elemento:

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

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.

Operazioni API usate