FastAPIのクエリパラメータ: 完全ガイド

FastAPIとクエリパラメータの基本

FastAPIは、Pythonの非常に高速（高性能）、使いやすい、モダンな、高速（クイック）なWebフレームワークです。それは非常に直感的で簡単に使うことができます。

クエリパラメータは、URLの一部として送信される追加の情報です。これらは、?記号の後にキーと値のペアとして追加されます。例えば、https://example.com/items?id=5のURLでは、id=5がクエリパラメータです。

FastAPIでは、関数のパラメータとしてクエリパラメータを定義することができます。これにより、FastAPIは自動的にリクエストからこれらのパラメータを抽出し、関数に渡します。

以下に、FastAPIを使用してクエリパラメータを定義する基本的な例を示します。

from fastapi import FastAPI

app = FastAPI()

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

上記のコードでは、qという名前のクエリパラメータを定義しています。このパラメータはオプショナルで、デフォルト値はNoneです。ユーザーが/items/?q=somequeryのようなURLでリクエストを送ると、qの値が"somequery"に設定され、この値がread_items関数に渡されます。

以上がFastAPIとクエリパラメータの基本的な使い方です。次のセクションでは、クエリパラメータの型変換について詳しく説明します。

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

FastAPIは、クエリパラメータの型変換も自動的に行ってくれます。Pythonの型ヒントを使用して、関数のパラメータの型を指定するだけで、FastAPIは適切な型にパラメータを変換します。

以下に、FastAPIを使用してクエリパラメータの型変換を行う基本的な例を示します。

from fastapi import FastAPI

app = FastAPI()

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

上記のコードでは、qという名前の文字列型のクエリパラメータと、priceという名前の浮動小数点型のクエリパラメータを定義しています。ユーザーが/items/?q=somequery&price=9.99のようなURLでリクエストを送ると、qの値が"somequery"に、priceの値が9.99に設定され、これらの値がread_items関数に渡されます。

FastAPIは、以下のような様々な型のクエリパラメータの型変換をサポートしています。

文字列 (str)
整数 (int)
浮動小数点数 (float)
ブール値 (bool)

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

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

FastAPIでは、クエリパラメータを必須またはオプショナルに設定することができます。これは関数のパラメータのデフォルト値を設定することで行います。

以下に、FastAPIを使用して必須とオプショナルなクエリパラメータを定義する基本的な例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

上記のコードでは、qという名前のクエリパラメータは必須で、priceという名前のクエリパラメータはオプショナルです。ユーザーが/items/?q=somequeryのようなURLでリクエストを送ると、qの値が"somequery"に設定され、priceの値はデフォルトのNoneが設定され、これらの値がread_items関数に渡されます。

必須のクエリパラメータは、ユーザーがリクエストを送る際に必ず指定しなければならないパラメータです。指定されていない場合、FastAPIはエラーレスポンスを返します。

一方、オプショナルのクエリパラメータは、ユーザーがリクエストを送る際に指定することも、指定しないこともできます。指定されていない場合、デフォルト値が使用されます。

以上がFastAPIと必須とオプショナルなクエリパラメータについての基本的な説明です。次のセクションでは、複数のクエリパラメータの扱いについて詳しく説明します。

複数のクエリパラメータの扱い

FastAPIでは、複数のクエリパラメータを同時に扱うことができます。これは関数のパラメータとして複数のクエリパラメータを定義することで行います。

以下に、FastAPIを使用して複数のクエリパラメータを定義する基本的な例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

上記のコードでは、qという名前のクエリパラメータ、priceという名前のクエリパラメータ、limitという名前のクエリパラメータを定義しています。ユーザーが/items/?q=somequery&price=9.99&limit=10のようなURLでリクエストを送ると、qの値が"somequery"に、priceの値が9.99に、limitの値が10に設定され、これらの値がread_items関数に渡されます。

FastAPIは、複数のクエリパラメータを同時に扱うことができ、それぞれのクエリパラメータは独立して動作します。これにより、非常に柔軟なAPIの設計が可能になります。

以上がFastAPIと複数のクエリパラメータの扱いについての基本的な説明です。次のセクションでは、クエリパラメータのバリデーションについて詳しく説明します。

クエリパラメータのバリデーション

FastAPIは、クエリパラメータのバリデーションも自動的に行ってくれます。Pythonの型ヒントを使用して、関数のパラメータの型を指定するだけで、FastAPIは適切な型にパラメータを変換し、型が正しくない場合はエラーレスポンスを返します。

また、FastAPIはPydanticモデルを使用して、より高度なバリデーションを行うことも可能です。Pydanticモデルでは、フィールドのデフォルト値を設定することで、そのフィールドが必須かオプショナルかを指定することができます。さらに、各フィールドに対してバリデーションルールを設定することも可能です。

以下に、FastAPIとPydanticを使用してクエリパラメータのバリデーションを行う基本的な例を示します。

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = Query(..., min_length=3, max_length=50), price: Optional[float] = Query(None, gt=0)):
    return {"query": q, "price": price}

上記のコードでは、qという名前のクエリパラメータは必須で、その長さは3文字以上50文字以下でなければならないことを指定しています。また、priceという名前のクエリパラメータはオプショナルですが、指定された場合、その値は0より大きいことを指定しています。

以上がFastAPIとクエリパラメータのバリデーションについての基本的な説明です。次のセクションでは、FastAPIにおけるクエリパラメータのベストプラクティスについて詳しく説明します。

FastAPIにおけるクエリパラメータのベストプラクティス

FastAPIを使用してAPIを設計する際のクエリパラメータのベストプラクティスは以下の通りです。

明確な命名: クエリパラメータの名前は、その目的を明確に表すように選びましょう。これにより、APIの利用者はパラメータの目的を理解しやすくなります。
型ヒントの使用: Pythonの型ヒントを使用して、クエリパラメータの期待される型を明示しましょう。これにより、FastAPIは自動的に型チェックと型変換を行ってくれます。
デフォルト値の設定: クエリパラメータがオプショナルである場合、適切なデフォルト値を設定しましょう。これにより、パラメータが指定されていない場合の挙動を制御することができます。
バリデーションの追加: PydanticのQueryクラスを使用して、クエリパラメータにバリデーションルールを追加しましょう。これにより、不適切なパラメータ値を早期に検出し、エラーレスポンスを返すことができます。
ドキュメンテーションの記述: FastAPIは自動的にAPIのドキュメンテーションを生成しますが、クエリパラメータの説明を追加することで、ドキュメンテーションをさらに充実させることができます。

以上がFastAPIにおけるクエリパラメータのベストプラクティスです。これらのプラクティスを適用することで、より使いやすく、保守性の高いAPIを設計することができます。