チュートリアル - 一括インポート項目定義 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 ベースのデプロイでは、Microsoft Fabric ワークスペース間のデプロイは中央の Git リポジトリから実行されます。このリポジトリでは、Fabric 項目定義がコードとして扱われ、構造化されたリリースフローを通じて昇格されます。 Dev、Test、Prod のすべての環境は同じメインブランチに配置され、各ステージは専用のビルドおよびリリースパイプラインを使用して個別にデプロイされます。

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

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

一括インポート項目定義 API を使用して、推奨されるビルドパイプラインとリリースパイプライン。

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

zip ファイル bulk-api-demo-zip をローカルコンピューターにダウンロードする
サンプル zip には次のものが含まれています。

Azure DevOps パイプラインファイル (deploy-using-bulk-api.yml)
Fabric 項目定義ファイルが少ないサンプルワークスペース (bulk-tutorial-dev)

Azure DevOps リポジトリをローカルコンピューターに複製し、このフォルダーにファイルを解凍します。
新しいコンテンツを Azure DevOps リポジトリにプッシュする

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

2.1 変数グループ: `bulkapi-group`

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

作成手順

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

変数名	説明
`AZURE_TENANT_ID`	サービスプリンシパル - テナント ID
`AZURE_CLIENT_ID`	サービスプリンシパル - クライアント ID
`AZURE_CLIENT_SECRET`	サービスプリンシパル - クライアントシークレット (シークレットとしてマーク)

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

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

手順

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

⚠️ アクセス許可のヒント: パイプラインを初めて実行する場合、ADO は変数グループと環境へのアクセスを承認するように求めるメッセージを表示する場合があります。 ADO 管理者は、[パイプラインの→設定] でこれらを事前に承認できます。

⚠️ 運用のヒント: このパイプラインは、テスト環境へのデプロイを示します。運用環境のデプロイも同様のフローに従い、テスト環境での検証が成功した後に承認ゲートが追加されます。

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

ファイル:deploy-using-bulk-api.yml- Azure DevOps リポジトリにあります。

行ごとの注釈を含む完全なパイプラインを次に示します。

# ──────────────────────────────────────────────────────────────
# TRIGGER: pipeline start on every push to main branch
# ──────────────────────────────────────────────────────────────
trigger:
  branches:
    include:
    - main


# ─────────────────────────────────────────────────────────────────────────────────────────
# Define the Azure DevOps agent, use of the variable group, and parameters initialization
# ─────────────────────────────────────────────────────────────────────────────────────────
pool:
  vmImage: ubuntu-latest

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


# ────────────────────────────────────────────────────────────────
# Step 1: Checkout & Get Fabric API token using service principal
# ────────────────────────────────────────────────────────────────
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 using service principal'


# ────────────────────────────────────────────────────────────────────
# Step 2: Build REQUEST_BODY and call Bulk Import Item Definitions API 
# ────────────────────────────────────────────────────────────────────
        - script: |
            ## Get workspace ID from workspace name to deploy
            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"

            ## Iterate through each file in the specified folder, read its contents, and encode them in Base64.
            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)

            ## Prepare the request body with base64 encoded items
            REQUEST_BODY=$(jq -n \
              --argjson parts "$PARTS_JSON" \
              '{
                definitionParts: $parts,
                options: {
                  allowPairingByName: false
                }
              }')

            echo "Request body built with $(echo "$PARTS_JSON" | jq length) parts"

            API_URL="https://api.fabric.microsoft.com/v1/workspaces/$WORKSPACE_ID/importItemDefinitions?beta=true"
            echo "Calling Bulk Import Item definition API: $API_URL"

            # Call the Bulk Import API and capture response headers
            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"

            # Extract operation ID from response headers
            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"

            # Set as variable for the next step
            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
          displayName: 'Deploy to $(test_workspace_to_deploy)'


# ────────────────────────────────────────
# Step 3: Wait for Deployment to complete 
# ────────────────────────────────────────
        - 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")

              # Check if importItemDefinitionsDetails exists and is not null
              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'

4.まとめ

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-18