クエリパラメータ¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

パスパラメータではない関数パラメータを宣言すると、それらは自動的に「クエリ」パラメータとして解釈されます。

Python 3.9+

from fastapi import FastAPI

app = FastAPI()

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内で ? の後に続くキーとバリューの組で、 & で区切られています。

例えば、以下の様なURL内で:

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

...クエリパラメータは:

skip: 値は 0
limit: 値は 10

これらはURLの一部なので、「自然に」文字列になります。

しかしPythonの型を宣言すると (上記の例では int として)、その型に変換されバリデーションが行われます。

パスパラメータに適用される処理と完全に同様な処理がクエリパラメータにも施されます:

エディターサポート (明らかに)
データ「解析」
データバリデーション
自動ドキュメント生成

デフォルト¶

クエリパラメータはパスの固定部分ではないので、オプショナルとしたり、デフォルト値をもつことができます。

上述の例では、skip=0 と limit=10 というデフォルト値を持っています。

したがって、以下のURLにアクセスすることは:

http://127.0.0.1:8000/items/

以下のURLにアクセスすることと同等になります:

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

しかし、例えば、以下にアクセスすると:

http://127.0.0.1:8000/items/?skip=20

関数内のパラメータの値は以下の様になります:

skip=20: URL内にセットしたため
limit=10: デフォルト値だったため

オプショナルなパラメータ¶

同様に、デフォルト値を None とすることで、オプショナルなクエリパラメータを宣言できます:

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

この場合、関数パラメータ q はオプショナルとなり、デフォルトでは None になります。

確認

パスパラメータ item_id はパスパラメータであり、q はそれとは違ってクエリパラメータであると判別できるほどFastAPI が賢いということにも注意してください。