שליטה בהעלאות קבצים ב-FastAPI: צלילת עומק לעיבוד טפסי Multipart

ביישומי ווב מודרניים, היכולת לטפל בהעלאות קבצים היא דרישה בסיסית. בין אם מדובר במשתמשים המעלים תמונות פרופיל, מסמכים לעיבוד, או מדיה לשיתוף, מנגנוני העלאת קבצים חזקים ויעילים הם קריטיים. FastAPI, ספריית ווב עתירת ביצועים לפייתון, מצטיינת בתחום זה, ומציעה דרכים יעילות לנהל נתוני טופס מסוג multipart, שהוא התקן לשליחת קבצים באמצעות HTTP. מדריך מקיף זה יוביל אתכם דרך המורכבויות של העלאת קבצים ב-FastAPI, החל ממימוש בסיסי ועד לשיקולים מתקדמים, ויבטיח שתוכלו לבנות בביטחון ממשקי API עוצמתיים וסקיילביליים עבור קהל גלובלי.

הבנת נתוני טופס Multipart

לפני שצוללים למימוש של FastAPI, חיוני להבין מהם נתוני טופס multipart. כאשר דפדפן שולח טופס המכיל קבצים, הוא בדרך כלל משתמש במאפיין enctype="multipart/form-data". סוג קידוד זה מפרק את שליחת הטופס למספר חלקים, שלכל אחד מהם יש סוג תוכן (content type) ומידע על סידור (disposition) משלו. זה מאפשר העברה של סוגי נתונים שונים בתוך בקשת HTTP אחת, כולל שדות טקסט, שדות שאינם טקסט, וקבצים בינאריים.

כל חלק בבקשת multipart מורכב מ:

• כותרת Content-Disposition: מציינת את שם שדה הטופס (name), ובמקרה של קבצים, את שם הקובץ המקורי (filename).
• כותרת Content-Type: מציינת את סוג ה-MIME של החלק (לדוגמה, text/plain, image/jpeg).
• גוף (Body): הנתונים עצמם של אותו חלק.

הגישה של FastAPI להעלאות קבצים

FastAPI ממנפת את הספרייה הסטנדרטית של פייתון ומשתלבת בצורה חלקה עם Pydantic לאימות נתונים. עבור העלאות קבצים, היא משתמשת בסוג UploadFile מהמודול fastapi. מחלקה זו מספקת ממשק נוח ובטוח לגישה לנתוני הקובץ שהועלה.

מימוש בסיסי של העלאת קבצים

נתחיל בדוגמה פשוטה של יצירת נקודת קצה (endpoint) ב-FastAPI שמקבלת העלאת קובץ יחיד. נשתמש בפונקציה File מ-fastapi כדי להכריז על פרמטר הקובץ.

            from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/files/")
async def create_file(file: UploadFile):
    return {"filename": file.filename, "content_type": file.content_type}

            

              
                Copy
              
            
          

בדוגמה זו:

• אנו מייבאים את FastAPI, File, ו-UploadFile.
• נקודת הקצה /files/ מוגדרת כבקשת POST.
• הפרמטר file מקבל אנוטציה מסוג UploadFile, מה שמסמן שהוא מצפה לקבל העלאת קובץ.
• בתוך פונקציית נקודת הקצה, אנו יכולים לגשת למאפיינים של הקובץ שהועלה, כגון filename ו-content_type.

כאשר לקוח שולח בקשת POST ל-/files/ עם קובץ מצורף (בדרך כלל באמצעות טופס עם enctype="multipart/form-data"), FastAPI תטפל אוטומטית בפענוח ותספק אובייקט UploadFile. לאחר מכן, תוכלו לעבוד עם אובייקט זה.

שמירת קבצים שהועלו

לעתים קרובות, תצטרכו לשמור את הקובץ שהועלה לדיסק או לעבד את תוכנו. אובייקט UploadFile מספק מתודות לכך:

