Si trajtoni të dhënat e formularit dhe ngarkesat e skedarëve?

Question

Accepted Answer

FastAPI trajtojnë **të dhënat e formularit HTML** (`Form`) dhe **ngarkesat e skedarëve** (`File`/`UploadFile`) — të ndryshme nga trupat JSON, pasi ato përdorin lloje të ndryshme përmbajtjeje (`multipart/form-data`). Të dyja deklarohen me lloje parametrash të veçanta.

## Fushat e formularit

```python
from fastapi import Form

@app.post("/login")
def login(username: str = Form(), password: str = Form()):   # form fields, not JSON
    # data comes as application/x-www-form-urlencoded or multipart/form-data
    return {"username": username}
```

Përdorni `Form()` për të marrë fushat e formularit HTML (p.sh. një formular hyrjeje). Shënim: një rrugë mund të përdorë ose një trup JSON **ose** të dhëna formularash, jo të dyja, pasi janë lloje të ndryshme përmbajtjeje. (Kërkon `python-multipart` të instaluar.)

## Ngarkesat e skedarëve

```python
from fastapi import File, UploadFile

@app.post("/upload")
async def upload(file: UploadFile):                  # a single file
    contents = await file.read()                      # read the file's bytes
    file.filename                                      # original name
    file.content_type                                  # MIME type
    # save it:
    with open(f"uploads/{file.filename}", "wb") as f:
        f.write(contents)
    return {"filename": file.filename, "size": len(contents)}
```

`UploadFile` është lloji i rekomanduar — është një skedar i ndarë në spola (skedarëve të mëdhenj shkojnë në disk, jo të gjitha në memorie), me metoda async (`read`, `write`, `seek`) dhe metapërmasa. Përdorjeni atë në vend të `bytes` të papërpunuar për çdo gjë përveç skedarëve të vegjël.

## Skedarë të shumtë dhe formular + skedar së bashku

```python
@app.post("/upload-many")
async def upload_many(files: list[UploadFile]):       # multiple files
    return [f.filename for f in files]

@app.post("/profile")
async def profile(name: str = Form(), avatar: UploadFile = File()):
    # combine form fields AND a file upload in one multipart request
    ...
```

## Validoni ngarkesat (siguria!)

```python
if file.content_type not in ["image/jpeg", "image/png"]:   # check type
    raise HTTPException(400, "Invalid file type")
# also: limit file SIZE, sanitize filenames, scan content — uploads are untrusted input
```

## Pse ka rëndësi

Trajtimi i të dhënave të formularit dhe i ngarkesave të skedarëve është një nevojë e zakonshme, praktike — formularet e hyrjes, ngarkesat e fotografive të profilit, dorëzimet e dokumenteve dhe API-et e përpunimit të skedarëve të gjithë kërkojnë atë, dhe funksionon ndryshe nga trupat JSON që FastAPI përdor si parazgjedhje.

Komprehensioni i `Form()` për fushat e formularit dhe veçanërisht **`UploadFile`** për ngarkesat (qasja e rekomanduar, pasi që ai ndan skedarëve të mëdhenj në disk në vend të ngarkimit të gjithçkaje në memorie — e rëndësishme për trajtimin e skedarëve të mëdhenj pa lodhur RAM-in) është i nevojshëm për këto veçori.

Njësoj i rëndësishëm është **përgjegjësia për siguri** që vjen me ngarkesat: pasi që skedarëve të ngarkuar janë hyrje të pabesme, validimi i llojit dhe madhësisë, dezinfeksioni i emrave të skedarëve dhe kujdesi se si i ruani/i shërbejeni ato është thelbësor për të shmangur dobësitë.

Dija se si të merrni fushat e formularit, si të trajtoni ngarkesat e vetme dhe të shumtë skedarësh, si të kombinoni formulare me skedarë dhe si të validoni ngarkesat me siguri është njohuri praktike për ndërtimin e API-eve të botës reale që pranojnë përmbajtje të paraqitur nga përdoruesit.