类似之前的路径参数、查询参数和请求参数,表单与文件也可以算是请求参数中的一员,不过表单与文件更为特殊一些,表单是处理键值对数据、文件则是处理文件数据(图片、音频、视频等文件)。
目录
1 请求表单数据
1.1 表单字段
1.2 Form 使用
2 请求文件
2.1 File 使用
2.2 UploadFile 使用
2.3 更多方式
① 可选文件上传
② 多文件上传
📌源码地址:
https://gitee.com/yinyuu/fast-api_study_yinyu
1 请求表单数据
1.1 表单字段
HTML 表单(<form></form>)向服务器发送数据通常使用「特殊」的编码。
比如👇,包含一个普通输入框和一个密码输入框:
<form action="">
Username: <input type="text" name="username"><br>
Password: <input type="password" name="password">
</form>
FastAPI 的目的是要确保从正确的位置读取数据,而不是读取 JSON。
表单数据的「媒体类型」编码一般为 application/x-www-form-urlencoded。
HTTP 协议规定:可在一个路径操作中声明多个 Form 参数,但不能同时声明接收 JSON 的 Body 字段,此时请求体的编码是 application/x-www-form-urlencoded,而不是不是 application/json。
1.2 Form 使用
如果接口接收的不是 JSON,而是表单字段时,要使用 Form。
预先安装:pip install python-multipart
from fastapi import FastAPI, Form #从 fastapi 导入 Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()): #定义 Form 参数
return {"username": username}
创建表单(Form)参数的方式与 Body 和 Query 一样,也可以使用 default、description、title、gt 等元数据和验证!
OAuth2 规范的 "密码流" 模式规需要通过表单字段发送 username 和 password。 该规范要求字段必须命名为 username 和 password,并通过表单字段发送,不能用 JSON。
2 请求文件
2.1 File 使用
File 用于定义客户端的上传文件。
预先安装:pip install python-multipart
from fastapi import FastAPI, File, UploadFile #从 fastapi 导入 File
app = FastAPI()
@app.post("/files/")
async def create_file(file: bytes = File()): #定义 File 参数
return {"file_size": len(file)}
创建文件(File)参数的方式与 Body 和 Query 一样,也可以使用 default、description、title、gt 等元数据和验证!
此时路径操作函数参数的类型声明为 bytes,FastAPI 将以 bytes 形式读取和接收文件内容。这种方式把文件的所有内容都存储在内存里,适用于小型文件。
上传文件以「表单数据」形式发送,表单包含文件时,编码为 multipart/form-data。使用了 File,FastAPI 就知道要从请求体的正确位置获取文件。
2.2 UploadFile 使用
很多情况下,UploadFile 更好用。
from fastapi import FastAPI, UploadFile #从 fastapi 导入 UploadFile
app = FastAPI()
@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile): #定义文件参数时使用 UploadFile
return {"filename": file.filename}
📌 UploadFile 与 bytes 相比:
- 使用 spooled 文件:存储在内存的文件超出最大上限时,FastAPI 会把文件存入磁盘;
- 这种方式更适于处理图像、视频、二进制文件等大型文件,好处是不会占用所有内存;
- 可获取上传文件的元数据;
📌 UploadFile 属性如下:
- filename:上传文件名字符串(str),例如, myimage.jpg;
- content_type:内容类型(MIME 类型 / 媒体类型)字符串(str),例如,image/jpeg;
- file: SpooledTemporaryFile( file-like 对象)。其实就是 Python文件,可直接传递给其他预期 file-like 对象的函数或支持库。
2.3 更多方式
① 可选文件上传
如果熟悉其他请求参数的话,你可以通过 None 作为默认值将一个文件参数设为可选:
from typing import Union
from fastapi import FastAPI, File, UploadFile
app = FastAPI()
@app.post("/files/")
async def create_file(file: Union[bytes, None] = File(default=None)):
if not file:
return {"message": "No file sent"}
else:
return {"file_size": len(file)}
@app.post("/uploadfile/")
async def create_upload_file(file: Union[UploadFile, None] = None):
if not file:
return {"message": "No upload file sent"}
else:
return {"filename": file.filename}
② 多文件上传
可用同一个「表单字段」发送含多个文件的「表单数据」。
上传多个文件时,要声明含 bytes 或 UploadFile 的列表(List):
from typing import List
from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse
app = FastAPI()
@app.post("/files/")
async def create_files(files: List[bytes] = File()):
return {"file_sizes": [len(file) for file in files]}
@app.post("/uploadfiles/")
async def create_upload_files(files: List[UploadFile]):
return {"filenames": [file.filename for file in files]}
@app.get("/")
async def main():
content = """
<body>
<form action="/files/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
</body>
"""
return HTMLResponse(content=content)
接收的也是含 bytes 或 UploadFile 的列表(list)。