Tutoriel - Fabric CI/CD avec l'API des définitions d'éléments pour importation massive

Dans ce tutoriel, vous utilisez un pipeline Azure DevOps qui tire parti de l’API de définition d’élément d’importation en bloc pour déployer des éléments à partir d’un dossier Git. Le dossier Git contient des définitions d’éléments d’un espace de travail de développement connecté à Git, et le pipeline les déploie sur un espace de travail de test qui n’est pas connecté à Git.

Prerequisites

• Azure DevOps Azure Project et référentiel + autorisations pour configurer le pipeline Azure DevOps et créer des groupes de variables.
• Nom de l’espace de travail Fabric : bulk-tutorial-test - espace de travail cible pour le déploiement
• Principal de service (SPN) : une inscription d’application Entra ID (Azure AD) avec un secret client doit inclure l’ID client, le secret client et l’ID de locataire.
• Le principal de service dispose de l’autorisation Contributeur pour l’espace bulk-tutorial-test de travail Fabric
• Paramètre d’administration fabric pour le principal de service - Un administrateur Fabric doit activer « Les principaux de service peuvent utiliser les API Fabric » dans le portail d’administration Fabric sous Paramètres du locataire

💡 Pointe: Pour activer l’accès au principal de service dans Fabric, un administrateur Fabric doit activer « Les principaux de service peuvent utiliser les API Fabric » dans le portail d’administration Fabric sous Paramètres du locataire.

Contexte

Dans le déploiement basé sur Git utilisant un environnement de compilation, les déploiements à travers les espaces de travail Fabric proviennent d’un dépôt Git central. Considérez les définitions d’éléments Fabric comme du code et promouvez-les via un flux de libération structuré. Tous les environnements - Dev, Test et Prod - s’alignent sur la même branche principale, tandis que chaque étape est déployée indépendamment en utilisant des pipelines dédiés de build et release.

Les pipelines commencent généralement par exporter des définitions d’éléments Fabric à partir d’un espace de travail de développement à l’aide de l’intégration Git Fabric. Ces définitions peuvent ensuite être validées dans un environnement de construction par le biais de vérifications automatisées, de revues de pull requests et d'application des politiques avant la promotion. (Non abordé dans ce didacticiel).

Pendant le déploiement, le pipeline appelle l’API d'importation en masse pour transférer les définitions d’éléments approuvées dans l’espace de travail cible. L'API prend en charge la création de nouveaux éléments et la mise à jour des éléments existants en place, tout en s'appuyant sur la gestion des dépendances intégrée de Fabric pour garantir que les éléments sont déployés dans l'ordre approprié. Cela permet des déploiements cohérents et reproductibles dans des environnements de test et de production sans intervention manuelle.

Étape 1. Préparer un exemple de dépôt

1. Télécharger le fichier zip bulk-api-demo-zip sur votre ordinateur local
2. L’exemple zip contient :
   • Fichier de pipeline Azure DevOps (deploy-using-bulk-api.yml)
   • Exemple d’espace de travail avec quelques fichiers de définitions d’éléments Fabric (bulk-tutorial-dev)
3. Clonez votre dépôt Azure DevOps sur votre ordinateur local et décompressez le fichier dans ce dossier.
4. Envoyer (push) le nouveau contenu vers le référentiel Azure DevOps

Étape 2. Exécuter Azure DevOps pipeline

2.1 Groupe de variables : bulkapi-group

Ce groupe de variables contient les informations du principal du service utilisées par Azure Pipeline pour s’authentifier.

Étapes de création

1. Accédez à Pipelines → Bibliothèque dans votre projet ADO.
2. Sélectionnez + Groupe de variables.
3. Nomme-le : bulkapi-group
4. Ajoutez les variables suivantes :

2.2 Configuration du pipeline Azure DevOps

Créez un pipeline dans Azure DevOps qui fait référence au fichier YAML deploy-using-bulk-api.yml dans votre dépôt.

Étapes

