ตั้งค่าส่วนท้ายของปริมาณงาน Microsoft Fabric โดยใช้สเปค OpenAPI (Swagger)

2025-07-02

ส่วนท้ายของปริมาณงาน Microsoft Fabric คือบริการที่ใช้สัญญา Fabric API ซึ่งช่วยให้ปริมาณงานแบบกําหนดเองสามารถรวมเข้ากับแพลตฟอร์ม Microsoft Fabric ได้อย่างราบรื่น Back End นี้จะจัดการการดําเนินการวงจรชีวิตสําหรับรายการปริมาณงานของคุณ รวมถึงการสร้าง การค้นคืน การอัปเดต และการลบ

บทความนี้จะแนะนําคุณในการสร้างปริมาณงาน Fabric ที่สิ้นสุดโดยตรงจากข้อกําหนด OpenAPI (Swagger) อย่างรวดเร็ว วิธีการ API-first ช่วยให้คุณสามารถสร้างต้นแบบและตรวจสอบตรรกะ Back-end ได้อย่างรวดเร็วได้อย่างอิสระก่อนที่จะรวมเข้ากับสภาพแวดล้อมการพัฒนา Microsoft Fabric ที่สมบูรณ์ หลักการที่แสดงในที่นี้ใช้ได้กว้างขวาง โดยไม่คํานึงถึงเครื่องมือหรือภาษาเฉพาะที่คุณเลือก

ในตอนท้ายของบทความนี้ คุณจะสามารถ:

สร้างการสิ้นสุดปริมาณงาน Fabric ที่ยึดตามไฟล์ Swagger ที่รวมอยู่ในตัวอย่าง
ทําความเข้าใจกับโครงสร้างพื้นฐานและส่วนประกอบของส่วนหลังของปริมาณงาน Fabric
เรียกใช้และทดสอบ Back end ที่คุณสร้างขึ้นภายในเครื่องโดยใช้ Python และ FastAPI

ในบทความนี้ คุณจะใช้การดําเนินการหลักต่อไปนี้จากวงจรชีวิตของหน่วยข้อมูล การดําเนินการเหล่านี้สอดคล้องกับจุดสิ้นสุดที่กําหนดไว้ในไฟล์ Fabric API Swagger

สร้างรายการ: เริ่มต้นรายการปริมาณงานใหม่
รับส่วนข้อมูลรายการ: เรียกใช้การกําหนดค่ารายการ
อัปเดตรายการ: ปรับเปลี่ยนรายการที่มีอยู่
ลบรายการ: เอารายการออกจากพื้นที่ทํางาน

บทความนี้แสดงให้เห็นถึงกระบวนการโดยเฉพาะโดยใช้ Python และ FastAPI ด้วยเครื่องมือตัวสร้าง OpenAPI อย่างไรก็ตาม ตัวสร้าง OpenAPI เองสนับสนุนภาษาและเฟรมเวิร์กการเขียนโปรแกรมมากมาย คุณมีอิสระที่จะเลือกเครื่องมือสร้างโค้ดที่เข้ากันได้กับ OpenAPI หรือวิธีการที่เหมาะสมกับความเชี่ยวชาญและโครงการของทีมของคุณที่ต้องการสร้างโครงกระดูกหลังบ้านของคุณ

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

ก่อนที่คุณจะเริ่มขั้นตอนในบทความนี้ ตรวจสอบให้แน่ใจว่าคุณมีรายการต่อไปนี้

ความรู้ที่จําเป็น

ทําความเข้าใจเกี่ยวกับวงจรชีวิตรายการ Microsoft Fabric อ่านการจัดการวงจรชีวิตรายการ

ความเข้าใจนี้เป็นสิ่งสําคัญสําหรับบทความนี้ Back End ที่สร้างขึ้นใช้การดําเนินการวงจรชีวิต (สร้าง อ่าน อัปเดต ลบ) สําหรับรายการ Fabric ตามที่กําหนดไว้ในเอกสารวงจรชีวิตรายการ
ความรู้พื้นฐานของ Python และ RESTful API
ความคุ้นเคยกับแนวคิดปริมาณงาน Microsoft Fabric

