FastAPIでクエリパラメータとスキーマをマスターする

FastAPIとクエリパラメータ

FastAPIは、Pythonの非常に高速な（高性能）、使いやすい、モダンな、高速（高性能）なWebフレームワークです。それは非常に直感的で簡単に使うことができ、強力な機能を持っています。その一つがクエリパラメータの取り扱いです。

クエリパラメータは、URLの一部であり、特定の情報をWebサーバーに送信するために使用されます。これらは通常、URLの末尾に?記号の後に追加され、&記号で区切られます。例えば、https://example.com/items?id=5&color=redのようなURLでは、idとcolorはクエリパラメータであり、それぞれ5とredという値を持っています。

FastAPIでは、関数のパラメータとしてクエリパラメータを定義することで、これらのクエリパラメータを簡単に取り扱うことができます。以下に例を示します：

from fastapi import FastAPI

app = FastAPI()

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

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

FastAPIは、クエリパラメータの型を自動的に推測し、適切なバリデーションとドキュメンテーションを提供します。これにより、APIの開発が容易になり、エラーを防ぐことができます。。

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

FastAPIは、クエリパラメータの型変換も自動的に行ってくれます。これは、関数のパラメータとして定義した型に基づいています。以下に例を示します：

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

この例では、read_items関数はqとpageという2つのクエリパラメータを持っています。qは文字列型（str）で、pageは整数型（int）です。これらのパラメータはそれぞれオプショナルで、デフォルト値はNoneと1です。

FastAPIは、クエリパラメータの値を適切な型に自動的に変換します。つまり、URLから取得したpageパラメータの値（文字列）を整数に変換します。これにより、関数内部でpageパラメータを整数として安全に使用することができます。

また、型が一致しない場合や値が不適切な場合（例えば、pageパラメータに文字列"abc"が渡された場合など）は、FastAPIは自動的にHTTP 422エラーを返し、何が問題であるかを詳細に説明したエラーメッセージを提供します。これにより、APIの使用者は問題をすぐに理解し、修正することができます。

このように、FastAPIの型変換機能は、APIの開発を容易にし、エラーを防ぎ、APIの使用者にとっても使いやすいAPIを提供します。。

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

FastAPIは、クエリパラメータのバリデーションも自動的に行ってくれます。これは、関数のパラメータとして定義した型に基づいています。以下に例を示します：

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

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

この例では、read_items関数はqという名前のクエリパラメータを持っています。このパラメータはオプショナルで、デフォルト値はNoneです。しかし、Query関数を使用して、このパラメータに追加のバリデーションルールを設定しています。具体的には、qの長さは最小3文字、最大50文字でなければなりません。

FastAPIは、これらのバリデーションルールを自動的に適用します。つまり、qパラメータの値がこれらのルールに適合しない場合、FastAPIは自動的にHTTP 422エラーを返し、何が問題であるかを詳細に説明したエラーメッセージを提供します。これにより、APIの使用者は問題をすぐに理解し、修正することができます。

このように、FastAPIのバリデーション機能は、APIの開発を容易にし、エラーを防ぎ、APIの使用者にとっても使いやすいAPIを提供します。。

クエリパラメータのデフォルト値の設定

FastAPIでは、クエリパラメータのデフォルト値を簡単に設定することができます。これは、関数のパラメータとして定義したデフォルト値に基づいています。以下に例を示します：

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

この例では、read_items関数はqとpageという2つのクエリパラメータを持っています。qは文字列型（str）で、pageは整数型（int）です。これらのパラメータはそれぞれオプショナルで、デフォルト値はNoneと1です。

FastAPIは、これらのデフォルト値を自動的に適用します。つまり、qやpageパラメータがURLに含まれていない場合、それぞれNoneと1が使用されます。これにより、関数内部でqやpageパラメータを安全に使用することができます。

また、デフォルト値を設定することで、APIの使用者は必要なパラメータをすべて指定しなくてもAPIを使用することができます。これにより、APIの使用者にとっても使いやすいAPIを提供します。。

クエリパラメータとスキーマの実用例

FastAPIを使用してクエリパラメータとスキーマを活用する具体的な例を以下に示します：

from fastapi import FastAPI, Query
from typing import Optional, List

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tags: List[str] = []

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

この例では、read_items関数はqとitemsという2つのクエリパラメータを持っています。qは文字列型（str）で、itemsはItemモデルのリストです。これらのパラメータはそれぞれオプショナルで、デフォルト値はNoneです。

qパラメータには、Query関数を使用して、最小長と最大長のバリデーションルールが設定されています。itemsパラメータは、Itemモデルのリストとして定義されています。Itemモデルは、name（必須）、description（オプショナル）、price（必須）、tags（オプショナル）という4つのフィールドを持っています。

このように、FastAPIを使用すれば、クエリパラメータとスキーマを組み合わせて、より複雑で強力なAPIを簡単に作成することができます。これにより、APIの使用者は、必要なデータを効率的に送受信することができます。。