Självstudie – Fabric CI/CD med API för massimport av objektdefinitioner

I det här självstudium använder du en Azure DevOps-pipeline som använder Bulk import item definition API:et för att distribuera objekt från en Git-mapp. Git-mappen innehåller objektdefinitioner från en utvecklingsarbetsyta som är ansluten till Git och pipelinen distribuerar dem till en testarbetsyta som inte är ansluten till Git.

Förutsättningar

• Azure DevOps Azure Projekt och databas + behörigheter för att konfigurera en Azure DevOps-pipeline och skapa variabelgrupper.
• Fabric-arbetsytans namn: bulk-tutorial-test – målarbetsyta för distributionen
• Tjänstens huvudnamn (SPN) – En Entra-ID (Azure AD) appregistrering med en klienthemlighet, måste ha klient-ID, klienthemlighet och hyresgäst-ID.
• Tjänstens huvudnamn har deltagarbehörighet för bulk-tutorial-test Fabric-arbetsyta
• Infrastrukturadministratörsinställning för tjänstens huvudnamn – En infrastrukturresursadministratör måste aktivera "Tjänstens huvudnamn kan använda Infrastruktur-API:er" i infrastrukturadministrationsportalen under Klientinställningar

💡 Tips: För att aktivera åtkomst till tjänstens huvudnamn i Infrastrukturresurser måste infrastrukturresursadministratören aktivera "Tjänstens huvudnamn kan använda Infrastruktur-API:er" i infrastrukturadministrationsportalen under Klientinställningar.

Bakgrund

I Git-baserad distribution med en byggmiljö kommer distributioner över Fabric-arbetsytor från ett centralt Git-arkiv. Behandla definitioner av Fabric-produkter som kod och marknadsför dem genom ett strukturerat releaseflöde. Alla miljöer – Dev, Test och Prod – är anpassade till samma huvudbranch, medan varje steg distribueras oberoende genom att använda dedikerade build- och releasepipelines.

Pipelines börjar vanligtvis med att exportera Fabric-artikelsdefinitioner från en utvecklingsarbetsyta med hjälp av Fabric Git Integration. Dessa definitioner kan sedan verifieras i en byggmiljö genom automatiserade kontroller, granskningar av pull-begäranden och principframtvingande före befordran. (Beskrivs inte i den här självstudien).

Under distributionprocessen anropar pipelinen massimport-API:et för att överföra godkända artikeldefinitioner till målarbetsytan. API:et stöder både skapande av nya objekt och uppdatering av befintliga objekt på plats, samtidigt som du förlitar dig på Fabric inbyggda beroendehantering för att säkerställa att objekt distribueras i rätt ordning. Detta möjliggör konsekventa, repeterbara distributioner i test- och produktionsmiljöer utan manuella åtgärder.

Steg 1. Förbered ett exempelarkiv

1. Ladda ned zip-filen bulk-api-demo-zip till din lokala dator
2. Zip-exemplet innehåller:
   • Azure DevOps-pipelinefil (deploy-using-bulk-api.yml)
   • Exempel på arbetsyta med några definitionsfiler för Fabric-objekt (bulk-tutorial-dev)
3. Klona Azure DevOps-lagringsplatsen till den lokala datorn och packa upp filen till den här mappen.
4. Skicka det nya innehållet till Azure DevOps-lagringsplatsen

Steg 2. Kör Azure DevOps-pipeline

2.1 Variabelgrupp: bulkapi-group

Den här variabelgruppen lagrar information om tjänstens huvudnamn som Azure Pipeline autentiserar med.

Steg för att skapa

1. Gå till Pipelines → Library i ditt ADO-projekt.
2. Välj + Variabelgrupp.
3. Ge den namnet: bulkapi-group
4. Lägg till följande variabler:

2.2 Konfiguration av Azure DevOps-pipeline

Skapa en pipeline i Azure DevOps som refererar till deploy-using-bulk-api.yml YAML-filen i ditt repo.

Instruktioner

1. Gå till Pipelines → Pipelines → Ny pipeline.
2. Välj Azure-lagringsplatser Git och välj din lagringsplats.
3. Välj befintlig YAML-fil för Azure-pipelines.
4. Ändra pool enligt befintlig agentpool, till exempel för att använda Microsoft-Hosted agent (Linux-baserad) användning: vmImage: ubuntu-latest
5. Run
6. När pipelinen har slutförts innehåller Fabric-arbetsytan bulk-tutorial-test de distribuerade objekten.

3. Djupdykning i kod: YAML för ADO-pipeline

File:deploy-using-bulk-api.yml – finns på den Azure DevOps lagringsplatsen.

Pipelinen består av tre steg som var och en utför en distinkt åtgärd. Nedan visas varje steg med anteckningar.

3.1 Utlösare för pipeline och konfiguration

Definiera när pipelinen körs och konfigurera agentpoolen och variablerna.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Steg 1 – Autentisera med Fabric API

Hämta en bärartoken från Microsoft Entra ID med inloggningsuppgifter för tjänsthuvudnamn.

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-autentiseringsuppgifter från variabelgruppen (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Utdata:FABRIC_TOKEN — en bearer-token som lagras som en hemlig pipeline-variabel och används i efterföljande steg.

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

3.3 Steg 2 – Skapa nyttolast och anropa API för massimport

Det här steget utför tre åtgärder: lös arbetsyte-ID:t, skapa nyttolasten för begäran från lokala filer och anropa API:et massimport.

3.3.1 Lös arbetsyte-ID

Leta upp mål-arbetsytans ID utifrån visningsnamn med hjälp av 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 (arbetsytans namn)

Utdata:WORKSPACE_ID — GUID:et för målarbetsytan

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

3.3.2 Skapa base64-kodad begärandetext

Iterera genom varje fil i källmappen, koda innehållet i Base64 och montera JSON-begärandetexten.

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

Utdata:REQUEST_BODY — JSON-nyttolast som innehåller alla delar av objektdefinitionen, base64-kodad

Nyckelalternativ:allowPairingByName: false — objekt matchas av logiskt ID (från .platform filer), inte med visningsnamn.

3.3.3 Anropa API:et för massimport

Skicka data till Bulk Import API och hämta operations-ID:t för pollning.

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

Utdata:OPERATION_ID — identifieraren för den långvariga åtgärden, lagrad som en pipelinevariabel

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

Svarshantering:

• 200 OK — distributionen slutfördes synkront (resulterar i brödtext)
• 202 Accepted — distributionen är asynkron. avsökning med hjälp av OPERATION_ID
• 4xx — driftsättningen misslyckades; feldetaljer i svarstexten

3.4 Steg 3 – Kontrollera att driftsättningen har slutförts

Fråga av slutpunkten för den långvariga åtgärden tills distributionen har slutförts och resultatet är tillgängligt.

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

Indata:FABRIC_TOKEN, OPERATION_ID

Utdata: JSON med distributionsresultat som innehåller status för varje objekt

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

Resultatstruktur: Svaret innehåller importItemDefinitionsDetails – en matris med resultat per objekt:

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

4. Sammanfattning

Den här handledningen visade hur du använder Bulk Import Item Definition API:et som distributionsmekanism. Den visade hur du distribuerar objekt från en dev-arbetsyta som är ansluten till en Git-lagringsplats genom att extrahera lagringsplatsens innehåll, omvandla det till nödvändiga API-indata och distribuera det till ett test Fabric arbetsyta som inte är ansluten till Git.

API-åtgärder som används