ซอฟต์แวร์ที่จําเป็น

Python 3.8+ ดาวน์โหลด Python
Node.jsซึ่งจําเป็นถ้าคุณต้องการติดตั้ง OpenAPI Generator CLI ผ่าน npm ดาวน์โหลด Node.js
Git เพื่อลอกแบบที่เก็บตัวอย่าง ดาวน์โหลด Git
ตัวแก้ไขโค้ด เช่น Visual Studio Code, PyCharm หรือสภาพแวดล้อมการพัฒนาแบบรวมที่คุณต้องการ (IDE)

Java สําหรับตัวสร้าง OpenAPI

OpenAPI Generator CLI จําเป็นต้องใช้ Java เป็นสภาพแวดล้อมแบบรันไทม์ คุณไม่จําเป็นต้องเขียนรหัส Java คุณต้องใช้เพียงเพื่อเรียกใช้เครื่องมือตัวสร้างเท่านั้น

เวอร์ชัน Java ขั้นต่ําที่จําเป็นคือ Java 8 เราขอแนะนําให้คุณใช้เวอร์ชันการสนับสนุนระยะยาว (LTS) ที่รองรับ เช่น Java 17 หรือ Java 21

วิธีการติดตั้ง Java:

ติดตั้ง Microsoft build ของ OpenJDK (แนะนํา) ทําตามคําแนะนําสําหรับระบบปฏิบัติการของคุณใน ติดตั้ง Microsoft Build ของ OpenJDK
ตรวจสอบการติดตั้งของคุณ เปิดเทอร์มินัลหรือพร้อมท์คําสั่งและเรียกใช้:
```
java -version
```
คุณควรเห็นผลลัพธ์คล้ายกับตัวอย่างนี้:
```
openjdk version "17.0.12" 2024-07-16 LTS
OpenJDK Runtime Environment Microsoft-10377968 (build 17.0.12+7-LTS)
OpenJDK 64-Bit Server VM Microsoft-10377968 (build 17.0.12+7-LTS, mixed mode, sharing)
```

หากคุณติดตั้ง Java จากผู้ขายรายอื่นแล้ว (เช่น Oracle, Eclipse Temurin หรือ Amazon Corretto) พร้อมเวอร์ชัน 8 หรือใหม่กว่า คุณสามารถใช้การติดตั้งที่มีอยู่ของคุณได้

ขั้นตอนที่ 1: ตั้งค่าสภาพแวดล้อมการพัฒนาของคุณ

ก่อนอื่น ให้ตั้งค่าสภาพแวดล้อมการพัฒนาของคุณด้วยเครื่องมือและแพคเกจที่จําเป็น:

โคลนที่เก็บตัวอย่างสําหรับนักพัฒนา Microsoft Fabric:

git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample
cd Microsoft-Fabric-workload-development-sample

สร้าง PythonBackend ไดเรกทอรี:
```
mkdir PythonBackend
cd PythonBackend
```

สร้างสภาพแวดล้อมเสมือน Python:

# Create a Python virtual environment for the project
python -m venv .venv

# Activate the virtual environment
# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

ติดตั้ง OpenAPI Generator CLI:
```
npm install @openapitools/openapi-generator-cli -g
```
สําหรับวิธีการติดตั้งทางเลือก โปรดดูเอกสารประกอบการติดตั้งตัวสร้าง OpenAPI

ขั้นตอนที่ 2: ตรวจสอบว่าสภาพแวดล้อมเสมือน Python ของคุณเปิดใช้งานอยู่

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

ตรวจสอบการเปิดใช้งานของสภาพแวดล้อมเสมือน

ยืนยันว่าสภาพแวดล้อมเสมือนของคุณถูกเปิดใช้งานแล้ว คุณควรเห็น (.venv) ที่จุดเริ่มต้นของพร้อมท์เทอร์มินัลของคุณ

ถ้าไม่ได้เปิดใช้งานสภาพแวดล้อมเสมือน ให้เรียกใช้:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

ตรวจสอบว่าตัวแปล Python ของสภาพแวดล้อมเสมือนคุณใช้งานอยู่