1. Accédez à Pipelines → Pipelines → Nouveau pipeline.
2. Choisissez Git Azure Repos et sélectionnez votre référentiel.
3. Choisissez le fichier YAML Azure Pipelines existant.
4. Modifiez le pool en fonction du pool d’agents existant, par exemple pour utiliser l’agent Microsoft-Hosted (basé sur Linux) : vmImage: ubuntu-latest
5. Exécuter
6. Une fois le pipeline terminé, l’espace de travail Fabric bulk-tutorial-test contient les éléments déployés.

3. Présentation approfondie du code : YAML du pipeline ADO

File :deploy-using-bulk-api.yml , situé dans le référentiel Azure DevOps.

Le pipeline se compose de trois étapes, chacune effectuant une opération distincte. Vous trouverez ci-dessous chaque étape avec des annotations.

3.1 Déclencheur et configuration du pipeline

Définissez quand le pipeline s’exécute et configurez le pool d’agents et les variables.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Étape 1 : s’authentifier avec l’API Fabric

Obtenez un jeton de porteur auprès de Microsoft Entra ID à l’aide des informations d’identification du principal de service.

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'

Entrée: Informations d’identification SPN du groupe de variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Sortie:FABRIC_TOKEN — un jeton Bearer stocké sous forme de variable secrète de pipeline, utilisé par les étapes suivantes.

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

3.3 Étape 2 : Générer une charge utile et appeler l’API d’importation en bloc

Cette étape effectue trois opérations : résoudre l’ID de l’espace de travail, générer la charge utile de la requête à partir de fichiers locaux et appeler l’API d’importation en bloc.

3.3.1 Résoudre l’ID de l’espace de travail

Recherchez l’ID d’espace de travail cible par nom complet à l’aide de l’API REST Fabric.

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"

Entrée :FABRIC_TOKEN, test_workspace_to_deploy (nom de l’espace de travail)

Sortie:WORKSPACE_ID — GUID de l’espace de travail cible

API appelée :GET https://api.fabric.microsoft.com/v1/workspaces

3.3.2 Générer le corps de la requête encodé en base64

Effectuez une itération dans chaque fichier du dossier source, encodez le contenu en Base64 et assemblez le corps de la requête JSON.

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"

Entrée: Fichiers locaux dans le bulk-tutorial-dev dossier

Sortie:REQUEST_BODY — Charge utile JSON contenant toutes les parties de définition d’élément, encodées en base64

Option clé :allowPairingByName: false — les éléments sont mis en correspondance par l’ID logique (provenant des fichiers .platform), et non par le nom d’affichage.

3.3.3 Appeler l’API d’importation en masse

Envoyez la charge utile à l’API d’importation groupée et récupérez l’ID de l’opération pour le suivi.

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

Entrée :FABRIC_TOKEN, , WORKSPACE_IDREQUEST_BODY

Sortie:OPERATION_ID — l’identificateur d’opération de longue durée, stocké en tant que variable de pipeline

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

Gestion des réponses :

• 200 OK — le déploiement s’est achevé de manière synchrone (résultat dans le corps de la réponse)
• 202 Accepted — le déploiement est asynchrone ; effectuez des interrogations à l’aide de OPERATION_ID
• 4xx — Échec du déploiement ; détails d’erreur dans le corps de la réponse

3.4 Étape 3 : sondage pour l’achèvement du déploiement

Interrogez le point de terminaison d’opération de longue durée jusqu’à ce que le déploiement se termine et que le résultat soit disponible.

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

Entrée :FABRIC_TOKEN, OPERATION_ID

Sortie: Résultat du déploiement JSON contenant l’état par élément

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

Structure des résultats : La réponse contient importItemDefinitionsDetails un tableau avec des résultats par élément :

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

4. Résumé

Ce tutoriel a montré comment utiliser l’API De définition d’élément d’importation en bloc comme mécanisme de déploiement. Il a montré comment déployer des éléments à partir d'un espace de travail de développement connecté à un référentiel Git en extrayant le contenu du référentiel, en le transformant en entrée d'API requise et en le déployant sur un espace de travail de test Fabric qui n'est pas connecté à Git.

Opérations d’API utilisées