Tutorial - Fabric CI/CD com API de Definições de Itens de Importação em Lote

Neste tutorial, utilizas um pipeline Azure DevOps que aproveita a API de definição de itens de importação em massa para implementar itens a partir de uma pasta Git. A pasta Git contém definições de itens de um espaço de trabalho de desenvolvimento ligado ao Git, e o pipeline implementa-as num espaço de trabalho de teste que não está ligado ao Git.

Pré-requisitos

• Azure DevOps Azure Project e repositório + permissões para configurar o pipeline do Azure DevOps e criar grupos de variáveis.
• Nome do espaço de trabalho Fabric: bulk-tutorial-test - espaço de trabalho alvo para a implementação
• Service Principal (SPN) - Um registo de aplicação Entra ID (Azure AD) com um segredo do cliente, deve ter o id do cliente, o segredo do cliente, e o id do inquilino.
• O principal do serviço tem permissão de Contribuidor para o bulk-tutorial-test espaço de trabalho Fabric
• Definição de Administrador de Fabric para Principal de Serviço - Um Administrador de Fabric deve ativar "Os principals de serviço podem usar Fabric APIs" no Portal de Administrador de Fabric, em Definições de Tenant

💡 Dica: Para permitir o acesso do Service Principal no Fabric, um Administrador do Fabric deve ativar "Service principals podem usar APIs do Fabric" no Portal do Administrador do Fabric, nas Definições de Inquilino.

Contexto geral

Na implementação baseada em Git usando um ambiente de compilação, as implementações em espaços de trabalho Fabric vêm de um repositório Git central. Trate as definições de itens Fabric como código e promova-as através de um fluxo estruturado de lançamento. Todos os ambientes - Dev, Test e Prod - alinham-se com o mesmo ramo principal, enquanto cada estágio é implementado de forma independente através de pipelines dedicados de build e release.

Os pipelines normalmente começam por exportar definições de itens do Fabric a partir de um espaço de trabalho de desenvolvimento usando a integração do Fabric com o Git. Estas definições podem depois ser validadas num ambiente de compilação através de verificações automáticas, revisões de pull requests e aplicação de políticas antes da promoção. (Não abordado neste tutorial).

Durante a implementação, o pipeline invoca a API de Importação em Massa para promover definições de itens aprovadas no espaço de trabalho alvo. A API suporta tanto a criação de novos itens como a atualização dos existentes, dependendo do tratamento de dependências incorporado do Fabric para garantir que os itens são implementados na ordem correta. Isto permite implementações consistentes e repetíveis em ambientes de teste e produção sem intervenção manual.

Passo 1. Prepara um repositorio de exemplo

1. Descarregue o ficheiro zip bulk-api-demo-zip para a sua máquina local
2. O ficheiro ZIP de exemplo contém:
   • Ficheiro de pipeline do Azure DevOps (deploy-using-bulk-api.yml)
   • Espaço de trabalho de exemplo com poucos ficheiros de definição de itens Fabric (bulk-tutorial-dev)
3. Clone o seu repositório Azure DevOps para a sua máquina local e descompacte o ficheiro nesta pasta.
4. Empurrar o novo conteúdo para o repositório Azure DevOps

Passo 2. Executar pipeline do Azure DevOps

2.1 Grupo de variáveis: bulkapi-group

Este grupo de variáveis armazena os detalhes do principal do serviço com os quais o Azure Pipeline autentica.

Passos para Criar

1. Navegue até Pipeline → Biblioteca no seu projeto ADO.
2. Selecione + Grupo de variáveis.
3. Nomeia: bulkapi-group
4. Adicione as seguintes variáveis:

2.2 Azure DevOps Pipeline setup

Cria um pipeline em Azure DevOps que faça referência ao ficheiro YAML deploy-using-bulk-api.yml no teu repositório.

Passos

1. Navegue para Pipelines → Pipelines → Novo pipeline.
2. Escolhe o Repositórios do Azure Git e seleciona o teu repositório.
3. Escolha Existing Azure Pipelines YAML file.
4. Altere o pool de acordo com o conjunto de agentes existente; por exemplo, para utilizar o agente alojado pela Microsoft (baseado em Linux), utilize: vmImage: ubuntu-latest
5. Executar
6. Após a conclusão do pipeline, o espaço de trabalho do bulk-tutorial-test Fabric contém os itens implementados.

3. Análise aprofundada do código: ADO Pipeline YAML

Ficheiro:deploy-using-bulk-api.yml — localizado no repositório Azure DevOps.

O oleoduto consiste em três etapas, cada uma realizando uma operação distinta. Abaixo está cada passo com anotações.

3.1 Acionamento e configuração do pipeline

Define quando o pipeline corre e configura o pool de agentes e as variáveis.

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 Passo 1 — Autenticar com API Fabric

Adquira um token portador do Microsoft Entra ID usando credenciais de principal de serviço.

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'

Entrada: Credenciais SPN do grupo de variáveis (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Saída:FABRIC_TOKEN — um token bearer armazenado como variável secreta do pipeline, utilizado nas etapas seguintes.

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

3.3 Passo 2 — Construir o payload e chamar a API de Importação em Massa

Esta etapa executa três operações: resolver o ID do espaço de trabalho, construir o payload de pedido a partir de ficheiros locais e chamar a API de Importação em Massa.

3.3.1 Resolver o ID do espaço de trabalho

Procura o ID do espaço de trabalho alvo pelo nome de exibição usando a API Fabric REST.

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 (nome do espaço de trabalho)

Saída:WORKSPACE_ID — o GUID do espaço de trabalho alvo

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

3.3.2 Criar o corpo do pedido codificado em base64

Percorrer cada ficheiro da pasta de origem, codificar o conteúdo em Base64 e construir o corpo do pedido em 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"

Entrada: Ficheiros locais numa bulk-tutorial-dev pasta

Saída:REQUEST_BODY — Conteúdo JSON contendo todas as partes da definição do item, codificado em Base64

Opção chave:allowPairingByName: false — os itens são correspondidos por ID lógico (a partir de .platform ficheiros), e não por nome de visualização.

3.3.3 Invocar a API de Importação em lote

Envie a carga útil para a API de Importação em Massa e registe o ID da operação para consulta periódica.

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

Input:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

Saída:OPERATION_ID — o identificador da operação de execução prolongada, armazenado como variável do pipeline

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

Tratamento da resposta:

• 200 OK — implementação concluída sincronamente (resultado no corpo)
• 202 Accepted — a implementação é assíncrona; Sondagem usando o OPERATION_ID
• 4xx — implementação falhada; Detalhes do erro no corpo da resposta

3.4 Passo 3 — Inquérito para conclusão do desdobramento

Consulte o endpoint da operação de longa duração até que a implementação seja concluída e o resultado esteja disponível.

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

Input:FABRIC_TOKEN, OPERATION_ID

Saída: Resultado de implementação JSON contendo o estado por item

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

Estrutura do resultado: A resposta contém importItemDefinitionsDetails — um array com resultados por item:

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

4. Resumo

Este tutorial demonstrou como usar a API de Definição de Itens de Importação em Massa como mecanismo de implementação. Mostrou como implementar itens de um espaço de trabalho de desenvolvimento ligado a um repositório Git, extraindo o conteúdo do repositório, transformando-o na entrada de API necessária e implementando-o num espaço de trabalho Fabric de teste que não está ligado ao Git.

Operações API utilizadas