ยืนยันว่าเทอร์มินัลของคุณใช้ตัวแปลภาษา Python จากสภาพแวดล้อมเสมือนของคุณ ไม่ใช่การติดตั้ง Python ทั่วโลกของระบบของคุณ

เรียกใช้คําสั่งต่อไปนี้:

# Display the path to the active Python interpreter
python -c "import sys; print(sys.executable)"

เอาต์พุตที่คาดหวังควรชี้ไปยังสภาพแวดล้อมเสมือนของคุณ:

- Windows: C:\path\to\project\PythonBackend\.venv\Scripts\python.exe
- macOS/Linux: /path/to/project/PythonBackend/.venv/bin/python

สําคัญ

ถ้าเอาต์พุตชี้ไปยังตําแหน่งอื่น (เช่นการติดตั้ง Python ทั้งระบบของคุณ) สภาพแวดล้อมเสมือนของคุณจะเปิดใช้งานไม่ถูกต้อง กลับไปดูงานการเปิดใช้งานอีกครั้งและตรวจสอบให้แน่ใจว่าพร้อมท์เทอร์มินัลของคุณปรากฏขึ้นพร้อมกับ(.venv)

กําหนดค่า IDE ของคุณ (ไม่บังคับ)

IDEs ที่ทันสมัยส่วนใหญ่จะตรวจหาสภาพแวดล้อมเสมือนของ Python โดยอัตโนมัติ อย่างไรก็ตาม คุณอาจจําเป็นต้องเลือกตัวแปลด้วยตนเองภายในการตั้งค่า IDE ของคุณ

ตัวอย่าง: การกําหนดค่า Visual Studio Code

เปิดโฟลเดอร์โครงการของคุณใน Visual Studio Code
เปิดชุดคําสั่ง:
- Windows หรือ Linux: Ctrl+Shift+P
- macOS: Cmd+Shift+P
ค้นหา และเลือกPython: Select Interpreter
เลือกล่ามที่อยู่ในสภาพแวดล้อมเสมือนของคุณ:
- Windows: .venv\Scripts\python.exe
- macOS หรือ Linux: .venv/bin/python
ตรวจสอบการเลือกของคุณบนแถบสถานะที่ด้านล่างของ Visual Studio Code ซึ่งควรแสดงบางอย่างเช่น:
```
Python 3.x.x ('.venv': venv)
```
เปิดเทอร์มินัลรวมใหม่ (เทอร์มินัล>ใหม่) สภาพแวดล้อมเสมือนของคุณควรเปิดใช้งานโดยอัตโนมัติ ตามที่ระบุโดย (.venv) ในพร้อมท์

แก้ไขปัญหาสภาพแวดล้อมเสมือนของคุณ

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

เคล็ดลับ

หาก IDE ของคุณไม่ตรวจพบสภาพแวดล้อมเสมือนโดยอัตโนมัติหรือหากเส้นทางตัวแปลไม่ตรงกับสภาพแวดล้อมเสมือนของคุณ ลองใช้โซลูชันเหล่านี้:

ตรวจสอบให้แน่ใจว่าคุณเปิด IDE ของคุณจากไดเรกทอรีโครงการที่ถูกต้อง
รีสตาร์ต IDE ของคุณและลองเลือกตัวแปลภาษาอีกครั้ง
ยืนยันว่าสภาพแวดล้อมเสมือนของคุณถูกเปิดใช้งานในเทอร์มินัลของคุณ

ขั้นตอนที่ 3: สร้างโครงการ FastAPI จากข้อกําหนด OpenAPI

ใช้ OpenAPI Generator CLI เพื่อสร้างโครงการ Python FastAPI จากข้อกําหนด Swagger ของ Fabric API

เรียกใช้คําสั่งการสร้าง

เรียกใช้คําสั่งต่อไปนี้จากไดเรกทอรีของคุณ PythonBackend :

openapi-generator-cli generate -i ../Backend/src/Contracts/FabricAPI/Workload/swagger.json -g python-fastapi -o . --additional-properties=packageName=fabric_api

