FastAPI subida de archivos
FastAPI proporcionaFileyUploadFileDos formas de manejar la subida de archivos, que admiten subir archivos individuales y una mezcla de formularios y archivos.
Instalar dependencias
La subida de archivos también depende depython-multipart:
pip install python-multipart
Usar UploadFile
UploadFileEs la forma recomendada, ya que proporciona una interfaz más rica para acceder a la información del archivo:
Ejemplo
app = FastAPI()
@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
# Atributos y métodos proporcionados por UploadFile
return {
"filename": file.filename, # Nombre del archivo
"content_type": file.content_type, # Tipo MIME del archivo
"size": file.size, # Tamaño del archivo (bytes)
}
UploadFileAtributos y métodos:
| Atributo/Método | Tipo | Descripción |
|---|---|---|
filename | str | None | Nombre original del archivo subido |
content_type | str | None | Tipo MIME del archivo (por ejemplo,image/png) |
file | SpooledTemporaryFile | Objeto similar a un archivo, permite leer el contenido del archivo |
size | int | None | Tamaño del archivo (bytes) |
read() | Método | Lee el contenido del archivo comobytes |
write() | Método | Escribe contenido en el archivo |
seek() | Método | Mueve la posición del puntero del archivo |
close() | Método | Cierra el archivo |
UploadFileUsa "SpooledTemporaryFile" para almacenar el contenido del archivo. Cuando el archivo es pequeño se guarda en memoria, y cuando es grande se escribe automáticamente al disco, por lo que es másbyteseficiente en memoria.
Usar File para recibir el contenido del archivo
FileLee directamente el contenido del archivo comobytes, adecuado para archivos pequeños:
Ejemplo
app = FastAPI()
@app.post("/files/")
async def create_file(file: bytes = File()):
# file son los datos binarios originales del archivo
return {"file_size": len(file)}
FileyUploadFileComparación:
| Elemento de comparación | File | UploadFile |
|---|---|---|
| Tipo de dato | bytes | Objeto de archivo |
| Uso de memoria | Todo el archivo se carga en memoria | Los archivos grandes se escriben automáticamente al disco |
| Información del archivo | Ninguna (solo contenido) | Tiene nombre, tipo y tamaño |
| Escenario de aplicación | Archivos pequeños | Archivos grandes, escenarios que requieren información del archivo |
Subida de archivos opcional
Usar valor predeterminadoNoneHace que la subida de archivos sea opcional:
Ejemplo
app = FastAPI()
@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile | None = None):
if not file:
return {"message": "No se subió ningún archivo"}
return {"filename": file.filename}
Subida de múltiples archivos
Usa una lista para recibir múltiples archivos:
Ejemplo
app = FastAPI()
@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):
return {"filenames": [file.filename for file in files]}
Subida mixta de formularios y archivos
Puedes recibir datos de formulario y archivos en la misma ruta al mismo tiempo:
Ejemplo
app = FastAPI()
@app.post("/items/")
async def create_item(
# Campo de formulario
name: str = Form(...),
description: str | None = Form(None),
# Subida de archivos
file: UploadFile | None = None,
):
result = {"name": name, "description": description}
if file:
result["filename"] = file.filename
return result
Guardar el archivo subido
El siguiente ejemplo muestra cómo guardar el archivo subido en el disco:
Ejemplo
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
# Guarda el archivo subido en la ruta especificada
with open(f"uploads/{file.filename}", "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
return {"filename": file.filename, "message": "Archivo subido exitosamente"}
En proyectos reales, al subir archivos se debe tener en cuenta: 1) Validar el tipo y tamaño del archivo; 2) Usar nombres de archivo seguros (evitar ataques de path traversal); 3) Restringir los permisos del directorio de subida; 4) Para archivos grandes, usar procesamiento por flujo en lugar de leer todo de una vez.
Resumen
- Se recomienda usar
UploadFile, es más eficiente en memoria y proporciona información completa del archivo FileAdecuado para escenarios de archivos pequeños, se lee directamente comobytes- Usar
list[UploadFile]Recibir subida de múltiples archivos - Formulario (
Form) y archivo (UploadFile) se pueden usar en la misma ruta - Al subir archivos, presta atención a la seguridad: valida el tipo de archivo, usa nombres seguros y limita el tamaño