Veiledning - Fabric CI/CD med API for bulkimport av varedefinisjoner

I denne veiledningen bruker du en Azure DevOps-pipeline som utnytter Bulk import item definition api for å distribuere elementer fra en Git-mappe. Git-mappen inneholder item-definisjoner fra et utviklingsarbeidsområde som er koblet til Git, og pipelinen distribuerer dem til et testarbeidsområde som ikke er koblet til Git.

Forutsetninger

• Azure DevOps Azure Project og repository + tillatelser for å konfigurere Azure DevOps-pipeline og opprette variabelgrupper.
• Navn på fabric-arbeidsområdet : bulk-tutorial-test - målarbeidsområde for distribusjonen
• Service Principal (SPN) – En entra-ID (Azure AD) App Registration med en klienthemmelighet, må ha klient-ID, klienthemmelighet og leietaker-ID.
• Tjenestehovedpersonen har bidragsytertillatelse for bulk-tutorial-test Fabric-arbeidsområdet
• Fabric Admin-innstilling for Service Principal – En Fabric Admin må aktivere "Service Principals can use Fabric APIs" i Fabric Admin Portal under Leietakerinnstillinger

💡 Tips: For å aktivere Service Principal-tilgang i Fabric, må en Fabric-administrator aktivere "Service Principals can use Fabric APIs" i Fabric Admin Portal under Leietakerinnstillinger.

Bakgrunn

I Git-basert utrulling ved bruk av et byggemiljø, kommer distribusjoner på tvers av Fabric-arbeidsområder fra et sentralt Git-repositorium. Behandle definisjoner av Fabric-produkter som kode og promoter dem gjennom en strukturert utgivelsesflyt. Alle miljøer – Dev, Test og Prod – tilpasses samme hovedgren, mens hvert trinn distribueres uavhengig ved bruk av dedikerte bygge- og release-pipelines.

Pipelines starter vanligvis med å eksportere Fabric-objektdefinisjoner fra et utviklingsområde ved bruk av Fabric Git-integrasjon. Disse definisjonene kan deretter valideres i et byggemiljø gjennom automatiserte kontroller, gjennomgang av pull requests og håndhevelse av retningslinjer før forfremmelse. (Ikke dekket i denne veiledningen).

Under utrulling kaller pipelinen Bulk Import API for å fremme godkjente varedefinisjoner inn i målarbeidsområdet. API-et støtter både opprettelse av nye elementer og oppdatering av eksisterende elementer, samtidig som det stoler på Fabric sin innebygde avhengighetshåndtering for å sikre at elementene distribueres i riktig rekkefølge. Dette muliggjør konsistente, repeterbare utrullinger i test- og produksjonsmiljøer uten manuell inngripen.

Trinn 1. Forbered et prøverepo

1. Last ned zip-filen bulk-api-demo-zip til din lokale maskin
2. Eksempel-zip-en inneholder:
   • Azure DevOps pipeline-fil (deploy-using-bulk-api.yml)
   • Eksempelarbeidsområde med få definisjonsfiler for Fabric-elementer (bulk-tutorial-dev)
3. Klon Azure DevOps-repositoriet ditt til din lokale maskin, og pakk ut filen i denne mappen.
4. Flytt det nye innholdet til Azure DevOps-repositoriet

Trinn 2. Run Azure DevOps pipeline

2.1 Variabelgruppe: bulkapi-group

Denne variabelgruppen lagrer tjenesteprinsippdetaljene som Azure Pipeline autentiserer seg med.

Trinn for å lage

1. Naviger til Pipelines → Library i ADO-prosjektet ditt.
2. Velg + variabelgruppe.
3. Nevn den: bulkapi-group
4. Legg til følgende variabler:

2.2 Azure DevOps Pipeline setup

Lag en pipeline i Azure DevOps som refererer til deploy-using-bulk-api.yml YAML-filen i repoet ditt.

Fremgangsmåte

1. Naviger til rørledninger → rørledninger → ny rørledning.
2. Velg Azure Repos Git og velg ditt repository.
3. Velg Existing Azure Pipelines YAML file.
4. Endre pool i henhold til eksisterende agentpool, for eksempel for å bruke Microsoft-Hosted agent (Linux-basert) bruker: vmImage: ubuntu-latest
5. Løpe
6. Etter at pipelinen er fullført, inneholder bulk-tutorial-test Fabric-arbeidsområdet de deployerte elementene.

3. Code deep dive: ADO Pipeline YAML

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

Pipelinen består av tre trinn, som hver utfører en egen operasjon. Nedenfor er hvert trinn med merknader.

3.1 Pipeline-trigger og konfigurasjon

Definer når pipelinen kjører og konfigurer agentpoolen og variablene.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Trinn 1 — Autentiser med Fabric API

Skaff en bærertoken fra Microsoft Entra ID ved å bruke tjenesteprinsipp-legitimasjoner.

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'

Innspill: SPN-legitimasjoner fra variabelgruppen (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Utdata:FABRIC_TOKEN — en bærertoken lagret som en hemmelig pipeline-variabel, brukt av påfølgende trinn.

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

3.3 Trinn 2 — Bygg payload og kall Bulk Import API

Dette steget utfører tre operasjoner: løser arbeidsområdets ID, bygger forespørselspayload fra lokale filer, og kaller Bulk Import API.

3.3.1 Resolve workspace ID

Søk opp målarbeidsområdets ID etter visningsnavn ved å bruke 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 (arbeidsområdenavn)

Utdata:WORKSPACE_ID — GUID-en til målarbeidsområdet

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

3.3.2 Build base64-kodet forespørselskropp

Iterer gjennom hver fil i kildemappen, koder innholdet i Base64, og sett sammen JSON-forespørselskroppen.

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"

Innspill: Lokale filer i bulk-tutorial-dev mappen

Utdata:REQUEST_BODY — JSON-nyttelast som inneholder alle deler av elementdefinisjon, base64-kodet

Nøkkelvalg:allowPairingByName: false — blir elementene matchet med logisk ID (fra .platform filer), ikke med visningsnavn.

3.3.3 Kall Bulk Import API

Send nyttelasten til Bulk Import API og fang operasjons-ID-en for 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

Inndata:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

Utdata:OPERATION_ID — den langvarige operasjonsidentifikatoren, lagret som en pipeline-variabel

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

Responshåndtering:

• 200 OK — utplassering fullført synkront (resultat i kroppen)
• 202 Accepted — utplassering er asynkron; avstemning ved bruk av OPERATION_ID
• 4xx — utplassering mislyktes; Feildetaljer i responstekst

3.4 Trinn 3 — Avstemning for fullføring av utplassering

Poll det langvarige operasjonsendepunktet til utrullingen er ferdig og resultatet er tilgjengelig.

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

Innspill:FABRIC_TOKEN, OPERATION_ID

Utdata: Distribusjonsresultat-JSON som inneholder status per element

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

Resultatstruktur: Svaret inneholder importItemDefinitionsDetails — et array med resultater per element:

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

4. Sammendrag

Denne veiledningen demonstrerte hvordan man bruker Bulk Import Item Definition API som en distribusjonsmekanisme. Den viste hvordan man kunne distribuere elementer fra et utviklingsarbeidsområde koblet til et Git-repositorium ved å hente ut innholdet i repositoriet, transformere det til nødvendig API-input, og distribuere det til et test-Fabric-arbeidsområde som ikke er koblet til Git.

API-operasjoner brukt