คําสั่งนี้แนะนํา OpenAPI Generator CLI เพื่อดําเนินการต่อไปนี้:

พารามิเตอร์	ค่า	คำอธิบาย	ต้องระบุ	วัตถุประสงค์	การอ้างอิง
`-i`	`[InputSpecPath]` ¹	ข้อกําหนดอินพุท: ระบุเส้นทางไปยังแฟ้มข้อกําหนด OpenAPI (Swagger) ต้นทาง	ต้องระบุ	ชี้ไปที่สัญญา Fabric API ที่กําหนดจุดสิ้นสุด แบบจําลอง และการดําเนินการทั้งหมด	ข้อมูลจําเพาะของ OpenAPI ของ
`-g`	`python-fastapi` ²	ชื่อตัวสร้าง: บอกเครื่องมือให้ใช้ตัว `python-fastapi` สร้างเพื่อสร้างโค้ด Python ฝั่งเซิร์ฟเวอร์	ต้องระบุ	กําหนดเฟรมเวิร์กเอาต์พุตและภาษาสําหรับโค้ด back-end ที่สร้างขึ้น	ตัวสร้าง FastAPI ของ Python สํารวจตัวสร้างเซิร์ฟเวอร์ที่พร้อมใช้งานทั้งหมด
`-o`	`.`	ไดเรกทอรีผลลัพธ์: แนะนําตัวสร้างเพื่อวางไฟล์เอาต์พุตในไดเรกทอรีปัจจุบัน	ต้องระบุ	ระบุว่าจะสร้างโครงสร้างโครงการที่สร้างขึ้นที่ใด	ไม่สามารถใช้งานได้
`--additional-properties`	`packageName=fabric_api`	ตัวเลือกเฉพาะตัวสร้าง: ตั้งชื่อแพคเกจ Python สําหรับโค้ดที่สร้างขึ้นเป็น `fabric_api`	เลือกได้	กําหนดโครงสร้างโค้ดที่สร้างขึ้นและรูปแบบการตั้งชื่อ	ตัวเลือกตัวสร้าง

¹ สําหรับ [InputSpecPath]เส้นทางคือ../Backend/src/Contracts/FabricAPI/Workload/swagger.json

² สําหรับพารามิเตอร์ตัวสร้าง (-g) บทความนี้ใช้ค่า python-fastapi เป็นตัวอย่าง OpenAPI Generator สนับสนุนตัวสร้างโค้ดฝั่งเซิร์ฟเวอร์จํานวนมากสําหรับภาษาและเฟรมเวิร์กต่าง ๆ คุณสามารถแทนที่ python-fastapi ด้วยตัวสร้างที่คุณต้องการ สําหรับรายการที่ครอบคลุม ดูที่เอกสารประกอบตัวสร้างเซิร์ฟเวอร์ OpenAPI

ติดตั้งการขึ้นต่อกันที่จําเป็น

เมื่อต้องการติดตั้งการขึ้นต่อกัน ให้ใช้คําสั่งนี้:

pip install -r requirements.txt

บน Windows คุณอาจพบข้อผิดพลาดกับ uvloop แพคเกจ หากเกิดกรณีเช่นนี้ขึ้น:

เปิดไฟล์ของคุณrequirements.txt
ค้นหารายการ uvloop ซึ่งอาจมีลักษณะคล้ายกับuvloop==0.17.0 เพิ่มเงื่อนไขแพลตฟอร์มในตอนท้าย:
```
uvloop==<existing version>; sys_platform != 'win32'
```
ตัวอย่างเช่น ถ้าแฟ้มของคุณมี uvloop==0.17.0ให้เปลี่ยนเป็นuvloop==0.17.0; sys_platform != 'win32'
เรียกใช้ pip install -r requirements.txt อีกครั้ง

การเปลี่ยนแปลงนี้จะทําให้แน่ใจว่า uvloop มีการติดตั้งเฉพาะบนแพลตฟอร์มที่ไม่ใช่ Windows เท่านั้น

ขั้นตอนที่ 4: ทําความเข้าใจโครงสร้างโค้ดที่สร้างขึ้น

