Opetus - Fabric CI/CD ja Bulk Import Item Definitions API

Tässä opastuaalissa käytät Azure DevOps -putkistoa, joka hyödyntää Bulk import -tuotemäärittelyrajapintaa Git-kansion kohteiden käyttöönotossa. Git-kansio sisältää kohdemäärittelyt kehittäjätyötilasta, joka on yhdistetty Gitiin, ja putkisto ottaa ne käyttöön testityötilaan, joka ei ole yhteydessä Gitiin.

Edellytykset

• Azure DevOps Azure Project ja repository + oikeudet Azure DevOps -pipelinen konfigurointiin ja muuttujaryhmien luomiseen.
• Fabric-työtilan nimi: bulk-tutorial-test - kohdetyötila käyttöönottoa varten
• Service Principal (SPN) – Entra ID -tunnus (Azure AD) -sovelluksen rekisteröinti, jossa on asiakassalaisuus, täytyy sisältää asiakas-ID, asiakassalaisuus ja tenant-ID.
• Palvelupäähenkilöllä on Contributor-oikeusbulk-tutorial-test Fabric-työtilalle
• Fabric Admin -asetus Service Principalille – Fabric-ylläpitäjän on otettava käyttöön "Service Principals can use Fabric APIs" Fabric Admin Portalissa Tenant Settings -osiossa

💡 Vinkki: Jotta Service Principal -pääsy voidaan ottaa käyttöön Fabricissa, Fabric-ylläpitäjän on otettava käyttöön "Service Principals can use Fabric-rajapintoja " Fabric Admin Portalissa Tenant Settings -kohdassa.

Tausta

Git-pohjaisessa käyttöönotossa, jossa käytetään build-ympäristöä, Fabric-työtilojen laajuiset käyttöönotot tulevat keskitetystä Git-repositoriosta. Käsittele Fabric-tuotemäärittelyjä koodina ja edistä niitä rakenteellisen julkaisuprosessin kautta. Kaikki ympäristöt – Dev, Test ja Prod – kohdistuvat samaan päähaaraan, kun taas jokainen vaihe otetaan käyttöön itsenäisesti omistettujen rakennus- ja julkaisuputkien avulla.

Putket alkavat tyypillisesti viemällä Fabric-kohdemäärittelyjä kehitystyötilasta Fabric Git -integraation avulla. Nämä määritelmät voidaan sitten vahvistaa rakennusympäristössä automatisoiduilla tarkistuksilla, pull request -tarkistuksilla ja politiikan valvonnalla ennen ylennystä. (Tätä ei käsitelty tässä ohjeessa).

Käyttöönoton aikana putkisto käynnistää Bulk Import API:n edistääkseen hyväksyttyjä kohteiden määrittelyjä kohdetyötilaan. API tukee sekä uusien kohteiden luomista että olemassa olevien päivittämistä, samalla kun se luottaa Fabric:n sisäänrakennettuun riippuvuushallintaan varmistaakseen, että kohteet otetaan käyttöön oikeassa järjestyksessä. Tämä mahdollistaa johdonmukaiset, toistettavat käyttöönotot testaus- ja tuotantoympäristöihin ilman manuaalista puuttumista.

Vaihe 1. Valmistele näytevarasto

1. Lataa zip-tiedosto bulk-api-demo-zip paikalliselle koneellesi
2. Näytezip sisältää:
   • Azure DevOps putkistotiedosto (deploy-using-bulk-api.yml)
   • Esimerkkityötila, jossa on muutama Fabric-elementti, määritelmä, tiedosto (bulk-tutorial-dev)
3. Kloonaa Azure DevOps -varastosi paikalliseen koneeseesi ja pakkaa tiedosto tähän kansioon.
4. Push the new content to Azure DevOps repository

Vaihe 2. Run Azure DevOps pipeline

2.1 Muuttujaryhmä: bulkapi-group

Tämä muuttujaryhmä tallentaa palvelupään tiedot, joilla Azure-putki autentikoituu.

Luomisen vaiheet

1. Siirry ADO-projektisi Pipelines → Libraryyn .
2. Valitse + Muuttujaryhmä -.
3. Nimeä se: bulkapi-group
4. Lisää seuraavat muuttujat:

2.2 Azure DevOps Pipeline setup

Luo putki Azure DevOps:ssa, joka viittaa deploy-using-bulk-api.yml YAML-tiedostoon repositasi.

