บทช่วยสอน - Fabric CI/CD พร้อม API คําจํากัดความรายการนําเข้าจํานวนมาก

ในบทช่วยสอนนี้ คุณใช้ไปป์ไลน์ Azure DevOps ที่ใช้ประโยชน์จาก API ข้อกําหนดรายการนําเข้าจํานวนมาก เพื่อปรับใช้รายการจากโฟลเดอร์ Git โฟลเดอร์ Git ประกอบด้วยข้อกําหนดรายการจากพื้นที่ทํางาน สําหรับนักพัฒนา ที่เชื่อมต่อกับ Git และไปป์ไลน์จะปรับใช้กับพื้นที่ทํางาน ทดสอบ ที่ไม่ได้เชื่อมต่อกับ Git

คุณสามารถแนบแผนการปรับใช้กับคําขอ Bulk Import Item Definitions ได้ตามต้องการ สําหรับรูปแบบคําขอและข้อกําหนด ดูที่ อัตโนมัติการปรับใช้ด้วยแผนการปรับใช้

ข้อกำหนดเบื้องต้น

• Azure DevOps โครงการ Azure และที่เก็บ + สิทธิ์ในการกําหนดค่าไปป์ไลน์ Azure DevOps และสร้างกลุ่มตัวแปร
• ชื่อพื้นที่ทํางานแฟบริค: bulk-tutorial-test - พื้นที่ทํางานเป้าหมายสําหรับการปรับใช้
• บริการหลัก (SPN) - การลงทะเบียนแอป Entra ID (Azure AD) ที่มีข้อมูลลับของไคลเอ็นต์ จําเป็นต้องมีรหัสไคลเอ็นต์ ข้อมูลลับของไคลเอ็นต์ และรหัสผู้เช่า
• บริการหลักมีสิทธิ์ ผู้สนับสนุน สําหรับ bulk-tutorial-test พื้นที่ทํางาน Fabric
• การตั้งค่าผู้ดูแลระบบ Fabric สําหรับ Service Principal - ผู้ดูแลระบบ Fabric ต้องเปิดใช้งาน "Service principals สามารถใช้ Fabric APIs ได้" ภายใต้การตั้งค่าGovern>Configurations> ของ Tenant ในแคตตาล็อก> OneLake

💡 เคล็ดลับ:เพื่อเปิดใช้งานการเข้าถึง Service Principal ใน Fabric ผู้ดูแลระบบ Fabric ต้องเปิดใช้งาน "Service principals สามารถใช้ Fabric APIs ได้" ภายใต้การตั้งค่าTenant ของ Catalog Govern>Configurations> ของ OneLake>

ฉากหลัง

ในการปรับใช้ตาม Git โดยใช้สภาพแวดล้อมการสร้าง การปรับใช้ทั่วทั้งพื้นที่ทํางาน Fabric มาจากที่เก็บ Git ส่วนกลาง ถือว่าข้อกําหนดรายการ Fabric เป็นโค้ดและเลื่อนระดับผ่านโฟลว์การนําออกใช้ที่มีโครงสร้าง สภาพแวดล้อมทั้งหมด - Dev, Test และ Prod - สอดคล้องกับสาขาหลักเดียวกัน ในขณะที่แต่ละขั้นตอนจะถูกปรับใช้อย่างอิสระโดยใช้ไปป์ไลน์การสร้างและรีลีสเฉพาะ

โดยทั่วไปไปป์ไลน์จะเริ่มต้นด้วยการส่งออกข้อกําหนดรายการ Fabric จากพื้นที่ทํางานการพัฒนาโดยใช้การรวม Fabric Git คําจํากัดความเหล่านี้สามารถตรวจสอบได้ในสภาพแวดล้อมการสร้างผ่านการตรวจสอบอัตโนมัติ (ไม่ครอบคลุมในบทช่วยสอนนี้)

ในระหว่างการปรับใช้ ไปป์ไลน์จะเรียกใช้ API การนําเข้าจํานวนมากเพื่อเลื่อนระดับข้อกําหนดรายการที่ได้รับอนุมัติไปยังพื้นที่ทํางานเป้าหมาย API รองรับทั้งการสร้างรายการใหม่และการอัปเดตรายการที่มีอยู่ ในขณะที่อาศัยการจัดการการขึ้นต่อกันในตัวของ Fabric เพื่อให้แน่ใจว่ามีการปรับใช้รายการในลําดับที่ถูกต้อง สิ่งนี้ช่วยให้สามารถปรับใช้ได้อย่างสม่ําเสมอและทําซ้ําได้ในสภาพแวดล้อมการทดสอบและการผลิตโดยไม่ต้องมีการแทรกแซงด้วยตนเอง

ขั้นตอนที่ 1 เตรียมตัวอย่าง repo

