Anleitung: Fabric CI/CD mit API für Massenimport von Elementdefinitionen

In diesem Tutorial verwenden Sie eine Azure-DevOps-Pipeline, die die Massenimportelementdefinitions-API nutzt, um Elemente aus einem Git-Ordner bereitzustellen. Der Git-Ordner enthält Elementdefinitionen aus einem Entwicklungsarbeitsbereich , der mit Git verbunden ist, und die Pipeline stellt sie in einem Testarbeitsbereich bereit, der nicht mit Git verbunden ist.

Voraussetzungen

• Azure DevOps Azure Project und Repository + Berechtigungen zum Konfigurieren der Azure DevOps-Pipeline und Erstellen von Variablengruppen.
• Name des Fabric-Arbeitsbereichs : bulk-tutorial-test – Zielarbeitsbereich für die Bereitstellung
• Dienstprinzipal (SPN) – Eine Entra-ID (Azure AD)-App-Registrierung mit einem Clientgeheimnis muss die Client-ID, das Clientgeheimnis und die Mandanten-ID haben.
• Der Dienstprinzipal verfügt über die Berechtigung "Mitwirkender " für bulk-tutorial-test den Fabric-Arbeitsbereich.
• Fabric-Administratoreinstellung für Dienstprinzipal – Ein Fabric-Administrator muss "Dienstprinzipale können Fabric-APIs verwenden" im Fabric Admin Portal unter Mandanteneinstellungen aktivieren.

💡 Tipp: Um den Dienstprinzipalzugriff in Fabric zu aktivieren, muss ein Fabric-Administrator "Dienstprinzipale können Fabric-APIs verwenden" im Fabric Admin Portal unter Mandanteneinstellungen aktivieren.

Hintergrund

Bei einer Git-basierten Bereitstellung mit einer Build-Umgebung erfolgen Deployments über Fabric-Arbeitsbereiche hinweg aus einem zentralen Git-Repository. Behandle die Definitionen von Fabric-Artikeln als Code und bewirbe sie durch einen strukturierten Release-Flow. Alle Umgebungen – Entwicklung, Test und Produktion – sind auf denselben Hauptzweig ausgerichtet, während jede Stufe unabhängig durch dedizierte Build- und Release-Pipelines bereitgestellt wird.

Pipelines beginnen in der Regel mit dem Exportieren von Fabric-Elementdefinitionen aus einem Entwicklungsarbeitsbereich mithilfe der Fabric Git-Integration. Diese Definitionen können dann in einer Buildumgebung durch automatisierte Prüfungen, Pullanforderungsüberprüfungen und Richtlinienerzwingung vor der Heraufführung überprüft werden. (In diesem Lernprogramm nicht behandelt).

Während der Bereitstellung ruft die Pipeline die Massenimport-API auf, um genehmigte Elementdefinitionen in den Zielarbeitsbereich zu importieren. Die API unterstützt sowohl das Erstellen neuer Elemente als auch das Aktualisieren vorhandener Elemente, wobei die integrierte Abhängigkeitsbehandlung von Fabric verwendet wird, um sicherzustellen, dass Elemente in der richtigen Reihenfolge bereitgestellt werden. Dies ermöglicht konsistente, wiederholbare Bereitstellungen in Test- und Produktionsumgebungen ohne manuelle Eingriffe.

Schritt 1. Vorbereiten eines Beispiel-Repositorys

1. Laden Sie die ZIP-Datei bulk-api-demo-zip auf Ihren lokalen Computer herunter.
2. Das Zip-Beispiel enthält:
   • Azure DevOps-Pipelinedatei (deploy-using-bulk-api.yml)
   • Beispielarbeitsbereich mit wenigen Fabric-Elementdefinitionsdateien (bulk-tutorial-dev)
3. Klonen Sie Ihr Azure DevOps-Repository auf Ihrem lokalen Computer, und entpacken Sie die Datei in diesen Ordner.
4. Pushen des neuen Inhalts an das Azure DevOps-Repository

Schritt 2. Ausführen Azure DevOps Pipeline

2.1 Variablegruppe: bulkapi-group

In dieser Variablengruppe werden die Dienstprinzipaldetails gespeichert, bei denen die Azure Pipeline authentifiziert wird.

Schritte zum Erstellen

1. Navigieren Sie zu Pipelines → Library in Ihrem ADO-Projekt.
2. Wählen Sie + Variablengruppe.
3. Benennen Sie ihn: bulkapi-group
4. Fügen Sie die folgenden Variablen hinzu:

2.2 Einrichten der Azure DevOps-Pipeline

Erstellen Sie eine Pipeline in Azure DevOps, die auf die YAML-Datei deploy-using-bulk-api.yml in Ihrem Repository verweist.