Vaiheet

1. Siirry kohtaan Pipelines → Pipelines → New pipeline.
2. Valitse Azure Repos Git ja valitse oma repositoriosi.
3. Valitse Existing Azure Pipelines YAML -tiedosto.
4. Muuta pool olemassa olevan agenttipoolin mukaan, esimerkiksi käyttääksesi Microsoft-Hosted agenttia (Linux-pohjainen) käyttäen: vmImage: ubuntu-latest
5. Juosta
6. Putkiston valmistuttua bulk-tutorial-test Fabric-työtila sisältää käyttöönotetut kohteet.

3. Koodin syväsyvällinen sukellus: ADO Pipeline YAML

Tiedosto:deploy-using-bulk-api.yml — sijaitsee Azure DevOps-repositoriossa.

Putki koostuu kolmesta vaiheesta, joista kukin suorittaa oman operaationsa. Alla on jokainen vaihe merkintöineen.

3.1 Putkiston laukaisu ja konfiguraatio

Määrittele, milloin putki suoritetaan, ja konfiguroi agenttipooli ja muuttujat.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Vaihe 1 — Tunnista Fabric API:n avulla

Hanki kantajatoken Microsoft Entra ID:stä käyttäen palvelupäähenkilön tunnuksia.

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'

Syöte: SPN-tunnistetiedot muuttujaryhmästä (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Tulostus:FABRIC_TOKEN — kantajatoken, joka on tallennettu salaisena putkimuuttujana, jota käytetään myöhemmissä vaiheissa.

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

3.3 Vaihe 2 — Rakenna payload ja kutsu Bulk Import API

Tämä vaihe suorittaa kolme toimintoa: ratkaisee työtilan ID:n, rakentaa pyyntökuorman paikallisista tiedostoista ja kutsuu Bulk Import API:ta.

3.3.1 Ratkaise työtilan ID

Etsi kohdetyötilan ID näyttönimen perusteella Fabric REST API:n avulla.

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"

Syöte:FABRIC_TOKEN, test_workspace_to_deploy (työtilan nimi)

Tulostus:WORKSPACE_ID — kohdetyötilan GUID

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

3.3.2 Rakenna base64-koodattu pyyntörunko

Käy läpi jokainen tiedosto lähdekansiossa, koodaa sisältö Base64:ään ja kokoa JSON-pyyntörunko.

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"

Syöte: Paikalliset tiedostot kansiossa bulk-tutorial-dev

Tulostus:REQUEST_BODY — JSON-hyötykuorma, joka sisältää kaikki alkiomäärittelyosat, base64-koodattu

Keskeinen vaihtoehto:allowPairingByName: false — kohteet yhdistetään loogiseen tunnisteeseen (tiedostoista .platform ), ei näyttönimellä.

3.3.3 Kutsu Bulk Import API:ta

Lähetä hyötykuorma Bulk Import API:lle ja kaappaa operaatio-ID kyselyä varten.

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

Syöte:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

Tulostus:OPERATION_ID — pitkäaikainen operaatiotunniste, tallennettuna putkimuuttujana

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

Vasteiden käsittely:

• 200 OK — käyttöönotto suoritettu synkronisesti (tulos rungossa)
• 202 Accepted — käyttöönotto on asynkronista; Kysely käyttäen OPERATION_ID
• 4xx — käyttöönotto epäonnistui; Virhetiedot vastauselimessä

3.4 Vaihe 3 — Kysely käyttöönoton suorittamiseksi

Kysy pitkäaikaisesta käyttöpäätepisteestä, kunnes käyttöönotto on valmis ja tulos on saatavilla.

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

Syöte:FABRIC_TOKEN, OPERATION_ID

Tulostus: Käyttöönottotulos JSON, joka sisältää kohtakohtaisen tilan

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

Tulosrakenne: Vastaus sisältää importItemDefinitionsDetails — taulukon, jossa on tulokset per kohde:

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

4. Yhteenveto

Tämä opetus osoitti, miten Bulk Import Item Definition API :ta käytetään käyttöönottomekanismina. Se näytti, miten kehittäjätyötilan alkio otetaan käyttöön Git-repositorioon kytkettynä purkamalla repositorion sisältö, muuttamalla se vaadituksi API-syötteeksi ja sijoittamalla sen testi-Fabric-työtilaan, joka ei ole yhteydessä Git-järjestelmään.

API-toiminnot