Tutorial – CI/CD do Fabric com a API de Definições de Itens para Importação em Lote

Neste tutorial, você usará um pipeline do Azure DevOps que aproveita a API de definição de itens para importação em massa para implantar itens de uma pasta Git. A pasta Git contém definições de item de um workspace de desenvolvimento conectado ao Git e o pipeline as implanta em um workspace de teste que não está conectado ao Git.

Pré-requisitos

• Azure DevOps Projeto do Azure e repositório + permissões para configurar o pipeline do Azure DevOps e criar grupos de variáveis.
• Nome do workspace do Fabric : bulk-tutorial-test – workspace de destino para a implantação
• Entidade de Serviço (SPN) – Um Registro de Aplicativo do Entra ID (Azure AD) com um segredo do cliente deve ter a ID do cliente, o segredo do cliente e a ID do locatário.
• A entidade de serviço tem permissão de Colaborador para o bulk-tutorial-test Fabric Workspace
• Configuração do Administrador do Fabric para Entidade de Serviço – Um Administrador do Fabric deve habilitar "As entidades de serviço podem usar APIs do Fabric" no Portal de Administração do Fabric em Configurações de Locatário

💡 Ponta: Para habilitar o acesso da Entidade de Serviço no Fabric, um administrador do Fabric deve habilitar "As entidades de serviço podem usar APIs do Fabric" no Portal de Administração do Fabric em Configurações de Locatário.

Tela de fundo

Em implantações baseadas em Git usando um ambiente de compilação, as implantações entre os workspaces Fabric vêm de um repositório Git central. Trate as definições de itens Fabric como código e promova-as por meio de um fluxo estruturado de lançamento. Todos os ambientes - Dev, Test e Prod - alinham-se ao mesmo ramo principal, enquanto cada estágio é implantado de forma independente usando pipelines dedicados de build e release.

Os pipelines normalmente começam com a exportação das definições de itens do Fabric a partir de um ambiente de trabalho de desenvolvimento, usando o Fabric Git Integration. Essas definições podem ser validadas em um ambiente de build por meio de verificações automatizadas, revisões de solicitação de pull e imposição de políticas antes da promoção. (Não abordado neste tutorial).

Durante a implantação, o pipeline invoca a API de Importação em Massa para promover definições de itens aprovados no workspace de destino. A API dá suporte à criação de novos itens e à atualização dos existentes em vigor, ao mesmo tempo em que depende do tratamento de dependência interno do Fabric para garantir que os itens sejam implantados na ordem correta. Isso permite implantações consistentes e repetíveis em ambientes de teste e produção sem intervenção manual.

Etapa 1. Preparar um repositório de exemplo

1. Baixe o arquivo zip bulk-api-demo-zip para seu computador local
2. O zip de exemplo contém:
   • Arquivo de pipeline do Azure DevOps (deploy-using-bulk-api.yml)
   • Workspace de exemplo com poucos arquivos de definições de itens do Fabric (bulk-tutorial-dev)
3. Clone o repositório do Azure DevOps no computador local e descompacte o arquivo para essa pasta.
4. Enviar o novo conteúdo por push para o repositório do Azure DevOps

Etapa 2. Executar Azure DevOps pipeline

2.1 Grupo de Variáveis: bulkapi-group

Esse grupo de variáveis armazena as informações da service principal usadas pelo Azure Pipeline para se autenticar.

Etapas para criar

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

2.2 Configuração do Pipeline do Azure DevOps

Crie um pipeline em Azure DevOps que referencie o arquivo YAML deploy-using-bulk-api.yml em seu repositório.

Steps

1. Navegue até Pipelines → Pipelines → Novo Pipeline.
2. Escolha Azure Repos Git e selecione seu repositório.
3. Escolha o arquivo YAML do Azure Pipelines existente.
4. Altere o pool conforme o pool de agentes existente; por exemplo, para usar o agente Microsoft-Hosted (baseado no Linux), use: vmImage: ubuntu-latest
5. Executar
6. Após a conclusão do pipeline, o espaço de trabalho do Fabric bulk-tutorial-test contém os itens implantados.

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

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

O pipeline consiste em três etapas, cada uma executando uma operação distinta. Abaixo está cada etapa com anotações.

3.1 Gatilho e configuração de pipeline

Defina quando o pipeline é executado e configure 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 Etapa 1 – Autenticar com Fabric API

Adquira um token de portador de Microsoft Entra ID usando credenciais de entidade 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 de SPN do grupo de variáveis (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Saída:FABRIC_TOKEN — um token de portador armazenado como uma variável de pipeline secreta, usada pelas etapas subsequentes.

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

3.3 Etapa 2 — Montar o payload e chamar a API de importação em massa

Esta etapa executa três operações: resolver o ID do workspace, montar o corpo da solicitação a partir de arquivos locais e chamar a API de Importação em Massa.

3.3.1 Determinar o ID do espaço de trabalho

Localize o ID do workspace de destino pelo nome de exibição usando a API REST do 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"

Entrada:FABRIC_TOKEN, test_workspace_to_deploy (nome do espaço de trabalho)

Saída:WORKSPACE_ID — o GUID do workspace de destino

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

3.3.2 Compilar corpo da solicitação codificada em base64

Percorrer cada arquivo na pasta de origem, codificar o conteúdo em Base64 e montar o corpo da solicitação 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: Arquivos locais na bulk-tutorial-dev pasta

Saída:REQUEST_BODY — Conteúdo JSON que contém todas as partes de definição de item, codificadas em base64

Opção principal:allowPairingByName: false — os itens são associados pelo ID lógico (dos arquivos .platform), não pelo nome de exibição.

3.3.3 Invocar a API de Importação em Massa

Envie a carga para a API de Importação em Massa e capture o identificador da operação para consulta.

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

Entrada:FABRIC_TOKEN, , WORKSPACE_IDREQUEST_BODY

Saída:OPERATION_ID — o identificador da operação de longa duração, armazenado como uma variável de pipeline

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

Tratamento de resposta:

• 200 OK — implantação concluída de forma síncrona (resultado no corpo)
• 202 Accepted — a implantação é assíncrona; sondagem usando o OPERATION_ID
• 4xx — falha na implantação; detalhes do erro no corpo da resposta

3.4 Etapa 3 – Sondagem para conclusão da implantação

Consulte o endpoint da operação de longa duração até que a implantaçã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'

Entrada:FABRIC_TOKEN, OPERATION_ID

Saída: JSON com o resultado da implantação, contendo o status de cada item

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

Estrutura de resultados: A resposta contém importItemDefinitionsDetails uma matriz 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 Item de Importação em Massa como um mecanismo de implantação. Ele mostrou como implantar itens de um workspace de desenvolvimento conectado a um repositório Git extraindo o conteúdo do repositório, transformando-o na entrada de API necessária e implantando-o em um workspace de Fabric de teste que não está conectado ao Git.

Operações de API usadas