Samouczek — CI/CD z użyciem interfejsu API definicji elementów do masowego importu w Fabric

W tym samouczku użyjesz potoku usługi Azure DevOps, który korzysta z API definicji zbiorczego importu elementów do wdrażania elementów z folderu Git. Folder Git zawiera definicje elementów z obszaru roboczego deweloperskiego połączonego z Git, a potok przenosi je do testowego obszaru roboczego, który nie jest połączony z Git.

Wymagania wstępne

Azure DevOps Azure Project and repository + permissions to configure Azure DevOps pipeline and create variable groups (Projekt platformy Azure i repozytorium i uprawnienia do konfigurowania potoku usługi Azure DevOps i tworzenia grup zmiennych).
Nazwa obszaru roboczego Fabric: bulk-tutorial-test — docelowy obszar roboczy dla wdrożenia
Jednostka usługi (SPN) — Rejestracja aplikacji Entra ID (Azure AD) z tajnym kluczem klienta, musi mieć identyfikator klienta, tajny klucz klienta i identyfikator dzierżawy.
Jednostka usługi ma uprawnienia Współpracownika dla bulk-tutorial-test obszaru roboczego Fabric
Ustawienie Fabric Admin dla Service Principal - Administrator Fabric musi włączyć "Service principals can use Fabric APIs" w Portalu Administracyjnym Fabric w sekcji Ustawienia dzierżawy

💡 Wskazówka: Aby włączyć dostęp jednostki obsługi w Fabric, administrator Fabric musi włączyć opcję "Jednostki obsługi mogą używać interfejsów API Fabric" w Portalu Administratora Fabric, w obszarze Ustawienia dzierżawy.

Kontekst

W wdrożeniu opartym na Git przy użyciu środowiska kompilacji, wdrożenia w obszarach roboczych Microsoft Fabric są realizowane z centralnego repozytorium Git, gdzie definicje elementów Fabric są traktowane jako kod i przechodzą przez ustrukturyzowany przepływ wydań. Wszystkie środowiska — Dev, Test i Prod — są przypisane do tej samej gałęzi głównej, podczas gdy każdy etap jest wdrażany niezależnie, korzystając z dedykowanych potoków tworzenia i wdrażania.

Potoki zwykle zaczynają się od wyeksportowania definicji elementów sieci szkieletowej z obszaru roboczego programowania przy użyciu integracji z usługą Git Fabric. Te definicje można następnie zweryfikować w środowisku kompilacji za pomocą automatycznych kontroli, przeglądów żądań ściągnięcia i wymuszania zasad przed podwyższeniem poziomu. (Nie omówiono w tym samouczku).

Podczas wdrażania potok wywołuje interfejs API importu zbiorczego, aby przenieść zatwierdzone definicje elementów do docelowego obszaru roboczego. Interfejs API obsługuje zarówno tworzenie nowych elementów, jak i aktualizację istniejących, polegając na wbudowanej obsłudze zależności w Fabric, aby zapewnić, że elementy są wdrażane we właściwej kolejności. Umożliwia to spójne, powtarzalne wdrożenia w środowiskach testowych i produkcyjnych bez ręcznej interwencji.

Sugerowane przepływy pracy kompilacji i wydania z wykorzystaniem interfejsu API definicji elementów zbiorczego importu.

Krok 1. Przygotowywanie przykładowego repozytorium

Pobierz plik zip bulk-api-demo-zip na komputer lokalny
Przykładowy plik zip zawiera:

Plik potoku usługi Azure DevOps (deploy-using-bulk-api.yml)
Przykładowy obszar roboczy z kilkoma plikami definicji elementów Fabric (bulk-tutorial-dev)

Sklonuj repozytorium usługi Azure DevOps na komputer lokalny i rozpakuj plik do tego folderu.
Wypychanie nowej zawartości do repozytorium usługi Azure DevOps

Krok 2. — Uruchamianie potoku usługi Azure DevOps

2.1 Grupa zmiennych: `bulkapi-group`

Ta grupa zmiennych przechowuje szczegóły obiektu usługi, których używa do uwierzytelniania Azure Pipeline.

Kroki tworzenia

Przejdź do sekcji Pipelines → Library w projekcie ADO.
Kliknij pozycję + Grupa zmiennych.
Nadaj mu nazwę: bulkapi-group
Dodaj następujące zmienne:

