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, samtidig med at Fabric's indbyggede afhængighedshåndtering er afhængigt for at sikre, at elementer implementeres i korrekt rækkefølge. Dette muliggør konsistente, gentagelige implementeringer i test- og produktionsmiljøer uden manuel indgriben.

Trin 1. Forbered et prøverepo

1. Download zip-filen bulk-api-demo-zip til din lokale maskine
2. Eksempel-zip'en indeholder:
   • Azure DevOps pipeline-fil (deploy-using-bulk-api.yml)
   • Eksempel på arbejdsområde med få Fabric-items-definitionsfiler (bulk-tutorial-dev)
3. Klon dit Azure DevOps-repository til din lokale maskine, og pak filen ud i denne mappe.
4. Skub det nye indhold til Azure DevOps-repositoryet

Trin 2. Run Azure DevOps pipeline

2.1 Variabelgruppe: bulkapi-group

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

Trin til oprettelse

1. Navigér til Pipelines → Library i dit ADO-projekt.
2. Vælg + variabelgruppe.
3. Nævn det: bulkapi-group
4. Tilføj følgende variable:

2.2 Azure DevOps Pipeline setup

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

Trin

1. Navigér til Pipelines → Pipelines → Ny pipeline.
2. Vælg Azure Repos Git og vælg dit repository.
3. Vælg Existing Azure Pipelines YAML file.
4. Ændr pool i henhold til eksisterende agentpulje, for eksempel for at bruge Microsoft-Hosted agent (Linux-baseret) bruge: vmImage: ubuntu-latest
5. Løbe
6. Efter pipeline-færdiggørelsen indeholder bulk-tutorial-test Fabric-arbejdsområdet de deployerede elementer.

3. Kodedybdegående gennemgang: ADO Pipeline YAML

File:deploy-using-bulk-api.yml — placeret i Azure DevOps-arkivet.

Pipelinen består af tre trin, som hver udfører en særpræget operation. Nedenfor er hvert trin med noter.

3.1 Pipeline-trigger og konfiguration

Definér, hvornår pipelinen kører, og konfigurer agentpuljen og variablerne.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Trin 1 — Autentificer med Fabric API

Erhverv et bærertoken fra Microsoft Entra ID ved hjælp af service principal credentials.

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: SPN-legitimationsoplysninger fra variabelgruppen (AZURE_TENANT_ID, AZURE_CLIENT_ID, ) AZURE_CLIENT_SECRET

Output:FABRIC_TOKEN — en bærertoken gemt som en hemmelig pipeline-variabel, brugt af efterfølgende trin.

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

3.3 Trin 2 — Byg payload og kald Bulk Import API

Dette trin udfører tre operationer: opløser arbejdsområde-ID'et, bygger anmodningspayload ud fra lokale filer og kalder Bulk Import API'en.

3.3.1 Resolve workspace ID

Slå målarbejdsområdets ID op efter visningsnavn ved hjælp af Fabric REST API'en.

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 (arbejdsområdenavn)

Output:WORKSPACE_ID — GUID for målarbejdsområdet

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

3.3.2 Build base64-kodet anmodningskrop

Iterer gennem hver fil i kildemappen, kod indholdet i Base64, og saml JSON-anmodningskroppen.

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: Lokale filer i bulk-tutorial-dev mappen

Output:REQUEST_BODY — JSON-payload, der indeholder alle item definition-dele, base64-kodet

Nøglemulighed:allowPairingByName: false — elementer matches med logisk ID (fra .platform filer), ikke ved visningsnavn.

3.3.3 Kald Bulk Import API'en

Send nyttelasten til Bulk Import API'en og indsaml operations-ID'et til 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

Input:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

Output:OPERATION_ID — den langvarige operation-identifikator, gemt som en pipeline-variabel

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

Responshåndtering:

• 200 OK — udrulning fuldført synkront (resultat i kroppen)
• 202 Accepted — udrulning er asynkron; afstemning ved brug af OPERATION_ID
• 4xx — udsendelsen mislykkedes; fejldetaljer i responsteksten

3.4 Trin 3 — Afstemning for gennemførelse af udsendelsen

Poll det langvarige operationsendepunkt, indtil udrulningen er færdig, og resultatet er tilgængeligt.

        - 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: Implementeringsresultat-JSON indeholder status pr. element

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

Resultatstruktur: Svaret indeholder importItemDefinitionsDetails — et array med resultater pr. opgave:

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

4. Resumé

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

API-operationer brugt