FastAPI クエリパラメータ

クエリパラメータは URL 内の?後に、&クエリパラメータは URL 内の ? の後、& で区切られたキーと値のペアです。関数のパラメータがパスパラメータでもリクエストボディでもない場合、FastAPI はそれを自動的にクエリパラメータとして解釈します。


基本的な使い方

クエリパラメータを宣言するには、関数のパラメータに型注釈とデフォルト値を追加するだけです:

例

from fastapi import FastAPI

app = FastAPI()

# skip と limit はクエリパラメータで、デフォルト値を持ちます
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    # ページネーションクエリのシミュレーション
    return fake_items_db[skip : skip + limit]

クエリパラメータの URL 内での形式:

http://127.0.0.1:8000/items/?skip=0&limit=10

異なるアクセス方法でのパラメータ値:

URLskip の値limit の値説明
/items/010デフォルト値を使用
/items/?skip=202010skip は渡された値を使用し、limit はデフォルト値を使用します
/items/?skip=20&limit=5205両方のパラメータは渡された値を使用します

オプションパラメータ

デフォルト値をNoneに設定するだけで、オプションのクエリパラメータを宣言できます:

例

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    # item_id はパスパラメータ(必須)、q はクエリパラメータ(オプション)です
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

ここでq: str | None = Noneの意味はq文字列またはNone、デフォルト値はNone。

FastAPI はデフォルト値によって= Noneパラメータが必須かどうかを判断し、型注釈によるのではありませんstr | None。型注釈は主にエディタのサポート向上に役立ちます。


クエリパラメータの型変換

FastAPI はクエリパラメータを自動的にbool型に変換できます:

例

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, short: bool = False):
    # short パラメータは自動的にブール値に変換されます
    if short:
        return {"item_id": item_id}
    return {"item_id": item_id, "description": "これはとても長い説明です"}

以下の URL 内のshortパラメータはすべて変換されますTrue:

/items/foo?short=1
/items/foo?short=True
/items/foo?short=true
/items/foo?short=on
/items/foo?short=yes

その他の値は変換されますFalse。


必須クエリパラメータ

デフォルト値を設定しないクエリパラメータが必須パラメータになります:

例

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, needy: str):
    # needy にはデフォルト値がなく、必須クエリパラメータです
    return {"item_id": item_id, "needy": needy}

アクセスしたとき/items/fooに提供されていないneedyパラメータがある場合、FastAPI は以下のようなエラーを返します:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "needy"],
      "msg": "Field required",
      "input": null
    }
  ]
}

必須・デフォルト値あり・オプションのパラメータを混在させる

同じ関数内で異なるタイプのクエリパラメータを混在させることができます:

例

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(
    item_id: str,           # パスパラメータ(必須)
    needy: str,             # 必須クエリパラメータ
    skip: int = 0,          # デフォルト値を持つクエリパラメータ
    limit: int | None = None,  # オプションのクエリパラメータ
):
    item = {"item_id": item_id, "needy": needy, "skip": skip}
    if limit:
        item.update({"limit": limit})
    return item

パラメータ型のまとめ:

パラメータ宣言方法必須かどうか説明
item_iditem_id: str必須パスパラメータ、URL パス内に現れる
needyneedy: str必須クエリパラメータ、デフォルト値なし
skipskip: int = 0オプションクエリパラメータ、デフォルト値 0
limitlimit: int | None = Noneオプションクエリパラメータ、デフォルト値は None

複数のパスパラメータとクエリパラメータ

FastAPI は複数のパスパラメータとクエリパラメータを同時に認識でき、パラメータの宣言順序は認識に影響しません:

例

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int,       # パスパラメータ
    item_id: str,       # パスパラメータ
    q: str | None = None,  # オプションのクエリパラメータ
    short: bool = False,   # デフォルト値を持つクエリパラメータ
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update({"description": "これはとても長い説明です"})
    return item

FastAPI はパラメータ名でパス内の変数を照合するため、関数のパラメータの順序は重要ではありません。


まとめ

クエリパラメータの核心ポイント:

  • デフォルト値があるパラメータはオプションで、デフォルト値がないパラメータは必須です
  • FastAPI は URL 内の文字列を自動的に宣言された型に変換します
  • bool型は複数の書き方をサポートしています(true、1、on、yesなど)
  • クエリパラメータはパスパラメータと混在して使用でき、順序は関係ありません
その他の拡張