แชร์ผ่าน


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

ส่วนท้ายของปริมาณงาน 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:

  1. ติดตั้ง Microsoft build ของ OpenJDK (แนะนํา) ทําตามคําแนะนําสําหรับระบบปฏิบัติการของคุณใน ติดตั้ง Microsoft Build ของ OpenJDK

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

    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: ตั้งค่าสภาพแวดล้อมการพัฒนาของคุณ

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

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

    git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample
    cd Microsoft-Fabric-workload-development-sample
    
  2. สร้าง PythonBackend ไดเรกทอรี:

    mkdir PythonBackend
    cd PythonBackend
    
  3. สร้างสภาพแวดล้อมเสมือน 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
    
  4. ติดตั้ง 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
  1. เปิดโฟลเดอร์โครงการของคุณใน Visual Studio Code

  2. เปิดชุดคําสั่ง:

    • Windows หรือ Linux: Ctrl+Shift+P
    • macOS: Cmd+Shift+P
  3. ค้นหา และเลือกPython: Select Interpreter

  4. เลือกล่ามที่อยู่ในสภาพแวดล้อมเสมือนของคุณ:

    • Windows: .venv\Scripts\python.exe
    • macOS หรือ Linux: .venv/bin/python
  5. ตรวจสอบการเลือกของคุณบนแถบสถานะที่ด้านล่างของ Visual Studio Code ซึ่งควรแสดงบางอย่างเช่น:

    Python 3.x.x ('.venv': venv)
    
  6. เปิดเทอร์มินัลรวมใหม่ (เทอร์มินัล>ใหม่) สภาพแวดล้อมเสมือนของคุณควรเปิดใช้งานโดยอัตโนมัติ ตามที่ระบุโดย (.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 แพคเกจ หากเกิดกรณีเช่นนี้ขึ้น:

  1. เปิดไฟล์ของคุณrequirements.txt

  2. ค้นหารายการ uvloop ซึ่งอาจมีลักษณะคล้ายกับuvloop==0.17.0 เพิ่มเงื่อนไขแพลตฟอร์มในตอนท้าย:

    uvloop==<existing version>; sys_platform != 'win32'
    

    ตัวอย่างเช่น ถ้าแฟ้มของคุณมี uvloop==0.17.0ให้เปลี่ยนเป็นuvloop==0.17.0; sys_platform != 'win32'

  3. เรียกใช้ 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 ได้ที่ไหน

  1. ค้นหาหรือสร้างไฟล์การกําหนดค่าปริมาณงาน (workload-dev-mode.json):

    • ตําแหน่งที่ตั้งเริ่มต้นจะถูก C:\workload-dev-mode.json
    • คุณสามารถสร้างไฟล์นี้ในภายหลัง เมื่อคุณกําลังตั้งค่าสภาพแวดล้อมการพัฒนา Fabric เต็มรูปแบบ
  2. ตรวจสอบให้แน่ใจว่าค่า 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 ถ้าคุณจําเป็นต้องใช้พอร์ตอื่น:

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

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

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

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

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

    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.
    
  2. ทดสอบเอกสาร 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 แบบโต้ตอบโดยอัตโนมัติ เพื่อให้คุณสามารถทดสอบจุดสิ้นสุดของคุณได้โดยตรงจากเบราว์เซอร์ของคุณ:

  1. เปิดเบราว์เซอร์ของคุณและไปที่ http://localhost:5000/docs

  2. ในส่วน ItemLifecycle ค้นหาตําแหน่งข้อมูล POST :

    POST /workspaces/{workspaceId}/items/{itemType}/{itemId}
    
  3. เลือกปุ่ม ลองใช้

  4. กรอกพารามิเตอร์ที่จําเป็น:

    • 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"
            }
        }
    }
    
    
  5. เลือกปุ่ม ดําเนินการ เพื่อส่งคําขอ

    คอนโซลเซิร์ฟเวอร์แสดงผลลัพธ์ที่คล้ายกับข้อความต่อไปนี้:

    === 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 แบบโต้ตอบโดยอัตโนมัติ:

  1. เปิดเบราว์เซอร์ของคุณและไปที่ http://localhost:5000/docs

  2. บน Swagger UI ที่ปรากฏขึ้น คุณสามารถสํารวจและทดสอบจุดสิ้นสุดทั้งหมดได้

  3. เมื่อต้องการดูจุดสิ้นสุดสร้าง รับ อัปเดต และลบ ให้เลือก ItemLifecycle ส่วน

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

สกรีนช็อตของพารามิเตอร์บนอินเทอร์เฟซ Swagger

ขั้นตอนที่ 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 จําเป็นต้องใช้การจัดการการรับรองความถูกต้องที่เหมาะสม ที่เก็บแบบถาวร การจัดการข้อผิดพลาดที่ครอบคลุม และตรรกะทางธุรกิจแบบกําหนดเองที่เฉพาะเจาะจงสําหรับปริมาณงานของคุณ