FastAPI パスパラメータ

パスパラメータは URL パス内の動的な部分であり、波括弧を使用して{}宣言します。FastAPI はパスパラメータを自動的にパス操作関数に渡し、型アノテーションに基づいてデータ変換と検証を行います。


基本的な使い方

Python のフォーマット文字列構文を使用してパスパラメータを宣言します:

例

from fastapi import FastAPI

app = FastAPI()

# {item_id} はパスパラメータです
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

アクセスhttp://127.0.0.1:8000/items/5すると、戻り値:

{"item_id": 5}

返り値がitem_id整数である5、文字列ではないことに注意してください"5"。FastAPI は型アノテーションを通じてitem_id: intURL 内の文字列を整数に自動変換します。


データ変換

型をintと宣言すると、FastAPI は自動的に型変換を行います:

# 传入整数,正常工作
GET /items/3       -> {"item_id": 3}

# 传入非整数,返回校验错误
GET /items/foo     -> 错误:Input should be a valid integer

# 传入浮点数,同样报错
GET /items/4.2     -> 错误:Input should be a valid integer

アクセスhttp://127.0.0.1:8000/items/fooすると、FastAPI が返す検証エラーメッセージ:

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["path", "item_id"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

FastAPI の検証エラーメッセージは非常に明確で、具体的なエラー位置(loc)、エラータイプ(type)、エラーの説明(msg)を示します。これはデバッグの際に非常に役立ちます。


パスパラメータの型

以外にもintint

、他の標準 Python 型を使用できます:型説明
strURL 例/items/foo
int文字列(デフォルト型)/items/5
float整数/items/5.5
bool浮動小数点数/items/true
uuid.UUIDUUID/items/3fa85f64-5717-4562-b3fc-2c963f66afa6

パスの順序は重要

パスの順序は重要

例

from fastapi import FastAPI

app = FastAPI()

例
@app.get("/users/me")
async def read_user_me():
    # /users/{user_id} の前に定義する必要があります
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    """現在のユーザー情報を取得"""
    return {"user_id": user_id}

"""ID に基づいてユーザー情報を取得"""/users/meもし/users/{user_id}/users/me/users/meを"me"であるuser_id/users/{user_id}

の後に置いた場合、


プリセット値のパスパラメータ(Enum)

にアクセスすると、FastAPI はEnumuser_id

例

from enum import Enum
from fastapi import FastAPI


固定パスのルートは必ず動的パスパラメータのルートより前に定義してください。そうしないと、動的パラメータが固定パスの値を「飲み込んで」しまいます。
class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    プリセット値のパスパラメータ(Enum)
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

パスパラメータを特定の固定値のみに制限する必要がある場合は、Python の

Enum型を使用できます:
例str# 列挙クラスを作成し、str と Enum を継承
# 列挙メンバーと比較可能Enum列挙クラスのポイント:
model_name.valueポイント"alexnet")

説明http://127.0.0.1:8000/models/alexnetstr を継承

{"model_name": "alexnet", "message": "Deep Learning FTW!"}

API ドキュメントが値の型を文字列として認識し、正しくレンダリングされるようにします/models/foobarEnum を継承alexnet、resnet、lenet。


パスを含むパスパラメータ

列挙メンバーの実際の値を取得します(例:

例

from fastapi import FastAPI

app = FastAPI()

)
@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

アクセスhttp://127.0.0.1:8000/files/home/johndoe/myfile.txtすると、戻り値:

{"file_path": "home/johndoe/myfile.txt"}

プリセット以外の値を渡すと(例:/files/と/home/)、FastAPI は検証エラーを返し、選択可能な値は//パスを含むパスパラメータ/パスパラメータ自体がパス(ファイルパスなど)を含む必要がある場合は、Starlette のパスコンバータを使用します:


まとめ

# :path は、このパラメータがスラッシュを含むパスにマッチできることを示します

  • アクセスすると、戻り値:
  • URL 内のの間に二重スラッシュが現れることに注意してください
  • これは正常です。なぜならパスパラメータが/
  • で始まるからです。まとめ
Python 標準の型宣言により、FastAPI パスパラメータは同時に次のものを得られます: