Vejledning - Fabric CI/CD med Bulk Import Item Definitions API

I denne vejledning bruger du en Azure DevOps-pipeline, der udnytter Bulk import item definition api'en til at deployere elementer fra en Git-mappe. Git-mappen indeholder item-definitioner fra et udviklingsarbejdsområde , der er forbundet til Git, og pipelinen deployer dem til et testarbejdsområde , der ikke er forbundet til Git.

Forudsætninger

Azure DevOps Azure Project og repository + tilladelser til at konfigurere Azure DevOps-pipeline og oprette variabelgrupper.
Fabric workspace navn: bulk-tutorial-test - målarbejdsområde for udrulningen
Service Principal (SPN) - En Entra ID (Azure AD) App Registration med en klienthemmelighed, der skal have klient-id, klient-hemmelighed og lejer-id.
Serviceprincipalen har bidragyder-tilladelse til bulk-tutorial-test Fabric-arbejdsområdet
Fabric Admin-indstilling for Service Principal - En Fabric Admin skal aktivere "Service Principals can use Fabric APIs" i Fabric Admin Portal under Lejerindstillinger

💡 Tip: For at aktivere Service Principal-adgang i Fabric skal en Fabric Admin aktivere "Service Principals can use Fabric APIs" i Fabric Admin Portal under Tenant Settings.

Baggrund

I Git-baseret implementering med et build-miljø drives deployments på tværs af Microsoft Fabric-arbejdsområder fra et centralt Git-repository, hvor Fabric-items-definitioner behandles som kode og promoveres gennem en struktureret releaseflow. Alle miljøer – Dev, Test og Prod – er justeret til samme hovedgren, mens hver fase implementeres uafhængigt ved hjælp af dedikerede build- og release-pipelines.

Pipelines begynder typisk med at eksportere Fabric-varedefinitioner fra et udviklingsarbejdsområde ved hjælp af Fabric Git Integration. Disse definitioner kan derefter valideres i et build-miljø gennem automatiserede kontroller, gennemgang af pull requests og håndhævelse af politikker før forfremmelse. (Ikke dækket i denne tutorial).

Under udrulningen kalder pipelinen Bulk Import API'en for at fremme godkendte varedefinitioner ind i målarbejdsområdet. API'et understøtter både oprettelse af nye elementer og opdatering af eksisterende elementer, samtidig med at Fabrics indbyggede afhængighedshåndtering sikrer, at elementer implementeres i den korrekte rækkefølge. Dette muliggør konsistente, gentagelige implementeringer i test- og produktionsmiljøer uden manuel indgriben.

Foreslået build- og release-pipelines ved brug af bulk-import item definitions API.

Trin 1. Forbered et prøverepo

Download zip-filen bulk-api-demo-zip til din lokale maskine
Eksempel-zip'en indeholder:

Azure DevOps pipeline file (deploy-using-bulk-api.yml)
Eksempel på arbejdsområde med få Fabric-items-definitionsfiler (bulk-tutorial-dev)

Klon dit Azure DevOps-repository til din lokale maskine, og pak filen ud i denne mappe.
Skub det nye indhold til Azure DevOps-repositoryet

Trin 2. - Kør Azure DevOps pipeline

2.1 Variabelgruppe: `bulkapi-group`

Denne variabelgruppe gemmer de service principal-detaljer, som Azure Pipeline autentificerer med.

Trin til oprettelse

Navigér til Pipelines → Library i dit ADO-projekt.
Klik + Variabel gruppe.
Nævn det: bulkapi-group
Tilføj følgende variable:

Variabelnavn	Beskrivelse
`AZURE_TENANT_ID`	Service Principal - Lejer-ID
`AZURE_CLIENT_ID`	Serviceprincip - Klient-ID
`AZURE_CLIENT_SECRET`	Servicehovedperson - Klienthemmelighed (Markér som hemmelig)

2.2 Azure DevOps Pipeline setup

Opret en pipeline i Azure DevOps, der refererer deploy-using-bulk-api.yml til - YAML-filen i dit repo.

Trin

Navigér til Pipelines → Pipelines → Ny pipeline.
Vælg Azure Repos Git og vælg dit repository.
Vælg Existing Azure Pipelines YAML file.
Ændr puljen i henhold til eksisterende agentpuljen, f.eks. for at bruge Microsoft-Hosted agent (Linux-baseret): vmImage: ubuntu-latest
Løbe
Efter pipeline-afslutning indeholder bulk-tutorial-test Fabric-arbejdsområdet de deployerede elementer

⚠️ Tilladelsestip: Første gang pipelinen kører, kan ADO bede dig om at autorisere adgang til variablegrupperne og miljøerne. En ADO-administrator kan forhåndsgodkende disse under Pipeline → Settings.

⚠️ Produktionstip: Denne pipeline demonstrerer implementering til et testmiljø. Produktionsudrulningen kan følge en lignende flow, hvor en godkendelsesport tilføjes efter vellykket validering i testmiljøet.

3. Code Deep Dive: ADO Pipeline YAML

Fil:deploy-using-bulk-api.yml- placeret i Azure DevOps-repositoryet.

Nedenfor er hele pipelinen med linje-for-linje annotationer.

# ──────────────────────────────────────────────────────────────
# 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. Resumé

Denne vejledning demonstrerede, hvordan man bruger Bulk Import Item Definition API som en implementeringsmekanisme. Den viste, hvordan man deployer elementer fra et dev-arbejdsområde, der er forbundet til et Git-repository, ved at udtrække repository-indholdet, omdanne det til det nødvendige API-input og deployere det til et test-Fabric-arbejdsområde, der ikke er forbundet til Git.

Feedback

Var denne side nyttig?

Last updated on 2026-03-18