チュートリアル - 一括インポート項目定義 API を使用した Fabric CI/CD

このチュートリアルでは、 一括インポート項目定義 API を利用して Git フォルダーから項目をデプロイする Azure DevOps パイプラインを使用します。 Git フォルダーには、Git に接続されている 開発 ワークスペースの項目定義が含まれており、パイプラインによって、Git に接続されていない テスト ワークスペースにデプロイされます。

前提条件

• Azure DevOps Azure DevOps パイプラインを構成し、変数グループを作成するための Azure Project とリポジトリ + アクセス許可。
• ファブリック ワークスペース 名: bulk-tutorial-test - デプロイのターゲット ワークスペース
• サービス プリンシパル (SPN) - クライアント シークレットを使用した Entra ID (Azure AD) アプリの登録には、クライアント ID、クライアント シークレット、テナント ID が必要です。
• サービス プリンシパルには、 Fabric ワークスペースに対するbulk-tutorial-testアクセス許可があります
• サービス プリンシパルのファブリック管理者設定 - ファブリック管理者は、ファブリック管理ポータルの [テナント設定] で "サービス プリンシパルで Fabric API を使用できます" を有効にする必要があります

💡 ヒント：Fabric でサービス プリンシパル アクセスを有効にするには、ファブリック管理者が、Fabric 管理ポータルの [テナント設定] で "サービス プリンシパルで Fabric API を使用できます" を有効にする必要があります。

経歴

ビルド環境を用いたGitベースのデプロイでは、Fabricワークスペース間の展開は中央のGitリポジトリから行われます。 Fabricのアイテム定義をコードとして扱い、構造化されたリリースフローを通じて促進しましょう。 すべての環境(Dev、Test、Production)は同じメインブランチに連携し、各ステージは専用のビルドおよびリリースパイプラインを使って独立して展開されます。

パイプラインは、通常、Fabric Git Integration を使用して開発ワークスペースから Fabric 項目定義をエクスポートすることから始まります。 これらの定義は、昇格前の自動チェック、pull request レビュー、ポリシーの適用を通じて、ビルド環境で検証できます。 (このチュートリアルでは説明しません)。

デプロイ中、パイプラインは一括インポート API を呼び出して、承認済みアイテム定義をターゲット ワークスペースに昇格します。 この API は、新しい項目の作成と既存の項目の更新の両方をサポートします。一方、Fabricの組み込みの依存関係処理に依存して、項目が正しい順序でデプロイされるようにします。 これにより、手動による介入なしで、テスト環境と運用環境への一貫性のある反復可能なデプロイが可能になります。

ステップ 1. サンプル リポジトリを準備する

1. zip ファイル bulk-api-demo-zip をローカル コンピューターにダウンロードする
2. サンプル zip には次のものが含まれています。
   • Azure DevOps パイプライン ファイル (deploy-using-bulk-api.yml)
   • Fabric 項目定義ファイルが少ないサンプル ワークスペース (bulk-tutorial-dev)
3. Azure DevOps リポジトリをローカル コンピューターに複製し、このフォルダーにファイルを解凍します。
4. 新しいコンテンツを Azure DevOps リポジトリにプッシュする

ステップ 2. Azure DevOps パイプラインを実行する

2.1 変数グループ: bulkapi-group

この変数グループには、Azure Pipeline が認証するサービス プリンシパルの詳細が格納されます。

作成手順

1. ADO プロジェクト のパイプライン → ライブラリ に移動します。
2. [ + 変数] グループを選択します。
3. 名前を付けてください: bulkapi-group
4. 次の変数を追加します。

2.2 Azure DevOps パイプラインのセットアップ

リポジトリ内の deploy-using-bulk-api.yml YAML ファイルを参照するパイプラインをAzure DevOpsに作成します。

手順