• read(): קורא את כל תוכן הקובץ לזיכרון כבתים (bytes). יש להשתמש בזה עבור קבצים קטנים.
• write(content: bytes): כותב בתים לקובץ.
• seek(offset: int): משנה את המיקום הנוכחי בקובץ.
• close(): סוגר את הקובץ.

חשוב לטפל בפעולות קבצים באופן אסינכרוני, במיוחד כאשר מתמודדים עם קבצים גדולים או משימות התלויות בקלט/פלט (I/O). UploadFile של FastAPI תומך בפעולות אסינכרוניות.

            from fastapi import FastAPI, File, UploadFile
import shutil

app = FastAPI()

@app.post("/files/save/")
async def save_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
    return {"info": f"file '{file.filename}' saved at '{file_location}'"}

            

              
                Copy
              
            
          

בדוגמה משופרת זו:

• אנו משתמשים ב-File(...) כדי לציין שהפרמטר הזה הוא חובה.
• אנו מציינים נתיב מקומי שבו הקובץ יישמר. ודאו שהספרייה uploads קיימת.
• אנו פותחים את קובץ היעד במצב כתיבה בינארית (`"wb+"`).
• אנו קוראים באופן אסינכרוני את תוכן הקובץ שהועלה באמצעות await file.read() ולאחר מכן כותבים אותו לקובץ המקומי.

הערה: קריאת כל הקובץ לזיכרון באמצעות await file.read() עלולה להיות בעייתית עבור קבצים גדולים מאוד. עבור תרחישים כאלה, שקלו הזרמת תוכן הקובץ.

הזרמת תוכן קובץ (Streaming)

עבור קבצים גדולים, קריאת כל התוכן לזיכרון עלולה להוביל לצריכת זיכרון מופרזת ולשגיאות פוטנציאליות של חוסר זיכרון. גישה יעילה יותר מבחינת זיכרון היא הזרמת הקובץ במקטעים (chunks). הפונקציה shutil.copyfileobj מצוינת לכך, אך עלינו להתאים אותה לפעולות אסינכרוניות.

            from fastapi import FastAPI, File, UploadFile
import aiofiles # Install using: pip install aiofiles

app = FastAPI()

