Zelfstudie: FABRIC CI/CD met API voor bulkimportitemdefinities

In deze zelfstudie gebruikt u een Azure DevOps-pijplijn die gebruikmaakt van de api voor het bulksgewijs importeren van itemdefinities om items uit een Git-map te implementeren. De Git-map bevat itemdefinities van een ontwikkelwerkruimte die is verbonden met Git en de pijplijn implementeert deze naar een testwerkruimte die niet is verbonden met Git.

Vereiste voorwaarden

• Azure DevOps Azure Project en opslagplaats + machtigingen voor het configureren van Azure DevOps-pijplijn en het maken van variabele groepen.
• Naam van Fabric-werkruimte: bulk-tutorial-test - doelwerkruimte voor de uitrol
• Service Principal (SPN): een Entra ID (Azure AD) app-registratie met een clientgeheim, moet de client-id, het clientgeheim en de tenant-id bevatten.
• De service-principal heeft Bijdrager machtiging voor bulk-tutorial-test de Fabric-werkruimte
• Fabric-beheerdersinstelling voor service-principal: een Fabric-beheerder moet 'Service-principals kunnen Fabric-API's gebruiken' inschakelen in de Fabric-beheerportal onder Tenantinstellingen

💡 Tip: Als u toegang tot service-principals in Fabric wilt inschakelen, moet een Fabric-beheerder 'Service-principals kunnen Fabric-API's gebruiken' inschakelen in de Fabric-beheerportal onder Tenantinstellingen.

Achtergrond

Bij Git-gebaseerde implementatie met een build-omgeving komen deployments over Fabric-werkruimtes uit een centrale Git-repository. Behandel Fabric-itemdefinities als code en promoot ze via een gestructureerde releaseflow. Alle omgevingen - Dev, Test en Prod - zijn afgestemd op dezelfde hoofdbranch, terwijl elke fase onafhankelijk wordt uitgerold met speciale build- en release-pipelines.

Pijplijnen beginnen meestal met het exporteren van fabric-itemdefinities vanuit een ontwikkelwerkruimte met behulp van Fabric Git Integration. Deze definities kunnen vervolgens worden gevalideerd in een buildomgeving door middel van geautomatiseerde controles, pull-aanvraagbeoordelingen en beleidshandhaving vóór promotie. (Niet behandeld in deze zelfstudie).

Tijdens de implementatie roept de pijplijn de API voor bulkimport aan om goedgekeurde itemdefinities te promoten in de doelwerkruimte. De API ondersteunt zowel het maken van nieuwe items als het bijwerken van bestaande items, terwijl u afhankelijk bent van de ingebouwde afhankelijkheidsafhandeling van Fabric om ervoor te zorgen dat items in de juiste volgorde worden geïmplementeerd. Dit maakt consistente, herhaalbare implementaties mogelijk in test- en productieomgevingen zonder handmatige tussenkomst.

Stap 1. Een voorbeeldopslagplaats voorbereiden

1. Download het zip-bestand bulk-api-demo-zip naar uw lokale computer
2. Het zip-voorbeeld bevat:
   • Azure DevOps-pijplijnbestand (deploy-using-bulk-api.yml)
   • Voorbeeldwerkruimte met weinig definitiebestanden voor Fabric-items (bulk-tutorial-dev)
3. Kloon uw Azure DevOps-opslagplaats naar uw lokale computer en pak het bestand uit in deze map.
4. De nieuwe inhoud pushen naar de Azure DevOps-opslagplaats

Stap 2. Azure DevOps-pijplijn uitvoeren

2.1 Variabele groep: bulkapi-group

Deze variabelegroep slaat de gegevens van de service-principal op waarmee Azure Pipeline zich verifieert.

Stappen voor het maken

1. Navigeer naar Pijplijnen →-bibliotheek in uw ADO-project.
2. Selecteer + Variabele groep.
3. Geef deze de naam: bulkapi-group
4. Voeg de volgende variabelen toe:

2.2 Azure DevOps Pipeline instellen

Maak een pijplijn in Azure DevOps die verwijst naar het YAML-bestand deploy-using-bulk-api.yml in uw opslagplaats.