1. ดาวน์โหลดไฟล์ zip bulk-api-demo-zip ไปยังเครื่องในเครื่องของคุณ
2. ซิปตัวอย่างประกอบด้วย:
   • ไฟล์ไปป์ไลน์ 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 รับรองความถูกต้องด้วย

ขั้นตอนในการสร้าง

1. ไปที่ไป ป์ไลน์→ไลบรารี ในโปรเจ็กต์ ADO ของคุณ
2. เลือก + กลุ่มตัวแปร
3. ตั้งชื่อ: bulkapi-group
4. เพิ่มตัวแปรต่อไปนี้:

2.2 การตั้งค่าไปป์ไลน์ Azure DevOps

สร้างไปป์ไลน์ใน Azure DevOps ที่อ้างอิงไฟล์ YAML deploy-using-bulk-api.yml ในที่เก็บของคุณ

ขั้นตอน

1. ไปที่ ไปป์ไลน์ → ไปป์ไลน์→ ไปป์ไลน์ใหม่
2. เลือก Azure Repos Git และเลือกที่เก็บของคุณ
3. เลือกไฟล์ YAML ไปป์ไลน์ Azure ที่มีอยู่
4. เปลี่ยน pool ตามพูลเอเจนต์ที่มีอยู่ ตัวอย่างเช่น ใช้เอเจนต์ Microsoft-Hosted (ที่ใช้ Linux): vmImage: ubuntu-latest
5. วิ่ง
6. หลังจากไปป์ไลน์เสร็จสมบูรณ์ พื้นที่ทํางาน bulk-tutorial-test Fabric ประกอบด้วยรายการที่ปรับใช้

3. เจาะลึกโค้ด: ADO Pipeline YAML

File:deploy-using-bulk-api.yml — อยู่ในที่เก็บ Azure DevOps

ไปป์ไลน์ประกอบด้วยสามขั้นตอน โดยแต่ละขั้นตอนจะดําเนินการที่แตกต่างกัน ด้านล่างนี้คือแต่ละขั้นตอนพร้อมคําอธิบายประกอบ

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

เอาท์พุต:FABRIC_TOKEN — โทเค็นผู้ถือที่จัดเก็บเป็นตัวแปรไปป์ไลน์ลับ ซึ่งใช้โดยขั้นตอนต่อๆ ไป

API ที่เรียก:POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

3.3 ขั้นตอนที่ 2 — สร้างเพย์โหลดและเรียกใช้ Bulk Import API

ขั้นตอนนี้ดําเนินการสามอย่าง: แก้ไขรหัสพื้นที่ทํางาน สร้างเพย์โหลดคําขอจากไฟล์ภายในเครื่อง และเรียกใช้ API การนําเข้าจํานวนมาก

3.3.1 แก้ไขรหัสพื้นที่ทํางาน

ค้นหารหัสพื้นที่ทํางานเป้าหมายตามชื่อที่แสดงโดยใช้ Fabric REST API

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 (ชื่อพื้นที่ทํางาน)

เอาท์พุต: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 โฟลเดอร์

เอาท์พุต:REQUEST_BODY — เพย์โหลด JSON ที่มีส่วนคําจํากัดความรายการทั้งหมด, เข้ารหัส base64

ตัวเลือกที่สําคัญ:allowPairingByName: false — รายการจะจับคู่ด้วย ID ตรรกะ (จาก .platform ไฟล์) ไม่ใช่ตามชื่อที่แสดง

3.3.3 เรียกใช้ API การนําเข้าจํานวนมาก

ส่งเพย์โหลดไปยัง API การนําเข้าจํานวนมากและบันทึกรหัสการดําเนินการสําหรับการสํารวจ

API_URL="https://api.fabric.microsoft.com/v1/workspaces/$WORKSPACE_ID/items/bulkImportDefinitions"
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

อินพุต:FABRIC_TOKEN, WORKSPACE_ID, REQUEST_BODY

เอาท์พุต:OPERATION_ID — ตัวระบุการดําเนินการที่ทํางานเป็นเวลานาน ซึ่งจัดเก็บเป็นตัวแปรไปป์ไลน์

API ที่เรียก:POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/bulkImportDefinitions

การจัดการการตอบสนอง:

• 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 คําจํากัดความรายการนําเข้าจํานวนมาก เป็นกลไกการปรับใช้ แสดงวิธีปรับใช้รายการจากพื้นที่ทํางานสําหรับนักพัฒนาที่เชื่อมต่อกับที่เก็บ Git โดยการแยกเนื้อหาที่เก็บ แปลงเป็นอินพุต API ที่จําเป็น และปรับใช้กับพื้นที่ทํางาน Fabric ทดสอบที่ไม่ได้เชื่อมต่อกับ Git

การดําเนินการ API ที่ใช้

เนื้อหาที่เกี่ยวข้อง

• ทําให้การปรับใช้อัตโนมัติด้วยแผนการปรับใช้
• แผนการปฏิบัติงานคืออะไร?