Nazwa zmiennej	Opis
`AZURE_TENANT_ID`	Service Principal — identyfikator dzierżawy
`AZURE_CLIENT_ID`	Podmiot usługi — identyfikator klienta
`AZURE_CLIENT_SECRET`	Główny obiekt usługi - tajny sekret klienta (oznacz jako tajne)

2.2 Konfiguracja Pipeline w Azure DevOps

Utwórz potok w usłudze Azure DevOps, który odwołuje się do deploy-using-bulk-api.yml pliku YAML w repozytorium.

Kroki

Przejdź do pozycji Potoki → Potoki → nowy potok.
Wybierz pozycję Azure Repos Git i wybierz repozytorium.
Wybierz Istniejący plik YAML Azure Pipelines.
Zmień pulę zgodnie z istniejącą pulą agentów, np. aby użyć agenta Microsoft-Hosted (opartego na systemie Linux): vmImage: ubuntu-latest
Run
Po zakończeniu potoku danych, bulk-tutorial-test obszar roboczy Fabric zawiera wdrożone elementy.

⚠✔ Porada dotycząca uprawnień: Przy pierwszym uruchomieniu potoku ADO może pojawić się monit o autoryzowanie dostępu do grup zmiennych i środowisk. Administrator ADO może wstępnie autoryzować te opcje w obszarze Potok → Ustawienia.

⚠️ Porada dotycząca produkcji: Ten pipeline przedstawia wdrożenie w środowisku testowym. Wdrożenie produkcyjne może postępować zgodnie z podobnym przepływem z bramą zatwierdzania dodaną po pomyślnej weryfikacji w środowisku testowym.

3. Szczegółowe omówienie kodu: ADO Pipeline YAML

Plik:deploy-using-bulk-api.yml— znajduje się w repozytorium Usługi Azure DevOps.

Poniżej znajduje się pełny pipeline z adnotacjami linie-po-linii.

# ──────────────────────────────────────────────────────────────
# TRIGGER: pipeline start on every push to main branch
# ──────────────────────────────────────────────────────────────
trigger:
  branches:
    include:
    - main


# ─────────────────────────────────────────────────────────────────────────────────────────
# Define the Azure DevOps agent, use of the variable group, and parameters initialization
# ─────────────────────────────────────────────────────────────────────────────────────────
pool:
  vmImage: ubuntu-latest

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


# ────────────────────────────────────────────────────────────────
# Step 1: Checkout & Get Fabric API token using service principal
# ────────────────────────────────────────────────────────────────
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 using service principal'


# ────────────────────────────────────────────────────────────────────
# Step 2: Build REQUEST_BODY and call Bulk Import Item Definitions API 
# ────────────────────────────────────────────────────────────────────
        - script: |
            ## Get workspace ID from workspace name to deploy
            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"

            ## Iterate through each file in the specified folder, read its contents, and encode them in Base64.
            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)

            ## Prepare the request body with base64 encoded items
            REQUEST_BODY=$(jq -n \
              --argjson parts "$PARTS_JSON" \
              '{
                definitionParts: $parts,
                options: {
                  allowPairingByName: false
                }
              }')

            echo "Request body built with $(echo "$PARTS_JSON" | jq length) parts"

            API_URL="https://api.fabric.microsoft.com/v1/workspaces/$WORKSPACE_ID/importItemDefinitions?beta=true"
            echo "Calling Bulk Import Item definition API: $API_URL"

            # Call the Bulk Import API and capture response headers
            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"

            # Extract operation ID from response headers
            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"

            # Set as variable for the next step
            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
          displayName: 'Deploy to $(test_workspace_to_deploy)'


# ────────────────────────────────────────
# Step 3: Wait for Deployment to complete 
# ────────────────────────────────────────
        - 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")

              # Check if importItemDefinitionsDetails exists and is not null
              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'

4. Podsumowanie

W tym samouczku pokazano, jak używać interfejsu API definicji elementu importu zbiorczego jako mechanizmu wdrażania. Pokazano w nim, jak wdrożyć elementy z obszaru roboczego deweloperskiego połączonego z repozytorium Git, wyodrębniając zawartość repozytorium, przekształcając je w wymagane dane wejściowe interfejsu API i wdrażając je w testowym obszarze roboczym usługi Fabric, który nie jest połączony z usługą Git.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-03-18