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.

Du kan valgfritt legge ved en distribusjonsplan til forespørselen om Bulk Import Item Definitions. For forespørselsformat og krav, se Automatiser utrullinger med en utrullingsplan.

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 Setting for Service Principal - En Fabric Admin må aktivere "Service Principals can use Fabric APIs" under OneLake-katalogen>Govern>Configurations>Tenant settings.

💡 Tips: For å aktivere Service Principal-tilgang i Fabric, må en Fabric Admin aktivere "Service Principals can use Fabric APIs" under OneLake-katalogens>Govern>Configurations>Tenant-innstillinger.

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

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

Relatert innhold

• Automatiser utrullinger med en utrullingsplan
• Hva er en utplasseringsplan?