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 dev, który jest połączony z Git, a potok wdraża je do obszaru roboczego test, który nie jest połączony z Git.

Możesz opcjonalnie dołączyć plan wdrożenia do żądania Bulk Import Item Definitions. Informacje o formacie żądania i wymaganiach można znaleźć w artykule Automatyzowanie wdrożeń za pomocą planu wdrożenia.

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 administratora Fabric dla jednostki usługi — administrator Fabric musi włączyć opcję „Jednostki usługi mogą używać interfejsów API usługi Fabric” w obszarze katalogu OneLake>>>.

💡 Wskazówka: Aby włączyć dostęp jednostki usługi w Fabric, administrator Fabric musi włączyć opcję "Service principals can use Fabric APIs" w obszarze OneLake catalog>>>.

Kontekst

W przypadku wdrażania opartego na narzędziu Git w środowisku kompilacji wdrożenia w obszarach roboczych Fabric pochodzą z centralnego repozytorium Git. Traktuj definicje elementów Fabric jak kod i przenoś je przez ustrukturyzowany proces wydawniczy. Wszystkie środowiska – deweloperskie, testowe i produkcyjne – są powiązane z tą samą główną gałęzią, podczas gdy każdy etap jest wdrażany niezależnie za pomocą dedykowanych potoków budowania i wydawania.

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 aktualizowanie istniejących, a jednocześnie polega na wbudowanej obsłudze zależności Fabric, aby upewnić się, że elementy są wdrażane w odpowiedniej kolejności. Umożliwia to spójne, powtarzalne wdrożenia w środowiskach testowych i produkcyjnych bez ręcznej interwencji.

Krok 1. Przygotowywanie przykładowego repozytorium

1. Pobierz plik zip bulk-api-demo-zip na komputer lokalny
2. 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)
3. Sklonuj repozytorium usługi Azure DevOps na komputer lokalny i rozpakuj plik do tego folderu.
4. Wypychanie nowej zawartości do repozytorium usługi Azure DevOps

Krok 2. Uruchamianie potoku Azure DevOps

2.1 Grupa zmiennych: bulkapi-group

Ta grupa zmiennych przechowuje szczegóły jednostki usługi uwierzytelniane przez potok Azure.

Kroki tworzenia

1. Przejdź do sekcji Pipelines → Library w projekcie ADO.
2. Wybierz + grupę zmiennych.
3. Nadaj mu nazwę: bulkapi-group
4. Dodaj następujące zmienne:

2.2 Konfiguracja Pipeline w Azure DevOps

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

Kroki

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

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

File:deploy-using-bulk-api.yml — znajdujący się w repozytorium Azure DevOps.

Potok przetwarzania składa się z trzech kroków, z których każdy wykonuje odrębną operację. Poniżej znajduje się każdy krok z adnotacjami.

3.1 Wyzwalacz i konfiguracja potoku

Określ, kiedy potok ma być uruchamiany, i skonfiguruj pulę agentów oraz zmienne.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Krok 1 — Uwierzytelnianie przy użyciu interfejsu API Fabric

Uzyskaj token elementu nośnego z Microsoft Entra ID przy użyciu poświadczeń jednostki usługi.

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'

Wejście: Poświadczenia SPN z grupy zmiennych (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Wyjście:FABRIC_TOKEN — token uwierzytelniający typu Bearer przechowywany jako tajna zmienna potoku, wykorzystywany w kolejnych krokach.

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

3.3 Krok 2 — Zbudowanie ładunku danych i wywołanie interfejsu API importu zbiorczego

Ten krok wykonuje trzy operacje: ustalić identyfikator obszaru roboczego, zbudować treść żądania na podstawie plików lokalnych i wywołać interfejs Bulk Import API.

3.3.1 Rozwiązywanie identyfikatora obszaru roboczego

Wyszukaj identyfikator docelowego obszaru roboczego według nazwy wyświetlanej przy użyciu interfejsu 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"

Input:FABRIC_TOKEN, test_workspace_to_deploy (nazwa obszaru roboczego)

Wyjście:WORKSPACE_ID — identyfikator GUID docelowego obszaru roboczego

Interfejs API o nazwie:GET https://api.fabric.microsoft.com/v1/workspaces

3.3.2 Kompilowanie treści żądania zakodowanego w formacie base64

Przejrzyj każdy plik w folderze źródłowym, zakoduj jego zawartość w formacie Base64 i zbuduj ciało żądania 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"

Wejście: Pliki lokalne w bulk-tutorial-dev folderze

Wyjście:REQUEST_BODY — Ładunek JSON zawierający wszystkie części definicji elementu, zakodowany w formacie Base64

Opcja klucza:allowPairingByName: false — elementy są dopasowywane według identyfikatora logicznego (z .platform plików), a nie według nazwy wyświetlanej.

3.3.3 Wywołaj interfejs API importu zbiorczego

Wyślij dane żądania do interfejsu Bulk Import API i zapisz identyfikator operacji na potrzeby odpytywania.

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

Dane wejściowe:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

Wyjście:OPERATION_ID — długotrwały identyfikator operacji przechowywany jako zmienna potoku

Interfejs API o nazwie:POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/bulkImportDefinitions

Obsługa odpowiedzi:

• 200 OK — wdrożenie zostało ukończone synchronicznie (wynik w treści)
• 202 Accepted — wdrożenie jest asynchroniczne; odpytywanie za pomocą OPERATION_ID
• 4xx — wdrożenie nie powiodło się; szczegóły błędu w treści odpowiedzi

3.4 Krok 3 — sprawdzanie, czy wdrożenie zostało ukończone

Sonduj długotrwały punkt końcowy operacji, dopóki wdrożenie nie zostanie ukończone, a wynik będzie dostępny.

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

Dane wejściowe:FABRIC_TOKEN, OPERATION_ID

Wyjście: Wynik wdrożenia JSON zawierający stan poszczególnych elementów

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

Struktura wyników: Odpowiedź zawiera importItemDefinitionsDetails — tablicę z wynikami poszczególnych elementów:

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

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 ją w wymagane dane wejściowe interfejsu API i wdrażając je w testowym obszarze roboczym Fabric, który nie jest połączony z usługą Git.

Używane operacje interfejsu API

Treści powiązane

• Automatyzuj wdrożenia dzięki planowi wdrożenia
• Czym jest plan rozmieszczenia?