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

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

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

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

💡 เคล็ดลับ: เมื่อต้องการเปิดใช้งานการเข้าถึงบริการหลักใน Fabric ผู้ดูแลระบบ Fabric ต้องเปิดใช้งาน "บริการหลักสามารถใช้ Fabric API ได้" ในพอร์ทัลผู้ดูแลระบบ Fabric ภายใต้การตั้งค่าผู้เช่า

ฉากหลัง

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

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

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

ไปป์ไลน์การสร้างและนําออกใช้ที่แนะนําโดยใช้ API คําจํากัดความของรายการนําเข้าจํานวนมาก

ขั้นตอนที่ 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. เพิ่มตัวแปรต่อไปนี้:
ชื่อตัวแปร คำอธิบาย
AZURE_TENANT_ID บริการหลัก - รหัสผู้เช่า
AZURE_CLIENT_ID บริการหลัก - รหัสไคลเอ็นต์
AZURE_CLIENT_SECRET บริการหลัก - ข้อมูลลับของไคลเอ็นต์ (ทําเครื่องหมายเป็นข้อมูลลับ)

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 ประกอบด้วยรายการที่ปรับใช้

Tip

ครั้งแรกที่ไปป์ไลน์ทํางาน ADO อาจแจ้งให้คุณอนุญาตการเข้าถึงกลุ่มตัวแปรและสภาพแวดล้อม ผู้ดูแลระบบ ADO สามารถให้สิทธิ์ล่วงหน้าได้ภายใต้การตั้งค่า→ไปป์ไลน์

Tip

ไปป์ไลน์นี้สาธิตการปรับใช้กับสภาพแวดล้อมการทดสอบ การปรับใช้การผลิตสามารถทําตามโฟลว์ที่คล้ายกัน โดยมีการเพิ่มประตูการอนุมัติหลังจากการตรวจสอบความถูกต้องสําเร็จในสภาพแวดล้อมการทดสอบ

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"
ฉาก Purpose
trigger เรียกใช้ไปป์ไลน์ทุกครั้งที่กดไปยัง main สาขา
pool ใช้ตัวแทน Ubuntu ที่โฮสต์โดย Microsoft
variables.group อ้างอิง bulkapi-group กลุ่มตัวแปรที่มีข้อมูลประจําตัว SPN
test_workspace_to_deploy ชื่อที่แสดงพื้นที่ทํางานเป้าหมาย

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

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

เอาท์พุต: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"
    }
  ]
}
ฟิลด์ คำอธิบาย
itemId รหัสรายการพื้นที่ทํางาน (GUID) ของรายการที่ปรับใช้
itemDisplayName ชื่อที่แสดงของรายการ
itemType ชนิดรายการ Fabric (ตัวอย่างเช่น Report, , SemanticModel) Notebook
itemLogicalId รหัสตรรกะจาก .platform ไฟล์
operationType Create สําหรับรายการ Update ใหม่ สําหรับรายการที่มีอยู่
operationStatus Succeeded หรือ Failed

4. สรุป

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

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

ขั้นตอน API Purpose
รับรอง POST login.microsoftonline.com/.../oauth2/v2.0/token รับโทเค็นผู้ถือโดยใช้ข้อมูลประจําตัว SPN
แก้ไขพื้นที่ทํางาน GET api.fabric.microsoft.com/v1/workspaces ค้นหารหัสพื้นที่ทํางานตามชื่อที่แสดง
ปรับใช้รายการ POST api.fabric.microsoft.com/v1/workspaces/{id}/items/bulkImportDefinitions นําเข้าคําจํากัดความรายการทั้งหมดในการเรียกครั้งเดียว
ผลการสํารวจความคิดเห็น GET api.fabric.microsoft.com/v1/operations/{id}/result รอให้การปรับใช้แบบอะซิงโครนัสเสร็จสมบูรณ์
  • Last updated on