OpenAPI Generator สร้างโครงการ FastAPI ที่มีโครงสร้างด้วยไดเรกทอรีหลักต่อไปนี้:

PythonBackend/
├── src/
│   └── fabric_api/
│       ├── apis/              # Generated API route definitions
│       │   ├── item_lifecycle_api.py
│       │   ├── jobs_api.py
│       │   └── endpoint_resolution_api.py
│       ├── impl/              # Where you'll implement controllers
│       │   └── __init__.py
│       ├── models/            # Data models for requests/responses
│       │   ├── create_item_request.py
│       │   └── ...
│       └── main.py            # FastAPI application entry point
├── tests/                     # Generated test files
└── requirements.txt           # Dependencies

ไดเรกทอรี apis ประกอบด้วยข้อกําหนดของเราเตอร์สําหรับแต่ละจุดสิ้นสุด API
ไดเรกทอรี models ประกอบด้วยแบบจําลอง Pydantic สําหรับคําขอและวัตถุตอบสนอง
ไดเรกทอรี impl คือตําแหน่งที่คุณใช้ตรรกะของผู้ควบคุมของคุณ
ไฟล์ main.py ตั้งค่าแอปพลิเคชัน FastAPI

ขั้นตอนที่ 5: ใช้ตัวควบคุม ItemLifecycle

สร้างการใช้งานตัวควบคุมที่จัดการคําขอ Fabric API ตัวควบคุมสืบทอดมาจากคลาสพื้นฐานที่สร้างขึ้น

สร้าง item_lifecycle_controller.py ใน impl ไดเรกทอรี:

# file path: src/fabric_api/impl/item_lifecycle_controller.py

from fabric_api.apis.item_lifecycle_api_base import BaseItemLifecycleApi
from fabric_api.models.get_item_payload_response import GetItemPayloadResponse
from pydantic import Field, StrictStr
from typing_extensions import Annotated
from fastapi import HTTPException

class ItemLifecycleController(BaseItemLifecycleApi):
    """
    Implementation of Item Lifecycle API methods.
    """
    
    async def item_lifecycle_create_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
        create_item_request,
    ) -> None:
        """
        Implementation for creating a new item.
        """
        print(f"\n=== CREATE ITEM CALLED ===")
        print(f"Workspace ID: {workspaceId}")
        print(f"Item Type: {itemType}")
        print(f"Item ID: {itemId}")
        print(f"Display Name: {create_item_request.display_name}")
        print(f"Description: {create_item_request.description}")
        if create_item_request.creation_payload:
            print(f"Creation Payload: {create_item_request.creation_payload}")
        print("===========================\n")
        return
    
    async def item_lifecycle_delete_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
    ) -> None:
        """
        Implementation for deleting an existing item.
        """
        print(f"Delete item called for itemId: {itemId}")
        return
    
    async def item_lifecycle_get_item_payload(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
    ) -> GetItemPayloadResponse:
        """
        Implementation for retrieving the payload for an item.
        """
        print(f"Get item payload called for itemId: {itemId}")
        # Return a simple payload
        return GetItemPayloadResponse(item_payload={"sample": "data"})
    
    async def item_lifecycle_update_item(
        self,
        workspaceId,
        itemType,
        itemId,
        activity_id,
        request_id,
        authorization,
        x_ms_client_tenant_id,
        update_item_request,
    ) -> None:
        """
        Implementation for updating an existing item.
        """
        print(f"Update item called for itemId: {itemId}")
        return

ขั้นตอนที่ 6: กําหนดค่าและเรียกใช้แอปพลิเคชัน FastAPI

ก่อนที่คุณจะเรียกใช้แอปพลิเคชัน FastAPI ของคุณ ตรวจสอบให้แน่ใจว่าการกําหนดค่าพอร์ตสอดคล้องกับสภาพแวดล้อมการพัฒนาของ Microsoft Fabric ขั้นตอนนี้เป็นสิ่งสําคัญสําหรับการรวมที่เหมาะสมกับเกตเวย์การพัฒนา Fabric

ทําความเข้าใจเกี่ยวกับการกําหนดค่าพอร์ต

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