Schritte

1. Navigieren Sie zu Pipelines → Pipelines → Neue Pipeline.
2. Wählen Sie Azure Repos Git aus, und wählen Sie Ihr Repository aus.
3. Wählen Sie vorhandene YaML-Datei für Azure-Pipelines aus.
4. Ändern Sie den pool entsprechend dem vorhandenen Agentpool, z. B. um Microsoft-Hosted Agent (linuxbasiert) zu verwenden: vmImage: ubuntu-latest
5. Laufen
6. Nach Abschluss der Pipeline enthält der Fabric-Arbeitsbereich bulk-tutorial-test die bereitgestellten Elemente.

3. Detaillierte Analyse des Codes: ADO Pipeline YAML

File:deploy-using-bulk-api.yml - befindet sich im Azure DevOps Repository.

Die Pipeline besteht aus drei Schritten, die jeweils einen unterschiedlichen Vorgang ausführen. Im Folgenden finden Sie jeden Schritt mit Anmerkungen.

3.1 Pipeline-Auslöser und Konfiguration

Definieren Sie, wann die Pipeline ausgeführt wird, und konfigurieren Sie den Agentpool und die Variablen.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Schritt 1 – Authentifizieren mit Fabric-API

Abrufen eines Bearertokens von Microsoft Entra ID mithilfe von Dienstprinzipalanmeldeinformationen.

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'

Eingabe: SPN-Anmeldeinformationen aus variabler Gruppe (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Ausgabe:FABRIC_TOKEN — ein Bearertoken, das als geheime Pipelinevariable gespeichert ist und von nachfolgenden Schritten verwendet wird.

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

3.3 Schritt 2 – Erstellen der Nutzlast und Aufrufen der Massenimport-API

Dieser Schritt führt drei Vorgänge aus: Auflösen der Arbeitsbereichs-ID, Erstellen der Anforderungsnutzlast aus lokalen Dateien und Aufrufen der Massenimport-API.

3.3.1 Arbeitsbereichs-ID auflösen

Suchen Sie die Zielarbeitsbereichs-ID anhand des Anzeigenamens mithilfe der Fabric REST-API.

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 (Arbeitsbereichsname)

Ausgabe:WORKSPACE_ID — die GUID des Zielarbeitsbereichs

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

3.3.2 Base64-kodierten Anforderungshauptteil erstellen

Durchlaufen Sie jede Datei im Quellordner, codieren Sie Inhalte in Base64, und fügen Sie den JSON-Anforderungstext zusammen.

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"

Eingabe: Lokale Dateien im bulk-tutorial-dev Ordner

Ausgabe:REQUEST_BODY — JSON-Nutzlast mit allen Elementdefinitionsteilen, base64-codiert

Schlüsseloption:allowPairingByName: false — Elemente werden mit der logischen ID (aus .platform Dateien) abgeglichen, nicht nach Anzeigename.

3.3.3 Aufrufen der Massenimport-API

Senden Sie die Nutzlast an die Bulk Import API und speichern Sie die Vorgangs-ID für das Polling.

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

Eingabe:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

Ausgabe:OPERATION_ID — der Bezeichner des lang andauernden Vorgangs, der als Pipelinevariable gespeichert wird

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

Antwortbehandlung:

• 200 OK — Synchroner Abschluss der Bereitstellung (Ergebnis im Textkörper)
• 202 Accepted — Die Bereitstellung erfolgt asynchron; fragen Sie den Status über OPERATION_ID ab
• 4xx — Bereitstellung fehlgeschlagen; Fehlerdetails im Antworttext

3.4 Schritt 3 – Umfrage zum Abschluss der Bereitstellung

Fragen Sie den Endpunkt für Vorgänge mit langer Laufzeit so lange ab, bis die Bereitstellung abgeschlossen ist und das Ergebnis verfügbar ist.

        - 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'

Eingabe:FABRIC_TOKEN, OPERATION_ID

Ausgabe: JSON-Bereitstellungsergebnis, das den Status pro Element enthält

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

Ergebnisstruktur: Die Antwort enthält importItemDefinitionsDetails – ein Array mit Ergebnissen pro Element:

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

4. Zusammenfassung

In dieser Anleitung wurde die Verwendung der Bulk Import Item Definition API als Deployment-Mechanismus veranschaulicht. Es wurde gezeigt, wie Elemente aus einem Entwicklungsarbeitsbereich bereitgestellt werden, der mit einem Git-Repository verbunden ist, indem der Repositoryinhalt extrahiert, in die erforderliche API-Eingabe umgewandelt und in einem Test-Fabric Arbeitsbereich bereitgestellt wird, der nicht mit Git verbunden ist.

Verwendete API-Vorgänge