@app.post("/files/stream/")
async def stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        content = await file.read()
        await out_file.write(content)
    return {"info": f"file '{file.filename}' streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

עם aiofiles, אנו יכולים להזרים ביעילות את תוכן הקובץ שהועלה לקובץ יעד מבלי לטעון את כל הקובץ לזיכרון בבת אחת. ה-await file.read() בהקשר זה עדיין קורא את כל הקובץ, אך aiofiles מטפל בכתיבה בצורה יעילה יותר. להזרמה אמיתית במקטעים עם UploadFile, בדרך כלל הייתם משתמשים בלולאה על await file.read(chunk_size), אך aiofiles.open ו-await out_file.write(content) היא תבנית נפוצה ובעלת ביצועים טובים לשמירה.

גישת הזרמה מפורשת יותר המשתמשת במקטעים:

            from fastapi import FastAPI, File, UploadFile
import aiofiles

app = FastAPI()

CHUNK_SIZE = 1024 * 1024 # 1MB chunk size

@app.post("/files/chunked_stream/")
async def chunked_stream_file(file: UploadFile = File(...)):
    file_location = f"./uploads/{file.filename}"
    async with aiofiles.open(file_location, "wb") as out_file:
        while content := await file.read(CHUNK_SIZE):
            await out_file.write(content)
    return {"info": f"file '{file.filename}' chunked streamed and saved at '{file_location}'"}

            

              
                Copy
              
            
          

נקודת הקצה `chunked_stream_file` קוראת את הקובץ במקטעים של 1MB וכותבת כל מקטע לקובץ הפלט. זוהי הדרך היעילה ביותר מבחינת זיכרון לטפל בקבצים שעלולים להיות גדולים מאוד.

טיפול בהעלאות קבצים מרובות

יישומי ווב דורשים לעתים קרובות ממשתמשים להעלות מספר קבצים בו-זמנית. FastAPI הופך זאת לפשוט.

העלאת רשימת קבצים

ניתן לקבל רשימת קבצים על ידי הוספת אנוטציה לפרמטר שלכם עם רשימה של UploadFile.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/multiple/")
async def create_multiple_files(
    files: List[UploadFile] = File(...)
):
    results = []
    for file in files:
        # Process each file, e.g., save it
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {"files_processed": results}

            

              
                Copy
              
            
          

בתרחיש זה, הלקוח צריך לשלוח מספר חלקים עם אותו שם שדה טופס (למשל, `files`). FastAPI יאסוף אותם לתוך רשימת פייתון של אובייקטי UploadFile.

שילוב קבצים עם נתוני טופס אחרים

מקובל שטפסים מכילים גם שדות קבצים וגם שדות טקסט רגילים. FastAPI מטפל בזה על ידי כך שהוא מאפשר להכריז על פרמטרים אחרים באמצעות אנוטציות סוג סטנדרטיות, יחד עם Form עבור שדות טופס שאינם קבצים.

            from fastapi import FastAPI, File, UploadFile, Form
from typing import List

app = FastAPI()

@app.post("/files/mixed/")
async def upload_mixed_data(
    description: str = Form(...),
    files: List[UploadFile] = File(...) # Accepts multiple files with the name 'files'
):
    results = []
    for file in files:
        # Process each file
        file_location = f"./uploads/{file.filename}"
        with open(file_location, "wb+") as file_object:
            file_object.write(await file.read())
        results.append({"filename": file.filename, "content_type": file.content_type, "saved_at": file_location})
    return {
        "description": description,
        "files_processed": results
    }

            

              
                Copy
              
            
          

בעת שימוש בכלים כמו Swagger UI או Postman, תציינו את ה-description כשדה טופס רגיל ואז תוסיפו מספר חלקים עבור השדה files, כאשר סוג התוכן של כל אחד מהם מוגדר לסוג התמונה/מסמך המתאים.

תכונות מתקדמות ושיטות עבודה מומלצות

מעבר לטיפול בסיסי בקבצים, מספר תכונות מתקדמות ושיטות עבודה מומלצות הן קריטיות לבניית ממשקי API חזקים להעלאת קבצים.

מגבלות גודל קובץ

אישור העלאות קבצים ללא הגבלה עלול להוביל להתקפות מניעת שירות (denial-of-service) או לצריכת משאבים מופרזת. למרות ש-FastAPI עצמה אינה אוכפת מגבלות קשות כברירת מחדל ברמת הספרייה, עליכם ליישם בדיקות:

• ברמת היישום: בדקו את גודל הקובץ לאחר קבלתו אך לפני עיבודו או שמירתו.
• ברמת שרת הווב/פרוקסי: הגדירו את שרת הווב שלכם (למשל, Nginx, Uvicorn עם workers) לדחות בקשות החורגות מגודל מטען (payload) מסוים.

דוגמה לבדיקת גודל ברמת היישום:

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

MAX_FILE_SIZE_MB = 10
MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024

@app.post("/files/limited_size/")
async def upload_with_size_limit(file: UploadFile = File(...)):
    if len(await file.read()) > MAX_FILE_SIZE_BYTES:
        raise HTTPException(status_code=400, detail=f"File is too large. Maximum size is {MAX_FILE_SIZE_MB}MB.")
    
    # Reset file pointer to read content again
    await file.seek(0)
    
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully."}

            

              
                Copy
              
            
          

חשוב: לאחר קריאת הקובץ לבדיקת גודלו, עליכם להשתמש ב-await file.seek(0) כדי לאפס את מצביע הקובץ להתחלה אם בכוונתכם לקרוא את תוכנו שוב (למשל, כדי לשמור אותו).

סוגי קבצים מורשים (MIME Types)

הגבלת העלאות לסוגי קבצים ספציפיים משפרת את האבטחה ומבטיחה את שלמות הנתונים. ניתן לבדוק את המאפיין content_type של אובייקט UploadFile.

            from fastapi import FastAPI, File, UploadFile, HTTPException

app = FastAPI()

ALLOWED_FILE_TYPES = {"image/jpeg", "image/png", "application/pdf"}

@app.post("/files/restricted_types/")
async def upload_restricted_types(file: UploadFile = File(...)):
    if file.content_type not in ALLOWED_FILE_TYPES:
        raise HTTPException(status_code=400, detail=f"Unsupported file type: {file.content_type}. Allowed types are: {', '.join(ALLOWED_FILE_TYPES)}")
        
    # Proceed with saving or processing the file
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())
        
    return {"info": f"File '{file.filename}' uploaded successfully and is of an allowed type."}

            

              
                Copy
              
            
          

