หมายเหตุ
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลอง ลงชื่อเข้าใช้หรือเปลี่ยนไดเรกทอรีได้
การเข้าถึงหน้านี้ต้องได้รับการอนุญาต คุณสามารถลองเปลี่ยนไดเรกทอรีได้
ส่วนท้ายของปริมาณงาน 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
- Windows หรือ Linux:
ค้นหา และเลือก
Python: Select Interpreter
เลือกล่ามที่อยู่ในสภาพแวดล้อมเสมือนของคุณ:
- Windows:
.venv\Scripts\python.exe
- macOS หรือ Linux:
.venv/bin/python
- Windows:
ตรวจสอบการเลือกของคุณบนแถบสถานะที่ด้านล่างของ 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]
1 |
ข้อกําหนดอินพุท: ระบุเส้นทางไปยังแฟ้มข้อกําหนด OpenAPI (Swagger) ต้นทาง |
ต้องระบุ | ชี้ไปที่สัญญา Fabric API ที่กําหนดจุดสิ้นสุด แบบจําลอง และการดําเนินการทั้งหมด | ข้อมูลจําเพาะของ OpenAPI ของ |
-g |
python-fastapi
2 |
ชื่อตัวสร้าง: บอกเครื่องมือให้ใช้ตัว python-fastapi สร้างเพื่อสร้างโค้ด Python ฝั่งเซิร์ฟเวอร์ |
ต้องระบุ | กําหนดเฟรมเวิร์กเอาต์พุตและภาษาสําหรับโค้ด back-end ที่สร้างขึ้น |
ตัวสร้าง FastAPI ของ Python สํารวจตัวสร้างเซิร์ฟเวอร์ที่พร้อมใช้งานทั้งหมด |
-o |
. |
ไดเรกทอรีผลลัพธ์: แนะนําตัวสร้างเพื่อวางไฟล์เอาต์พุตในไดเรกทอรีปัจจุบัน |
ต้องระบุ | ระบุว่าจะสร้างโครงสร้างโครงการที่สร้างขึ้นที่ใด | ไม่สามารถใช้งานได้ |
--additional-properties |
packageName=fabric_api |
ตัวเลือกเฉพาะตัวสร้าง: ตั้งชื่อแพคเกจ Python สําหรับโค้ดที่สร้างขึ้นเป็น fabric_api |
เลือกได้ | กําหนดโครงสร้างโค้ดที่สร้างขึ้นและรูปแบบการตั้งชื่อ | ตัวเลือกตัวสร้าง |
1 สําหรับ [InputSpecPath]
เส้นทางคือ../Backend/src/Contracts/FabricAPI/Workload/swagger.json
2 สําหรับพารามิเตอร์ตัวสร้าง (-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:
- เปิดเบราว์เซอร์ของคุณและไปที่
http://localhost:5000/docs
- ยืนยันว่า 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 จําเป็นต้องใช้การจัดการการรับรองความถูกต้องที่เหมาะสม ที่เก็บแบบถาวร การจัดการข้อผิดพลาดที่ครอบคลุม และตรรกะทางธุรกิจแบบกําหนดเองที่เฉพาะเจาะจงสําหรับปริมาณงานของคุณ