Back end ของคุณเพื่อเรียกใช้บนพอร์ตเฉพาะ (ค่าเริ่มต้น: 5000)
พอร์ตที่ตรงกับ WorkloadEndpointURL ค่าในการกําหนดค่าปริมาณงานของคุณ
การเรียก Fabric API ทั้งหมดจะกําหนดเส้นทางผ่านเกตเวย์การพัฒนาไปยังจุดสิ้นสุดนี้

กําหนดค่าจุดสิ้นสุดปริมาณงาน (สําหรับการรวม Fabric)

เมื่อคุณรวมเข้ากับสภาพแวดล้อมการพัฒนา Microsoft Fabric เต็มรูปแบบ คุณต้องกําหนดค่า URL ปลายทางของปริมาณงาน การกําหนดค่านี้บอกเกตเวย์การพัฒนาว่าจะส่งต่อคําขอ API ได้ที่ไหน

ค้นหาหรือสร้างไฟล์การกําหนดค่าปริมาณงาน (workload-dev-mode.json):
- ตําแหน่งที่ตั้งเริ่มต้นจะถูก C:\workload-dev-mode.json
- คุณสามารถสร้างไฟล์นี้ในภายหลัง เมื่อคุณกําลังตั้งค่าสภาพแวดล้อมการพัฒนา Fabric เต็มรูปแบบ
ตรวจสอบให้แน่ใจว่าค่า WorkloadEndpointURL ตรงกับพอร์ต back-end ของคุณ:
```
{
    "WorkloadEndpointURL": "http://localhost:5000",
    // ... other configuration settings
}
```

สําหรับรายละเอียดการกําหนดค่าปริมาณงานที่สมบูรณ์ โปรดดูเอกสารประกอบสําหรับการเริ่มต้นใช้งานส่วนท้ายของความสามารถในการเพิ่ม

เรียกใช้แอปพลิเคชัน FastAPI

เริ่มต้นแอปพลิเคชัน FastAPI ของคุณบนพอร์ต 5000 (หรือพอร์ตที่คุณเลือกที่ตรงกับการกําหนดค่า)

สําหรับ Windows PowerShell:

$env:PYTHONPATH="src"
uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

สําหรับพร้อมท์คําสั่ง Windows:

set PYTHONPATH=src
uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

สําหรับ macOS หรือ Linux:

PYTHONPATH=src uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

สําคัญ

การตั้งค่า PYTHONPATH เป็นสิ่งสําคัญสําหรับ Python เพื่อค้นหาโมดูลอย่างถูกต้อง ตัวแปรสภาพแวดล้อมนี้มีผลต่อเซสชันเทอร์มินัลปัจจุบันเท่านั้น

อีกวิธีหนึ่งคือ คุณสามารถเรียกใช้คําสั่งจาก src ไดเรกทอรี:

cd src
python -m uvicorn fabric_api.main:app --host 0.0.0.0 --port 5000

หมายเหตุ

พอร์ต 5000 มักใช้เป็นค่าเริ่มต้นในตัวอย่างการพัฒนาปริมาณงาน Microsoft Fabric ถ้าคุณจําเป็นต้องใช้พอร์ตอื่น:

เปลี่ยนค่า --port ในคําสั่งของคุณ uvicorn (ตัวอย่างเช่น --port 5001)
เมื่อต้องการจับคู่พอร์ตใหม่นี้ ให้ WorkloadEndpointURL อัปเดตค่าในไฟล์ของคุณ workload-dev-mode.json (ตัวอย่างเช่น "http://localhost:5001")

ตรวจสอบให้แน่ใจว่าแอปพลิเคชันอื่นในระบบของคุณไม่ได้ใช้พอร์ตที่คุณเลือก

ตรวจสอบว่าส่วนหลังของคุณสามารถเข้าถึงได้

หลังจากที่คุณเริ่มแอปพลิเคชัน ตรวจสอบว่าแอปทํางานอย่างถูกต้อง:

ตรวจสอบเอาต์พุตของคอนโซล ซึ่งควรมีลักษณะคล้ายกับตัวอย่างนี้:

INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO:     Started reloader process [xxxx]
INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

ทดสอบเอกสาร API:
1. เปิดเบราว์เซอร์ของคุณและไปที่ http://localhost:5000/docs
2. ยืนยันว่า Swagger UI แสดงจุดสิ้นสุดที่พร้อมใช้งานทั้งหมด

ขั้นตอนที่ 7: ทดสอบ API

คุณสามารถทดสอบ API ของคุณโดยใช้คําสั่ง Curl หรือ Swagger UI ที่มีอยู่ภายในที่ FastAPI มีให้

ขด

เรียกใช้คําสั่งต่อไปนี้ในเทอร์มินัลของคุณ:

curl -X POST "http://localhost:5000/workspaces/test-workspace/items/TestItemType/test-item-123" \
  -H "Content-Type: application/json" \
  -H "activity-id: test-activity-id" \
  -H "request-id: test-request-123" \
  -H "authorization: SubjectAndAppToken1.0 subjectToken=\"dummy-token\", appToken=\"dummy-app-token\"" \
  -H "x-ms-client-tenant-id: test-tenant-456" \
  -d '{
    "display_name": "Test Item",
    "description": "This is a test item created via curl",
    "creation_payload": {
      "key1": "value1",
      "key2": "value2",
      "nested": {
        "data": "example"
      }
    }
  }'

Swagger UI

FastAPI จะสร้างเอกสาร API แบบโต้ตอบโดยอัตโนมัติ เพื่อให้คุณสามารถทดสอบจุดสิ้นสุดของคุณได้โดยตรงจากเบราว์เซอร์ของคุณ:

เปิดเบราว์เซอร์ของคุณและไปที่ http://localhost:5000/docs
ในส่วน ItemLifecycle ค้นหาตําแหน่งข้อมูล POST :
```
POST /workspaces/{workspaceId}/items/{itemType}/{itemId}
```
เลือกปุ่ม ลองใช้
กรอกพารามิเตอร์ที่จําเป็น:
- workspaceId: test-workspace
- itemType: TestItemType
- itemId: test-item-123
- activity-id: test-activity-id
- request-id: test-request-123
- authorization: SubjectAndAppToken1.0 subjectToken="dummy-token", appToken="dummy-app-token"
- x-ms-client-tenant-id: test-tenant-456
สําหรับเนื้อความของคําขอ ให้ใช้โค้ดต่อไปนี้:
```
{
    "display_name": "Test Item",
    "description": "This is a test item created via Swagger UI",
    "creation_payload": {
        "key1": "value1",
        "key2": "value2",
        "nested": {
        "data": "example"
        }
    }
}
```
เลือกปุ่ม ดําเนินการ เพื่อส่งคําขอ

คอนโซลเซิร์ฟเวอร์แสดงผลลัพธ์ที่คล้ายกับข้อความต่อไปนี้:
```
=== CREATE ITEM CALLED ===
Workspace ID: test-workspace
Item Type: TestItemType
Item ID: test-item-123
Display Name: Test Item
Description: This is a test item created via Swagger UI
Creation Payload: {'key1': 'value1', 'key2': 'value2', 'nested': {'data': 'example'}}
===========================
```
รายละเอียดการตอบกลับจะปรากฏโดยตรงใน Swagger UI

เคล็ดลับ

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

ขั้นตอนที่ 8: สํารวจเอกสาร API

FastAPI จะสร้างเอกสาร API แบบโต้ตอบโดยอัตโนมัติ:

เปิดเบราว์เซอร์ของคุณและไปที่ http://localhost:5000/docs
บน Swagger UI ที่ปรากฏขึ้น คุณสามารถสํารวจและทดสอบจุดสิ้นสุดทั้งหมดได้
เมื่อต้องการดูจุดสิ้นสุดสร้าง รับ อัปเดต และลบ ให้เลือก ItemLifecycle ส่วน

รูปภาพต่อไปนี้แสดงตัวอย่างของ Swagger UI ที่มีจุดสิ้นสุด Fabric API

ขั้นตอนที่ 9: ใช้ฟังก์ชันการทํางานขั้นสูงเพิ่มเติม

