コンテンツへスキップ

クエリパラメータ¶

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

Python 3.8+

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/

次のようにアクセスするのと同じになります

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}

🤓 その他のバージョンとバリアント

Python 3.8+

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 になります。

確認

また、FastAPI は、パスパラメータ item_id がパスパラメータであり、q がそうではないため、クエリパラメータであることに気づくほど賢いことにも注目してください。

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

bool 型も宣言でき、それらは変換されます

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, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

🤓 その他のバージョンとバリアント

Python 3.8+

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, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

この場合、次のようにアクセスすると、

http://127.0.0.1:8000/items/foo?short=1

または

http://127.0.0.1:8000/items/foo?short=True

または

http://127.0.0.1:8000/items/foo?short=true

または

http://127.0.0.1:8000/items/foo?short=on

または

http://127.0.0.1:8000/items/foo?short=yes

またはその他の大文字小文字のバリエーション (大文字、最初の文字を大文字など) の場合、関数はパラメータ short を True の bool 値として認識します。それ以外の場合は False と認識します。

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

複数のパスパラメータとクエリパラメータを同時に宣言できます。FastAPI はどれがどれであるかを認識します。

また、特定の順序で宣言する必要はありません。

それらは名前によって検出されます

Python 3.10+

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": "This is an amazing item that has a long description"}
        )
    return item

🤓 その他のバージョンとバリアント

Python 3.8+

from typing import Union

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: Union[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": "This is an amazing item that has a long description"}
        )
    return item

必須クエリパラメータ¶

パスパラメータではないパラメータ (これまではクエリパラメータしか見ていません) にデフォルト値を宣言すると、それは必須ではありません。

特定の値を追加したくないが、単にオプションにしたい場合は、デフォルトを None に設定します。

しかし、クエリパラメータを必須にしたい場合は、デフォルト値を宣言しないだけで済みます。

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    item = {"item_id": item_id, "needy": needy}
    return item

ここで、クエリパラメータ needy は、型 str の必須クエリパラメータです。

ブラウザで次のような URL を開くと、

http://127.0.0.1:8000/items/foo-item

...必須パラメータ needy を追加しないと、次のようなエラーが表示されます。

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

needy は必須パラメータなので、URL で設定する必要があります。

http://127.0.0.1:8000/items/foo-item?needy=sooooneedy

...これでうまくいきます。

{
    "item_id": "foo-item",
    "needy": "sooooneedy"
}

もちろん、一部のパラメータを必須とし、一部にデフォルト値を設定し、一部を完全にオプションとすることもできます。

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: int | None = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

🤓 その他のバージョンとバリアント

Python 3.8+

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: Union[int, None] = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

この場合、3 つのクエリパラメータがあります。

needy、必須の str。
skip、デフォルト値が 0 の int。
limit、オプションの int。

ヒント

パスパラメータと同じように、Enum を使用することもできます。