1. [パイプライン] → [パイプライン] → [新しいパイプライン] に移動します。
2. Azure Repos Git を選択し、リポジトリを選択します。
3. [既存の Azure Pipelines YAML ファイル] を選択します。
4. 既存のエージェント プールに従って pool を変更します (たとえば、Microsoft-Hosted エージェント (Linux ベース) の使用を使用する場合: vmImage: ubuntu-latest
5. 実行
6. パイプラインの完了後、bulk-tutorial-test Fabric ワークスペースには、デプロイされた項目が含まれます。

3. コードの詳細: ADO パイプライン YAML

File:deploy-using-bulk-api.yml — Azure DevOps リポジトリにあります。

パイプラインは 3 つのステップで構成され、それぞれが個別の操作を実行します。 注釈を含む各ステップを次に示します。

3.1 パイプラインのトリガーと構成

パイプラインを実行するタイミングを定義し、エージェント プールと変数を構成します。

trigger:
  branches:
    include:
    - main

pool:
  vmImage: ubuntu-latest

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

3.2 手順 1 — Fabric API を使用して認証する

サービス プリンシパルの資格情報を使用して、Microsoft Entra IDからベアラー トークンを取得します。

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'

入力： 変数グループの SPN 資格情報 (AZURE_TENANT_ID、 AZURE_CLIENT_ID、 AZURE_CLIENT_SECRET)

Output:FABRIC_TOKEN — シークレット パイプライン変数として格納されたベアラー トークン。後続の手順で使用されます。

呼び出される API:POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

3.3 手順 2 — ペイロードをビルドし、一括インポート API を呼び出す

この手順では、ワークスペース ID の解決、ローカル ファイルからの要求ペイロードのビルド、一括インポート API の呼び出しという 3 つの操作を実行します。

3.3.1 ワークスペース ID を解決する

Fabric REST API を使用して、表示名でターゲット ワークスペース ID を検索します。

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"

入力:FABRIC_TOKEN、 test_workspace_to_deploy (ワークスペース名)

Output:WORKSPACE_ID — ターゲット ワークスペースの GUID

呼び出される API:GET https://api.fabric.microsoft.com/v1/workspaces

3.3.2 base64 でエンコードされた要求本文をビルドする

ソース フォルダー内の各ファイルを反復処理し、Base64 でコンテンツをエンコードし、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"

入力：bulk-tutorial-dev フォルダー内のローカル ファイル

Output:REQUEST_BODY — すべての項目定義部分を含む JSON ペイロード(base64 エンコード)

キー オプション:allowPairingByName: false — 項目は、表示名ではなく論理 ID ( .platform ファイルから) で照合されます。

3.3.3 一括インポート API を呼び出す

ペイロードを一括インポート API に送信し、ポーリング用の操作 ID をキャプチャします。

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

Output:OPERATION_ID — パイプライン変数として格納される実行時間の長い操作識別子

呼び出される API:POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/bulkImportDefinitions?beta=true

応答処理:

• 200 OK — デプロイが同期的に完了しました (結果は本文になります)
• 202 Accepted — デプロイは非同期です。OPERATION_ID を使用してポーリングしてください。
• 4xx — デプロイに失敗しました。応答本文のエラーの詳細

3.4 手順 3 — デプロイの完了をポーリングして確認する

デプロイが完了し、結果が使用可能になるまで、実行時間の長い操作エンドポイントをポーリングします。

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

入力:FABRIC_TOKEN、 OPERATION_ID

出力： 項目ごとの状態を含むデプロイ結果 JSON

呼び出される API:GET https://api.fabric.microsoft.com/v1/operations/{operationId}/result

結果の構造: 応答には、項目ごとの結果を含む配列である importItemDefinitionsDetails が含まれています。

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

4.まとめ

このチュートリアルでは、 項目定義の一括インポート API をデプロイ メカニズムとして使用する方法について説明しました。 リポジトリのコンテンツを抽出し、必要な API 入力に変換し、Git に接続されていないテスト Fabric ワークスペースにデプロイすることで、Git リポジトリに接続されている開発ワークスペースから項目をデプロイする方法を示しました。

使用される API 操作