ขั้นตอนก่อนหน้านี้แสดงตัวอย่างพื้นฐานของวิธีการใช้ ItemLifecycle API โดยใช้ Python กับ FastAPI โปรดจําไว้ว่าบทความนี้เป็นตัวอย่างพื้นฐานที่แสดงเฉพาะแนวคิดหลักเท่านั้น สําหรับส่วนหลังที่มีเสถียรภาพและมีคุณภาพการผลิต โดยทั่วไปแล้วคุณจะใช้ฟังก์ชันการทํางานเพิ่มเติม เช่น:

สร้างคลาสบริการเพื่อจัดการตรรกะทางธุรกิจ การดําเนินการฐานข้อมูล และองค์ประกอบอื่น ๆ ของชั้นบริการ:

# src/fabric_api/services/storage_service.py
class StorageService:
    async def create_item(self, workspace_id, item_type, item_id, item_data):
        """
        Store the item in a database or other persistent storage
        """
        # Implementation here
        pass

    async def get_item(self, workspace_id, item_type, item_id):
        """
        Retrieve an item from storage
        """
        # Implementation here
        pass

ใช้การฉีดขึ้นต่อกันในตัวควบคุมของคุณ:

# src/fabric_api/impl/item_lifecycle_controller.py
from fabric_api.services.storage_service import StorageService

class ItemLifecycleController(BaseItemLifecycleApi):
    def __init__(self):
        self.storage_service = StorageService()

    async def item_lifecycle_create_item(self, workspaceId, ...):
        # Use the service
        await self.storage_service.create_item(workspaceId, itemType, itemId, create_item_request)

เพิ่มการจัดการข้อผิดพลาด:

async def item_lifecycle_create_item(self, ...):
    try:
        # Your implementation
        await self.storage_service.create_item(...)
        return None
    except ValueError as e:
        # Client error
        raise HTTPException(status_code=400, detail=str(e))
    except Exception as e:
        # Server error
        raise HTTPException(status_code=500, detail="Internal server error")

ต่อไปนี้คือข้อควรพิจารณาเพิ่มเติมสําหรับส่วนหลังที่มีเสถียรภาพ:

การใช้งานของผู้ควบคุมที่เหลืออยู่: ตัวอย่างเช่น ใช้ API งานและ API ความละเอียดของจุดสิ้นสุด
การรับรองความถูกต้องและการอนุญาต: ช่วยรักษาความปลอดภัยจุดสิ้นสุดของคุณโดยการตรวจสอบโทเค็นและสิทธิ์ สําหรับข้อมูลเพิ่มเติม ดูภาพรวมการรับรองความถูกต้องและการรับรองความถูกต้อง Back-end
ที่เก็บข้อมูลแบบถาวร: รวมกับฐานข้อมูลหรือโซลูชันที่เก็บอื่น ๆ เพื่อการคงอยู่ของข้อมูล
การบันทึกและการตรวจสอบ: ใช้การบันทึกที่ครอบคลุมและการตรวจสอบเพื่อติดตามสถานภาพและประสิทธิภาพของแอปพลิเคชัน
การทดสอบ: เขียนการทดสอบหน่วยและการรวมเพื่อช่วยรับประกันความน่าเชื่อถือและความถูกต้อง

บทสรุป

ตอนนี้คุณได้ตั้งค่า API ปริมาณงาน Microsoft Fabric back end โดยใช้ Python กับ FastAPI เรียบร้อยแล้ว การดําเนินการนี้:

ใช้เครื่องมือตัวสร้าง OpenAPI เพื่อสร้างโครงการ FastAPI
ใช้ตัวควบคุมที่จําเป็นสําหรับการจัดการคําขอ Fabric API

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

การรวมที่สมบูรณ์กับ Microsoft Fabric จําเป็นต้องใช้การจัดการการรับรองความถูกต้องที่เหมาะสม ที่เก็บแบบถาวร การจัดการข้อผิดพลาดที่ครอบคลุม และตรรกะทางธุรกิจแบบกําหนดเองที่เฉพาะเจาะจงสําหรับปริมาณงานของคุณ