FastAPIのクエリパラメータについて

クエリパラメータとは

クエリパラメータは、URLの一部で、特定の情報をWebサーバーに送信するために使用されます。これらは、URLの末尾にある?記号の後に配置され、&記号で区切られます。例えば、http://example.com/?key1=value1&key2=value2のような形式です。

クエリパラメータは、Webページの内容をフィルタリングしたり、特定の操作をトリガーしたりするために使用されます。これらは、検索クエリ、ページネーション、フィルタリング、ソートなど、さまざまな目的で使用されます。

FastAPIでは、関数のパラメータとしてクエリパラメータを定義することができます。これにより、クエリパラメータの値を簡単に取得し、それを使用して処理を行うことができます。また、FastAPIは、クエリパラメータの型チェックやバリデーションも自動的に行ってくれます。これにより、APIの安全性と堅牢性が向上します。具体的な使用方法については、次の小見出しで詳しく説明します。

クエリパラメータの宣言と使用

FastAPIでは、クエリパラメータは関数のパラメータとして宣言されます。以下に具体的な例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = None):
    return {"q": q}

上記の例では、read_items関数はqという名前のクエリパラメータを持っています。このパラメータはオプショナルで、デフォルト値はNoneです。この関数は、クエリパラメータqの値を含む辞書を返します。

このAPIエンドポイントにアクセスすると、qパラメータを含むクエリを送信することができます。例えば、http://localhost:8000/items/?q=somequeryのようになります。この場合、レスポンスは{"q": "somequery"}となります。

FastAPIは、関数のパラメータの型注釈を使用して、入力データのバリデーション、シリアライゼーション、ドキュメンテーションを自動的に行います。この例では、qはOptional[str]型であるため、Noneまたは文字列のいずれかであることが期待されます。もしクエリパラメータが提供されず、値がNoneである場合でも、FastAPIはエラーを返さずに適切に処理します。

以上がFastAPIでのクエリパラメータの宣言と使用の基本的な方法です。次の小見出しでは、クエリパラメータの型変換について詳しく説明します。

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

FastAPIは、クエリパラメータの型変換も自動的に行ってくれます。これは、関数のパラメータに型注釈を付けることで可能になります。以下に具体的な例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = None, price: float = 0.0):
    return {"q": q, "price": price}

上記の例では、read_items関数はqとpriceという2つのクエリパラメータを持っています。qは文字列型（str）で、priceは浮動小数点型（float）です。

このAPIエンドポイントにアクセスすると、qとpriceパラメータを含むクエリを送信することができます。例えば、http://localhost:8000/items/?q=somequery&price=9.99のようになります。この場合、レスポンスは{"q": "somequery", "price": 9.99}となります。

FastAPIは、クエリパラメータの値を適切な型に自動的に変換します。この例では、priceパラメータの値は文字列から浮動小数点数に変換されます。もし無効な値（例えば、数値ではない文字列）が提供された場合、FastAPIは詳細なエラーメッセージを含む400 Bad Requestレスポンスを自動的に返します。

以上がFastAPIでのクエリパラメータの型変換の基本的な方法です。次の小見出しでは、オプショナルなクエリパラメータについて詳しく説明します。

オプショナルなクエリパラメータ

FastAPIでは、クエリパラメータをオプショナル（つまり、必須ではない）として宣言することができます。これは、関数のパラメータにOptional型注釈を使用することで可能になります。以下に具体的な例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = None):
    return {"q": q}

上記の例では、read_items関数はqという名前のクエリパラメータを持っています。このパラメータはOptional[str]型であるため、Noneまたは文字列のいずれかであることが期待されます。デフォルト値はNoneです。

このAPIエンドポイントにアクセスすると、qパラメータを含むクエリを送信することができます。例えば、http://localhost:8000/items/?q=somequeryのようになります。この場合、レスポンスは{"q": "somequery"}となります。

もしqパラメータが提供されなかった場合、その値はデフォルトのNoneとなります。したがって、http://localhost:8000/items/へのリクエストは{"q": null}というレスポンスを返します。

以上がFastAPIでのオプショナルなクエリパラメータの基本的な使用方法です。次の小見出しでは、複数のパスパラメータとクエリパラメータについて詳しく説明します。

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

FastAPIでは、複数のパスパラメータとクエリパラメータを同時に使用することができます。以下に具体的な例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

上記の例では、read_item関数はitem_idという名前のパスパラメータと、qという名前のクエリパラメータを持っています。item_idは整数型（int）で、qはオプショナルな文字列型（Optional[str]）です。

このAPIエンドポイントにアクセスすると、item_idパラメータを含むパスと、qパラメータを含むクエリを送信することができます。例えば、http://localhost:8000/items/5?q=somequeryのようになります。この場合、レスポンスは{"item_id": 5, "q": "somequery"}となります。

FastAPIは、パスパラメータとクエリパラメータの値を適切な型に自動的に変換します。この例では、item_idパラメータの値は文字列から整数に、qパラメータの値は文字列（またはNone）に変換されます。

以上がFastAPIでの複数のパスパラメータとクエリパラメータの基本的な使用方法です。これらの概念を理解することで、より複雑なAPIエンドポイントを設計し、実装することが可能になります。次の小見出しでは、さらに詳細な情報を提供します。