לבדיקת סוג חזקה יותר, במיוחד עבור תמונות, כדאי לשקול שימוש בספריות כמו Pillow כדי לבדוק את התוכן האמיתי של הקובץ, מכיוון שלפעמים ניתן לזייף סוגי MIME.

טיפול בשגיאות ומשוב למשתמש

ספקו הודעות שגיאה ברורות וניתנות לפעולה למשתמש. השתמשו ב-HTTPException של FastAPI לתגובות שגיאה סטנדרטיות של HTTP.

• קובץ לא נמצא/חסר: אם פרמטר קובץ נדרש לא נשלח.
• חרגה ממגבלת גודל הקובץ: כפי שהוצג בדוגמת מגבלת הגודל.
• סוג קובץ לא חוקי: כפי שהוצג בדוגמת הגבלת הסוג.
• שגיאות שרת: עבור בעיות במהלך שמירת הקובץ או עיבודו (למשל, דיסק מלא, שגיאות הרשאה).

שיקולי אבטחה

העלאות קבצים מציבות סיכוני אבטחה:

• קבצים זדוניים: העלאת קבצי הרצה (.exe, .sh) או סקריפטים המתחזים לסוגי קבצים אחרים. תמיד ודאו את סוגי הקבצים ושקלו לסרוק קבצים שהועלו לאיתור תוכנות זדוניות.
• Path Traversal: בצעו סניטציה לשמות קבצים כדי למנוע מתוקפים להעלות קבצים לספריות לא רצויות (למשל, באמצעות שמות קבצים כמו ../../etc/passwd). UploadFile של FastAPI מטפל בסניטציה בסיסית של שמות קבצים, אך זהירות נוספת היא חכמה.
• מניעת שירות (Denial of Service): ישמו מגבלות גודל קובץ ואולי הגבלת קצב (rate limiting) על נקודות קצה של העלאה.
• Cross-Site Scripting (XSS): אם אתם מציגים שמות קבצים או תוכן קבצים ישירות בדף אינטרנט, ודאו שהם עוברים תהליך escape כראוי כדי למנוע התקפות XSS.

שיטה מומלצת: אחסנו קבצים שהועלו מחוץ לספריית השורש (document root) של שרת הווב שלכם, והגישו אותם דרך נקודת קצה ייעודית עם בקרות גישה מתאימות, או השתמשו ברשת להעברת תוכן (CDN).

שימוש במודלים של Pydantic עם העלאות קבצים

אף על פי ש-UploadFile הוא הסוג העיקרי לקבצים, ניתן לשלב העלאות קבצים במודלים של Pydantic למבני נתונים מורכבים יותר. עם זאת, שדות העלאת קבצים ישירים בתוך מודלים סטנדרטיים של Pydantic אינם נתמכים באופן טבעי עבור טפסי multipart. במקום זאת, בדרך כלל מקבלים את הקובץ כפרמטר נפרד ואז מעבדים אותו לפורמט שניתן לאחסן או לאמת על ידי מודל Pydantic.

תבנית נפוצה היא מודל Pydantic עבור מטא-דאטה וקבלת הקובץ בנפרד:

            from fastapi import FastAPI, File, UploadFile, Form