Steps

1. Navigeer naar Pijplijnen → Pipelines → Nieuwe pijplijn.
2. Kies Azure-opslagplaatsen Git en selecteer uw repository.
3. Kies bestaand YAML-bestand voor Azure-pipelines.
4. Wijzig de pool volgens de bestaande agentgroep, bijvoorbeeld om Microsoft-Hosted agent (op basis van Linux) te gebruiken: vmImage: ubuntu-latest
5. Rennen
6. Nadat de pijplijn is voltooid, bevat de bulk-tutorial-test Fabric-werkruimte de geïmplementeerde items.

3. Diepgaande blik op de code: ADO Pipeline YAML

File:deploy-using-bulk-api.yml, dat zich in de Azure DevOps opslagplaats bevindt.

De pijplijn bestaat uit drie stappen, die elk een afzonderlijke bewerking uitvoeren. Hieronder ziet u elke stap met aantekeningen.

3.1 Pijplijntrigger en -configuratie

Definieer wanneer de pijplijn wordt uitgevoerd en configureer de agentgroep en variabelen.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Stap 1: verifiëren met Fabric-API

Een Bearer-token verkrijgen van Microsoft Entra ID met behulp van service-principalreferenties.

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-referenties van een variabele groep (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Output:FABRIC_TOKEN — een Bearer-token dat is opgeslagen als een geheime pijplijnvariabele, die wordt gebruikt door de volgende stappen.

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

3.3 Stap 2: payload bouwen en API voor bulksgewijs importeren aanroepen

Met deze stap worden drie bewerkingen uitgevoerd: los de werkruimte-id op, bouw de nettolading van de aanvraag uit lokale bestanden en roep de API voor bulkimport aan.

3.3.1 Werkruimte-id oplossen

Zoek de ID van de doelwerkruimte op basis van de weergavenaam op via de 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"

Invoer:FABRIC_TOKEN, test_workspace_to_deploy (werkruimtenaam)

Output:WORKSPACE_ID — de GUID van de doelwerkruimte

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

3.3.2 Maak een base64-gecodeerde aanvraagtekst

Doorloop elk bestand in de bronmap, codeer inhoud in Base64 en stel de hoofdtekst van de JSON-aanvraag samen.

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 bestanden in de map bulk-tutorial-dev

Output:REQUEST_BODY — JSON-nettolading met alle itemdefinitieonderdelen, base64-gecodeerd

Sleuteloptie:allowPairingByName: false — items worden gematcht op logische id (uit .platform bestanden), niet op weergavenaam.

3.3.3 Roep de API voor bulksgewijs importeren aan

Verzend de payload naar de Bulk Import API en sla de bewerkings-ID op om later te pollen.

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

Invoer:FABRIC_TOKEN, , WORKSPACE_IDREQUEST_BODY

Output:OPERATION_ID — de langlopende bewerkings-id, opgeslagen als een pijplijnvariabele

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

Verwerking van antwoorden:

• 200 OK — uitrol synchroon voltooid (resultaat in de hoofdtekst)
• 202 Accepted — de uitrol verloopt asynchroon; voer polling uit via de OPERATION_ID
• 4xx — implementatie is mislukt; foutdetails in antwoordtekst

3.4 Stap 3: peiling voor voltooiing van de implementatie

Bevraag het eindpunt van de langlopende bewerking totdat de uitrol is voltooid en het resultaat beschikbaar is.

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

Invoer:FABRIC_TOKEN, OPERATION_ID

Output: JSON met implementatieresultaat met status per item

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

Resultaatstructuur: Het antwoord bevat importItemDefinitionsDetails : een matrix met resultaten per item:

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

4. Samenvatting

In deze zelfstudie werd gedemonstreerd hoe je de Bulkimport itemdefinitie-API als uitrolmechanisme kunt gebruiken. U ziet hoe u items implementeert vanuit een dev-werkruimte die is verbonden met een Git-opslagplaats door de inhoud van de opslagplaats te extraheren, deze te transformeren in de vereiste API-invoer en deze te implementeren in een test-Fabric werkruimte die niet is verbonden met Git.

API-bewerkingen die worden gebruikt