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.

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 Azure DevOps

2.1 Grupa zmiennych: `bulkapi-group`

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

Kroki tworzenia

Przejdź do sekcji Pipelines → Library w projekcie ADO.
Wybierz + grupę 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 Azure DevOps, który odwołuje się do pliku YAML deploy-using-bulk-api.yml 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ń pool zgodnie z istniejącą pulą agentów, na przykład aby użyć agenta Microsoft-Hosted (opartego na systemie Linux): vmImage: ubuntu-latest
Run
Po zakończeniu potoku obszar roboczy bulk-tutorial-test Fabric zawiera wdrożone elementy.

Wskazówka

Przy pierwszym uruchomieniu potoku ADO może wyświetlić monit o autoryzację dostępu do grup zmiennych i środowisk. Administrator ADO może wstępnie autoryzować je w sekcji Potok → Ustawienia.

Wskazówka

Ten proces demonstruje 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

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"

Setting	Purpose
`trigger`	Uruchom potok przy każdym pushu do gałęzi `main`
`pool`	Używanie agenta systemu Ubuntu hostowanego Microsoft
`variables.group`	Odwołaj się do grupy zmiennych `bulkapi-group`, zawierającej poświadczenia SPN
`test_workspace_to_deploy`	Wyświetlana nazwa docelowego obszaru roboczego

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"
    }
  ]
}

Pole	Opis
`itemId`	Identyfikator elementu obszaru roboczego (GUID) wdrożonego elementu
`itemDisplayName`	Nazwa wyświetlana elementu
`itemType`	Typ elementu Fabric (na przykład `Report`, `SemanticModel`, `Notebook`)
`itemLogicalId`	Identyfikator logiczny z `.platform` pliku
`operationType`	`Create` dla nowych elementów, `Update` dla istniejących elementów
`operationStatus`	`Succeeded` lub `Failed`

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

Step	API	Purpose
Authenticate	`POST login.microsoftonline.com/.../oauth2/v2.0/token`	Uzyskiwanie tokenu okaziciela przy użyciu poświadczeń SPN
Rozwiązywanie problemów z obszarem roboczym	`GET api.fabric.microsoft.com/v1/workspaces`	Wyszukaj identyfikator obszaru roboczego według nazwy wyświetlanej
Wdrażanie elementów	`POST api.fabric.microsoft.com/v1/workspaces/{id}/items/bulkImportDefinitions`	Importowanie wszystkich definicji elementów w jednym wywołaniu
Wynik ankiety	`GET api.fabric.microsoft.com/v1/operations/{id}/result`	Poczekaj na ukończenie wdrożenia asynchronicznego

Opinia

Czy ta strona była pomocna?

Last updated on 2026-09-29