クエリパラメータの基本
FastAPIでは、クエリパラメータは関数の引数として定義されます。これらの引数は自動的にクエリパラメータとして認識され、その型に基づいてバリデーションが行われます。
例えば、以下のようにitem_idというクエリパラメータを持つエンドポイントを定義することができます。
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(item_id: int):
return {"item_id": item_id}
このエンドポイントはhttp://localhost:8000/items/?item_id=5のようにアクセスすることで、item_idの値を取得することができます。
FastAPIは、関数の引数を見て、それがパスパラメータかクエリパラメータかを自動的に判断します。関数の引数がパスに存在しない場合、それはクエリパラメータとして扱われます。
以上がFastAPIにおけるクエリパラメータの基本的な使い方です。次のセクションでは、クエリパラメータの型変換について詳しく説明します。
クエリパラメータの型変換
FastAPIでは、クエリパラメータの型変換も自動的に行われます。関数の引数として定義した型に基づいて、適切な型に変換されます。
例えば、以下のようにitem_idというクエリパラメータを整数型で定義した場合、文字列で送られてきたクエリパラメータは整数に変換されます。
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(item_id: int):
return {"item_id": item_id}
このエンドポイントはhttp://localhost:8000/items/?item_id=5のようにアクセスすることで、item_idの値を取得することができます。ここで、item_idは文字列の”5″ではなく、整数の5として扱われます。
また、FastAPIはクエリパラメータの型が適切でない場合には、自動的にエラーレスポンスを返します。これにより、APIの使用者は何が問題であるかをすぐに理解することができます。
以上がFastAPIにおけるクエリパラメータの型変換についての説明です。次のセクションでは、オプショナルなクエリパラメータについて詳しく説明します。
オプショナルなクエリパラメータ
FastAPIでは、クエリパラメータをオプショナル（つまり、必須でない）として定義することができます。これは、特定のパラメータが必ずしも必要でない場合や、パラメータが提供されなかった場合にデフォルト値を使用したい場合に便利です。
オプショナルなクエリパラメータを定義するには、PythonのOptional型を使用します。以下に例を示します。
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(item_id: Optional[int] = None):
return {"item_id": item_id}
このエンドポイントはhttp://localhost:8000/items/?item_id=5のようにアクセスすることで、item_idの値を取得することができます。しかし、item_idパラメータが提供されなかった場合でも、エンドポイントはエラーを返さずに動作します。その場合、item_idの値はNoneになります。
以上がFastAPIにおけるオプショナルなクエリパラメータの使い方についての説明です。次のセクションでは、デフォルト値を持つクエリパラメータについて詳しく説明します。
デフォルト値を持つクエリパラメータ
FastAPIでは、クエリパラメータにデフォルト値を設定することができます。これは、特定のパラメータが提供されなかった場合に、そのデフォルト値を使用することを意味します。
デフォルト値を持つクエリパラメータを定義するには、関数の引数にデフォルト値を設定します。以下に例を示します。
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(item_id: int = 0):
return {"item_id": item_id}
このエンドポイントはhttp://localhost:8000/items/?item_id=5のようにアクセスすることで、item_idの値を取得することができます。しかし、item_idパラメータが提供されなかった場合でも、エンドポイントはエラーを返さずに動作します。その場合、item_idの値はデフォルトの0になります。
以上がFastAPIにおけるデフォルト値を持つクエリパラメータの使い方についての説明です。次のセクションでは、必須のクエリパラメータについて詳しく説明します。
必須のクエリパラメータ
FastAPIでは、クエリパラメータを必須として定義することができます。これは、特定のパラメータが必ず提供されることを要求する場合に使用します。
必須のクエリパラメータを定義するには、関数の引数を設定し、デフォルト値を設定しないことで実現できます。以下に例を示します。
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(item_id: int):
return {"item_id": item_id}
このエンドポイントはhttp://localhost:8000/items/?item_id=5のようにアクセスすることで、item_idの値を取得することができます。しかし、item_idパラメータが提供されなかった場合、FastAPIはエラーレスポンスを返します。これにより、APIの使用者は何が問題であるかをすぐに理解することができます。
以上がFastAPIにおける必須のクエリパラメータの使い方についての説明です。次のセクションでは、複数のパスパラメータとクエリパラメータについて詳しく説明します。
複数のパスパラメータとクエリパラメータ
FastAPIでは、複数のパスパラメータとクエリパラメータを同時に扱うことができます。これは、エンドポイントが複数のパラメータを必要とする場合や、エンドポイントが柔軟に動作する必要がある場合に便利です。
以下に、複数のパスパラメータとクエリパラメータを持つエンドポイントの例を示します。
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_items(item_id: int, q: Optional[str] = None):
return {"item_id": item_id, "q": q}
このエンドポイントはhttp://localhost:8000/items/5?q=somequeryのようにアクセスすることで、item_idとqの値を取得することができます。ここで、item_idはパスパラメータ、qはクエリパラメータです。
FastAPIは、関数の引数を見て、それがパスパラメータかクエリパラメータかを自動的に判断します。関数の引数がパスに存在する場合、それはパスパラメータとして扱われます。存在しない場合、それはクエリパラメータとして扱われます。
以上がFastAPIにおける複数のパスパラメータとクエリパラメータの使い方についての説明です。これらの知識を活用して、より柔軟で強力なAPIを設計することができます。次のセクションでは、さらに詳細なFastAPIの機能について説明します。