フォームデータ¶
AI coding agents
Use the official FastAPI skill for your installed version. Install it from your project directory:
uvx library-skills
See Develop with AI.
🌐 AI と人間による翻訳
この翻訳は、人間のガイドに基づいて AI によって作成されました。🤝
原文の意図を取り違えていたり、不自然な表現になっている可能性があります。🤖
AI LLM をより適切に誘導するのを手伝う ことで、この翻訳を改善できます。
JSONの代わりにフォームフィールドを受け取る場合は、Formを使用します。
Formのインポート¶
fastapiからFormをインポートします:
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
return {"username": username}
Formのパラメータの定義¶
BodyやQueryの場合と同じようにフォームパラメータを作成します:
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
return {"username": username}
例えば、OAuth2仕様が使用できる方法の１つ（「パスワードフロー」と呼ばれる）では、フォームフィールドとしてusernameとpasswordを送信する必要があります。
仕様では、フィールドの名前が正確にusernameとpasswordであることと、JSONではなくフォームフィールドとして送信されることを要求しています。
FormではBody（およびQueryやPath、Cookie）と同じ設定を宣言することができます。これには、バリデーション、例、エイリアス（例えばusernameの代わりにuser-name）などが含まれます。
備考
FormはBodyを直接継承するクラスです。
豆知識
フォームのボディを宣言するには、明示的にFormを使用する必要があります。なぜなら、これを使わないと、パラメータはクエリパラメータやボディ（JSON）パラメータとして解釈されるからです。
ブール型のフォームフィールド¶
ブラウザはHTMLフォームを送信する際、チェックされていないチェックボックスを省略します。チェックされていない場合にFalseを受け取るには、デフォルト値をFalseにしたブール型のフォームパラメータを宣言します:
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/preferences/")
async def update_preferences(subscribe: Annotated[bool, Form()] = False):
return {"subscribe": subscribe}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/preferences/")
async def update_preferences(subscribe: bool = Form(default=False)):
return {"subscribe": subscribe}
チェックされたチェックボックスはその値を送信し、デフォルトの値は"on"です。FastAPIは"on"をTrueとして受け付けます。
「フォームフィールド」について¶
HTMLフォーム（<form></form>）がサーバにデータを送信する方法は、通常、そのデータに「特別な」エンコーディングを使用していますが、これはJSONとは異なります。
FastAPI は、JSONの代わりにそのデータを適切な場所から読み込むようにします。
技術詳細
フォームからのデータは通常、application/x-www-form-urlencodedの「media type」を使用してエンコードされます。
しかし、フォームがファイルを含む場合は、multipart/form-dataとしてエンコードされます。ファイルの扱いについては次の章で説明します。
Form(media_type="multipart/form-data")を使用すると、OpenAPIでマルチパートフォームを記述できます。フォームパラメータやモデルを組み合わせる場合は、１つのパラメータに設定するだけで十分です。
これらのエンコーディングやフォームフィールドの詳細については、MDN の POST のウェブドキュメントを参照してください。
注意
path operationで複数のFormパラメータを宣言することができますが、JSONとして受け取ることを期待しているBodyフィールドを宣言することはできません。なぜなら、リクエストはapplication/jsonの代わりにapplication/x-www-form-urlencodedを使ってボディをエンコードするからです。
これは FastAPIの制限ではなく、HTTPプロトコルの一部です。
まとめ¶
フォームデータの入力パラメータを宣言するには、Formを使用します。