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

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

FastAPIは、Pythonの非常に高速で使いやすいモダンなWebフレームワークです。クエリパラメータは、URLの一部として送信される追加の情報で、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のようなリクエストを受け取ると、qの値somequeryがread_items関数に渡されます。その結果、レスポンスとして{"query": "somequery"}が返されます。

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 {"query": q, "minimum_price": price}

この例では、priceという名前のクエリパラメータを定義しています。このパラメータはfloat型で、デフォルト値は0.0です。

型変換の動作

上記の例では、/items/?q=somequery&price=100.5のようなリクエストを受け取ると、qの値somequeryとpriceの値100.5がread_items関数に渡されます。その結果、レスポンスとして{"query": "somequery", "minimum_price": 100.5}が返されます。

FastAPIは、クエリパラメータの型が指定されている場合、その型に基づいて適切な型変換を行います。この例では、priceパラメータはfloat型として定義されているため、リクエストから受け取った文字列をfloat型に変換します。

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

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

FastAPIでは、クエリパラメータを必須またはオプショナルに設定することができます。これにより、APIの柔軟性と堅牢性を向上させることができます。

必須のクエリパラメータ

必須のクエリパラメータは、関数の引数として定義され、デフォルト値が設定されていません。以下に例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

この例では、qという名前のクエリパラメータを定義しています。このパラメータは必須で、デフォルト値が設定されていません。したがって、qパラメータなしでこのエンドポイントを呼び出すと、FastAPIはエラーレスポンスを返します。

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

オプショナルなクエリパラメータは、関数の引数として定義され、デフォルト値が設定されています。以下に例を示します。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

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

この例では、qという名前のクエリパラメータを定義しています。このパラメータはオプショナルで、デフォルト値はNoneです。したがって、qパラメータなしでこのエンドポイントを呼び出しても、FastAPIはエラーレスポンスを返さず、qの値としてNoneを使用します。

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

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

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}

この例では、qという名前のクエリパラメータを定義しています。このパラメータはオプショナルで、デフォルト値はNoneです。また、Query関数を使用して、qの値が最小3文字、最大50文字になるようにバリデーションを設定しています。

バリデーションの動作

上記の例では、/items/?q=somequeryのようなリクエストを受け取ると、qの値somequeryがread_items関数に渡されます。その結果、レスポンスとして{"query": "somequery"}が返されます。

しかし、qの値が3文字未満または50文字を超える場合、FastAPIはエラーレスポンスを返します。これにより、APIは不適切な入力を防ぐことができます。

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

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

FastAPIでは、複数のパスパラメータとクエリパラメータを同時に扱うことができます。これにより、APIの柔軟性と堅牢性を向上させることができます。

パスパラメータとクエリパラメータの定義

以下に、パスパラメータとクエリパラメータを同時に使用する例を示します。

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

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

この例では、item_idという名前のパスパラメータと、qという名前のクエリパラメータを定義しています。item_idは必須のパスパラメータで、qはオプショナルなクエリパラメータです。

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

上記の例では、/items/5?q=somequeryのようなリクエストを受け取ると、item_idの値5とqの値somequeryがread_item関数に渡されます。その結果、レスポンスとして{"item_id": 5, "query": "somequery"}が返されます。

FastAPIは、パスパラメータとクエリパラメータの存在、型、デフォルト値、必須性などを自動的に処理します。これにより、開発者はビジネスロジックに集中することができます。

以上がFastAPIの複数のパスパラメータとクエリパラメータの扱い方です。次のセクションでは、FastAPIの自動ドキュメント生成機能とクエリパラメータについて詳しく説明します。

FastAPIの自動ドキュメント生成機能とクエリパラメータ

FastAPIは、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, title="Query string", description="Query string for the items to search in the database that have a good match")):
    return {"query": q}

この例では、qという名前のクエリパラメータを定義しています。このパラメータはオプショナルで、デフォルト値はNoneです。また、Query関数を使用して、qのタイトルと説明を設定しています。

自動ドキュメント生成の動作

上記の例では、FastAPIの自動ドキュメント生成機能を使用すると、qパラメータのタイトルと説明がドキュメントに表示されます。これにより、APIのエンドポイントとそのパラメータの目的をユーザーに明確に伝えることができます。

FastAPIの自動ドキュメント生成機能は、クエリパラメータだけでなく、パスパラメータやリクエストボディなど、APIのすべての部分に対して使用することができます。

以上がFastAPIの自動ドキュメント生成機能とクエリパラメータの基本的な使い方です。これらの知識を活用することで、効率的で堅牢なAPIを開発することができます。