from pydantic import BaseModel
from typing import Optional

class UploadMetadata(BaseModel):
    title: str
    description: Optional[str] = None

app = FastAPI()

@app.post("/files/model_metadata/")
async def upload_with_metadata(
    metadata: str = Form(...), # Receive metadata as a JSON string
    file: UploadFile = File(...)
):
    import json
    try:
        metadata_obj = UploadMetadata(**json.loads(metadata))
    except json.JSONDecodeError:
        raise HTTPException(status_code=400, detail="Invalid JSON format for metadata")
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Error parsing metadata: {e}")

    # Now you have metadata_obj and file
    # Proceed with saving file and using metadata
    file_location = f"./uploads/{file.filename}"
    with open(file_location, "wb+") as file_object:
        file_object.write(await file.read())

    return {
        "message": "File uploaded successfully with metadata",
        "metadata": metadata_obj,
        "filename": file.filename
    }

            

              
                Copy
              
            
          

בתבנית זו, הלקוח שולח את המטא-דאטה כמחרוזת JSON בתוך שדה טופס (למשל, metadata) ואת הקובץ כחלק multipart נפרד. השרת לאחר מכן מפענח את מחרוזת ה-JSON לאובייקט Pydantic.

העלאת קבצים גדולים ו-Chunking

עבור קבצים גדולים מאוד (למשל, ג'יגה-בייטים), אפילו הזרמה עלולה להיתקל במגבלות של שרת הווב או בצד הלקוח. טכניקה מתקדמת יותר היא העלאות במקטעים (chunked uploads), שבה הלקוח מפרק את הקובץ לחלקים קטנים יותר ומעלה אותם ברצף או במקביל. השרת לאחר מכן מרכיב מחדש את המקטעים הללו. זה בדרך כלל דורש לוגיקה מותאמת אישית בצד הלקוח ונקודת קצה בשרת שנועדה לטפל בניהול המקטעים (למשל, זיהוי מקטעים, אחסון זמני, והרכבה סופית).

אף ש-FastAPI אינה מספקת תמיכה מובנית להעלאות במקטעים ביוזמת הלקוח, ניתן ליישם לוגיקה זו בתוך נקודות הקצה שלכם ב-FastAPI. זה כרוך ביצירת נקודות קצה ש:

• מקבלות מקטעי קבצים בודדים.
• מאחסנות מקטעים אלה באופן זמני, ייתכן שעם מטא-דאטה המציין את סדרם ואת המספר הכולל של המקטעים.
• מספקות נקודת קצה או מנגנון לאיתות כאשר כל המקטעים הועלו, מה שמפעיל את תהליך ההרכבה מחדש.

זוהי משימה מורכבת יותר ולעתים קרובות מערבת ספריות JavaScript בצד הלקוח.

שיקולי בינאום וגלובליזציה (i18n & g11n)

בעת בניית ממשקי API לקהל גלובלי, העלאות קבצים דורשות תשומת לב מיוחדת:

• שמות קבצים: משתמשים ברחבי העולם עשויים להשתמש בתווים שאינם ASCII בשמות קבצים (למשל, הדגשות, אידאוגרמות). ודאו שהמערכת שלכם מטפלת ומאחסנת נכון שמות קבצים אלה. קידוד UTF-8 הוא בדרך כלל סטנדרטי, אך תאימות עמוקה עשויה לדרוש קידוד/פענוח וסניטציה קפדניים.
• יחידות גודל קובץ: בעוד ש-MB ו-GB נפוצים, היו מודעים לאופן שבו משתמשים תופסים גדלי קבצים. חשוב להציג מגבלות באופן ידידותי למשתמש.
• סוגי תוכן: משתמשים עלולים להעלות קבצים עם סוגי MIME פחות נפוצים. ודאו שרשימת הסוגים המורשים שלכם מקיפה או גמישה מספיק למקרה השימוש שלכם.
• תקנות אזוריות: היו מודעים לחוקי ריבונות נתונים ותקנות במדינות שונות. אחסון קבצים שהועלו עשוי לדרוש עמידה בכללים אלה.
• ממשק משתמש: הממשק בצד הלקוח להעלאת קבצים צריך להיות אינטואיטיבי ולתמוך בשפת המשתמש ובאזורו.

כלים וספריות לבדיקה

בדיקת נקודות קצה של העלאת קבצים היא קריטית. הנה כמה כלים נפוצים:

• Swagger UI (תיעוד API אינטראקטיבי): FastAPI יוצר אוטומטית תיעוד Swagger UI. ניתן לבדוק ישירות העלאות קבצים מממשק הדפדפן. חפשו את שדה קלט הקובץ ולחצו על כפתור "Choose File".
• Postman: כלי פופולרי לפיתוח ובדיקת API. כדי לשלוח בקשת העלאת קובץ:
• הגדירו את שיטת הבקשה ל-POST.
• הזינו את כתובת ה-URL של נקודת הקצה שלכם.
• עברו ללשונית "Body".
• בחרו ב-"form-data" כסוג.
• בזוגות מפתח-ערך, הזינו את שם פרמטר הקובץ שלכם (למשל, file).
• שנו את הסוג מ-"Text" ל-"File".
• לחצו על "Choose Files" כדי לבחור קובץ מהמערכת המקומית שלכם.
• אם יש לכם שדות טופס אחרים, הוסיפו אותם באופן דומה, תוך שמירה על סוגם כ-"Text".
• שלחו את הבקשה.
• cURL: כלי שורת פקודה לביצוע בקשות HTTP.
• לקובץ יחיד: curl -X POST -F "file=@/path/to/your/local/file.txt" http://localhost:8000/files/
• למספר קבצים: curl -X POST -F "files=@/path/to/file1.txt" -F "files=@/path/to/file2.png" http://localhost:8000/files/multiple/
• לנתונים מעורבים: curl -X POST -F "description=My description" -F "files=@/path/to/file.txt" http://localhost:8000/files/mixed/
• ספריית requests של פייתון: לבדיקה תכנותית.

            import requests

url = "http://localhost:8000/files/save/"
files = {'file': open('/path/to/your/local/file.txt', 'rb')}

response = requests.post(url, files=files)
print(response.json())

# For multiple files
url_multiple = "http://localhost:8000/files/multiple/"
files_multiple = {
    'files': [('file1.txt', open('/path/to/file1.txt', 'rb')),
              ('image.png', open('/path/to/image.png', 'rb'))]
}
response_multiple = requests.post(url_multiple, files=files_multiple)
print(response_multiple.json())

# For mixed data
url_mixed = "http://localhost:8000/files/mixed/"
data = {'description': 'Test description'}
files_mixed = {'files': open('/path/to/another_file.txt', 'rb')}
response_mixed = requests.post(url_mixed, data=data, files=files_mixed)
print(response_mixed.json())

            

              
                Copy
              
            
          

סיכום

FastAPI מספקת דרך עוצמתית, יעילה ואינטואיטיבית לטפל בהעלאות קבצים מסוג multipart. על ידי מינוף סוג UploadFile ותכנות אסינכרוני, מפתחים יכולים לבנות ממשקי API חזקים המשלבים בצורה חלקה יכולות טיפול בקבצים. זכרו לתעדף אבטחה, ליישם טיפול שגיאות הולם, ולהתחשב בצרכים של בסיס משתמשים גלובלי על ידי התייחסות להיבטים כמו קידוד שמות קבצים ועמידה בתקנות.

בין אם אתם בונים שירות שיתוף תמונות פשוט או פלטפורמת עיבוד מסמכים מורכבת, שליטה בתכונות העלאת הקבצים של FastAPI תהיה נכס משמעותי. המשיכו לחקור את יכולותיה, ליישם שיטות עבודה מומלצות, ולספק חוויות משתמש יוצאות דופן לקהל הבינלאומי שלכם.